Feature: Map Editor - [merged]

[benloh]

Merges dev-bl/mapeditor -> dev

This implements a rudimentary Map Editor so that users can define the number of instances and initial properties for a given model.

How This Works

A few key points:

• Map Editor is running its own PanelSimulation where the actual simulation is housed and run. This means if you also have a Mission Control open, that Mission Control is running a different simulation.

• Instances are being defined behind the scenes via init scripts tied to the model. Each instance has its own init script. init scripts are written in ScriptText, but the UI provides a way to set the property parameters. Currently this only supports setting x and y.

• When you add a new instance, an instance definition is created automatically and pre-populated with an init script that defines x and y positions.

• Currently only single numerical prop assignments are supported. We still need to add support for type checking to support strings and expressions.

• You can add multiple instances by clicking repeatedly on a blueprint. Each instance added will randomly offset around the center of the screen, but generally not exactly on top of each other so you can find the new instance.

• Currently the data is only saved while the Map Editor browser is opened. It is not saved to disk. If you develop a map that you would like to keep you need to copy the values to the your model's instances definition, e.g. gs_packages/gem-srv/src/app/data/aquatic.js.

• This Script JSX Call Order Whimsical diagram shows how the UI is rendered and updated.

To Test

1. Check out dev-bl/mapeditor
2. npm run bootstrap && npm run gem
3. Open a Map Editor page with the aquatic model: http://localhost/app/mapeditor?model=aquatic
4. You should see 3 fish and 4 algae defined and displayed on the screen.
5. The starting instances are defined in gs_packages/gem-srv/src/app/data/aquatic.js in the instances array.

To Add a New Instance

1. Click on a blueprint button in the "ADD BLUEPRINTS" panel to add a new instance.
2. A new agent should appear approximately in the center of the screen.
3. Click on the blueprint button again and a second instance will appear, with slight random offset.

To Edit an Instance

1. Click the instance in the "MAP INSTANCES" panel to Edit it.
2. Type any number.
3. Hit "Enter" to assign the value and force a screen update. You should see the agent move to a new location.
4. Select another instance and change the value.
5. Hit "Tab" to change focus and force update.
6. Select another instance and change the value.
7. Click anywhere on the instance to force an update.
8. Select another instance and change the value.
9. Select another instance to force the update.
10. Try typing non-numeric characters -- you shouldn't be allowed to.
11. Try directly dragging an instance -- you should see the parameters update when you drop the instance.

Still To Do

This is more of a proof of concept than anything. There are still many significant features and systems to build.

• Integration into Mission Control -- Map Editor currently loads as a separate page from Mission Control and keeps its own separate copy of a simulation. Once we have the basic functionality worked out. we can integrate the Map Editor features into Mission Control.

• "Places" Phase -- Currently we are using a hack to display the initial state of the simulation by basically running it for 250ms. This means that a few ticks of the update loop might run before you see the display, which could result in agents moving or entering unexpected states (e.g. Fish goes hungry because energyLevel goes down by 1 after 1 tick). Once we have a proper "Places!" phase this will no longer be a problem. ("Places" comes from the theatre world -- the director calls "Places" to tell actors to get into position and stage hands to arrange the set).

• Move SimData to Server -- The SimData module is currently loaded by PanelSimulation and resides in the browser. So all data is lost when the session is over. The module needs to be re-implemented as a server module that either connects to a back end database and/or exports to a file.

• Testing the init scripts -- Currently you can't test the int scripts within the Map Editor. But if you keep a Mission Control page open while you edit the Map, the Mission Control will receive the model updates. You can then run the sim in Mission Control. Note that triggering a run in Mission Control will also trigger a run in the Map Editor, though both simulations will run independently of each other. Of course once we integrate Map Editor into Mission Control this won't be necessary anymore.

• Add support for other keywords (e.g. 'featCall', featProp, etc)

• Expressions and Multiple Argument Properties -- Currently only single parameter functions are supported. Other keywords will need to support multiple parameters.

• Add Additional Property/Feature calls to the init script -- Currently you can only start with the properties that are already defined. A proper UI would allow you to add new properties to set.

• Selected Agent Visual Indicator -- There is no visual indicator of which agent you are currently editing. It would be nice to highlight the agent if you have the instance editor in edit mode.

• Add multiple instances programmatically

...and many more...

Known Issues

• [ ] Init Script Cleaning -- We are assuming that the init script is NOT hand-coded, but is in fact system generated. So we are not doing any validation or script cleaning on the code. As a result, things like extra whitespaces, bad keywords, and blank lines may cause unexpected behavior and errors.

See #18 for Design Discussion.

[benloh]

@daveseah Please review and suggest edits, or accept if it works. No rush.

[benloh]

added 1 commit

• 853c2135 - mapeditor: Change MapEditor PLACES hook from `UR/APP_START` to `SIM/LOAD_ASSETS`

Compare with previous version

[benloh]

added 1 commit

• 3e66c183 - mapeditor: Fix SimData add instance method to use simpler prop reference ('x',...

Compare with previous version

[benloh]

In GitLab by @daveseah on Mar 4, 2021, 15:07

@benloh it seems to compile and run! Accepting merge.

[benloh]

In GitLab by @daveseah on Mar 4, 2021, 15:07

mentioned in commit 8f23b7b6a932fea787a43af4d34389090b994c29

[benloh]

In GitLab by @jdanish on Mar 6, 2021, 06:57

Awesome. Two quick comments: 1) I don't think we need to add multiple instances programatically. It can happen via normal script operations once we have spawn, but I don't see any benefit in complicating the current screen / process which works nicely.

2) One thing I noticed in my tinkering is that the sim in the mapeditor will, at some points, run. That is, fish start getting hungry and eventually die. I assume we don't want this to run as it makes it really confusing when trying to determine what you are putting and where it'll be ? I realize this might be a bug or not yet implemented but wanted to comment in case it wasn't on your radar.

Looking forward to seeing what's next!

[benloh]

Thanks for testing, Joshua.

1. Multiple instance UI: Great! I'll just leave things as-is and if we decide we need to add one later we will.

2. Inadvertent runs: This was a temporary hack to get things to show up when the map editor first loads: we basically ran the sim for a fraction of a second. It has now been properly implemented with !56.

[benloh]

In GitLab by @jdanish on Mar 6, 2021, 10:04

Awesome. Should have known you’d be one step ahead.