Script Wizard GUI - [merged] #637

Closed benloh closed 1 year ago

In GitLab by @daveseah on Apr 12, 2022, 07:30

Merges dev-next-gui -> dev-next

Branch: dev-next-gui

At long last! The much anticipated Script Wizard UI is here!

This is still a little rough around the edges, so we expect it'll take a few rounds to iron things out.

screenshot_1054

TLDR;

Reporting Issues

A poorly reported issue can sometimes take us an hour to reproduce and figure out what's going on. Given that we are already running on fumes, please please please take care in reporting any issues. The more time we spend trying to figure out what a problem is, the less time we have to work on the system.

Ideally you would:

Create a video that shows how you generated the error
Create a new issue in GitLab
Write down the exact steps we can take to replicate the error, paying special attention to:

which branch/commit you're running
which project you loaded, including name and commit in art-assets (and if it's not in art-assets, include a copy of the gemproj file)
describe the steps you took
describe the error you saw
describe what you expected to see
attach a video of the error (a dropbox or box link will suffice) -- or at the very least a screenshot

Significant Changes

Even though on the surface things look pretty much the same, there have been VERY significant changes to all aspects of the system, so a very thorough QA test is needed.

If you read nothing else, make sure you read this list!

agent Blueprint references -- All object references now require explicit reference to the character type. e.g. prop energyLevel setTo 5 should now be prop agent.energyLevel setTo 5 or prop Bee.energyLevel setTo 5. This is so object references are consistent across when and non-when clauses. In most cases you can just use agent to refer to the current agent context. For when scripts, you need to explicitly refer to a particular type of agent (e.g. Moth vs Tree). You'll notice in most scripts, the prop lines will have errors: this is because the property name needs to have agent added to them in order to be valid. You'll need to fix this in most existing projects: just add agent to the property and feature selectors outside of when conditions. Inside of when make sure you select the appropriate agent type (e.g. Bee, Algae, etc.) See !243.
# directives -- For the most part, students should not be adding or editing directives. These are now inserted automatically by the system. If your project is missing directives, the system will automatically insert them when you next open the project. See !242.
useFeature is now addFeature -- We renamed it so it is more consistent with other keywords. useFeature still works, but please use addFeature in the future.

Existing Project Errors

While most older projects should run, you may encounter issues with them as you open them in the wizard and re-save them.

This is why in the testing, we recommend first that you confirm that the project will run without errors before trying to edit them with the wizard. This will help us track down the problem to see if it's a project conversion issue or an actual wizard editing issue.

There is a known issue with nested blocks that will cause errors if you try to open in them in the wizard. There are a couple of projects that we know will have problems with this:

aquatic
beeDemo
(there are probably others...)

See "Nested Blocks" in Known Issues below for a workround.

TIPS

Save frequently -- save backups. It's easy to break the script.
Reload after manual gemprj edit -- If you edit the *.gemprj files directly, you need to restart npm run gem for the project to re-load the gemproj file. Otherwise it will continue to use the version initially loaded when you first ran npm run gem.
Switch to Code View -- Code view is a good fallback if you need to quickly fix things, or you find the UI is not working right.
If Main seems to stop responding, check the browser developer console to see if there are any error messages. Bad scripts can cause errors when Main tries to compile blueprints and run init scripts. These errors are not necessarily displayed in red. If you encounter a script compile error like this, you generally need to identify the problem script, undo the changes you made, quit the server, and rerun npm run gem again to clear it. We're working on making this less painful for the future...

Monitor the Web Dev Console

Given that we are in the early part of a significant QA cycle, we strongly recommend that you always have the web developer console open and watch for red javascript errors. Sometimes, in spite of errors, the app will continue to run, but do so with strange behaviors. Generally if you see a javscript error, write it down and try to reproduce it, then report it. If you need to continue working, reload first to clear the error. Continuing to work and ignoring the error can have unexpected unintended effects and you may end up wasting both your time and our time on a non-issue.

Known Issues

HELP: xxx -- The help system has not been built yet, so you'll see placeholder help throughout the UI. This includes the static Use the "prop" keyword to set properties to specific values and do simple arithmetic. help at the bottom of the editor.
Comments -- Comments are not editable yet.
Moving Lines -- Right now it is not possible to move a script line. You can go into the CODE view to copy and paste lines if you need to move them.
Nested Blocks -- Nested blocks that will cause errors if you try to open in them in the wizard. Generally, the error will happen after you eidt and save a script line. You'll see this in the console:

ac-wizcore.ts:146 wizcore_interceptState tokens: Error: multiple declarations of UPDATE

The workaround is to add a comment at the end of each block. e.g.

This will cause an error:
```
onEvent Start [[
ifExpr {{ ... }} [[
]]
]]
```
Fix it by adding a comment:
```
onEvent Start [[
ifExpr {{ ... }} [[
]]
// end block
]]
```
Adding Lines at the end of a Nested Block -- Normally if you select the last line in a block and then click "+" to add a line below it, the line should be added to the end of the block (i.e. INSIDE the block), not AFTER the block. Currently inserting a line below will insert it after the block.
when context checking -- Currently, you can select any blueprint with any keyword even if that blueprint is not currently available in the current context. For example, if you're editing the Tree blueprint, and in the script you add a prop keyword, prop will blithely let you select Moth, Predator, or Graph blueprint propnames because they exist in the project. Ideally the wizard would know which agent contexts are currently active and only provide the active blueprints as options. For example, continuing the example above, only agent should be available to prop keywords, unless you add a when Moth touches Tree block. Inside that block, you should have access to Moth as well as Tree and agent (the current agent). While we intend to eventually provide this contextual information, it is a significant undertaking so we are not yet supporting it.
Context Checking -- In general, the system isn't very smart yet about knowing the context that is available to a particular keyword. This means that it is easy to add references inappropriately. For example, you might try to set a featProp on a feature that you have not added to the blueprint. Or you might refer to the wrong blueprint in code for a different blueprint. The rule of thumb is to use agent whenever possible, and to only use the blueprint name in when clauses when you've explicitly set a test condition that includes the blueprint.
Costumes -- All agents MUST use the Costume feature and set a skin. Otherwise you'll get errors like class-visual.ts:179 Uncaught (in promise) Error: arg1 must be texture asset name

Key Features

Syntax for keywords -- The editor will show blank "slots" for any property, methods, or parameters required for any given keyword.
Invalid script syntax is highlighted in red -- Any script line that has invalid syntax is displayed in red. You can click on it to fix it.
Locked "Words" -- Some gemscript commands should not be edited by novices. These are locked.
"Normal" vs "Expert" keywords and methods -- Some gemscript keywords, properties, and methods are for advanced users only. These are displayed in a separate faded out list below the main "normal" words.
Add line at the end of the script -- You can add a new line at the end of the script.
Insert line above / below current line -- You can insert a line above or below the currently selected line.
Delete line -- Any line that is not locked can be deleted.
Delete extra script word -- Manual script entry can sometimes add extra script words that need to be removed.
Round Script Editor -- Round init scripts can now be edited using the codejar editor. Integrating the wizard UI into the round script editing is challenging and may be addressed later, time permitting.
Instance Init Script Editor -- Round init scripts can now be edited using the codejar editor. Integrating the wizard UI into the instance init script editing is challenging and may be addressed later, time permitting.

To Test

git fetch && git checkout dev-next-gui
npm run bootstrap
npm run gem
Go to the Login page to select a project: http://localhost/app/login
Select any existing project.
Select Main

Run the Project

Open the developer web console (CMD SHIFT I)
Click "Prep Round"
Click "Start Round"
Make sure the simulation runs and there are no javascript errors in the console.
If the simulation does not run, or there are javascript errors, please try to fix them before using the wizard. If you can't fix it, please report it as an issue. Include the project file you are trying to open in the issue.

Edit a Script

In the lower left "CHARACTER TYPE SCRIPTS" section, click on a character name, e.g. "Algae"
This should open up the Algae script in a new tab, defaulting to the wizard view.
Click on any line to select it for editing
The line should open in the editor on the right panel
Click on any script "word" to change it.
Options to replace the word should appear in the right panel
Click on a keyword to select it
When a new keyword is selected, the syntax for the line should update (e.g. the number of words required will change based on the keyword, properties, and methods you select).
A hint for what each word should be is displayed above the word in light blue.
Edit all the words in a line -- The best line to test is probably something like featCall Costume setCostume 'algae.json' so that any changes are immediately obvious. e.g. change the algae.json to fish.json
Click "Save" to save the line.
Click "Save to Server" to save the script to the main server.
Review the main server to make sure the script was updated and no errors occurred.
If you changed the costume, you should see the existing instances change costumes.

Use the Code Editor

Click on the "CODE" tab in the Script Editor
You should see the gemscript code. The line numbers in the code should match the line numbers in the wizard.
Edit the code
Switch back to the "WIZARD" view -- make sure your changes are reflected

Add a Line at the End of the script

Make sure you're in "WIZARD" view
Click on "Add Line" at the bottom of the script view -- you may need to scroll down if your script is long
A new blank line should be inserted at the bottom of the script
The line should be automatically selected for editing
Edit the line and save it.

Add a Line in the middle of the script

Click on a line to select it.
Click on the "+" button above or below the line to insert a new line above or below the line.
Edit the line and save it.

Delete a Line

Click on a line to select it.
Click on the "DELETE" line button to delete it.
Notice that # directives cannot be deleted.

Insert a Nested Block

Find the # PROGRAM UPDATE block.
Click on a line to select it.
Click on "+" to add a line below it.
Click on "every" to add a new keyword
Click on the second parameter, and enter "10"
Click on "Save" to save the new keyword
Notice there is now a nested block below the "every" keyword with a comment // insert code here.
Click on the "every" line
Click "+" to add a new line below the "every" line
This should create a new blank line inside the every block.
Click "+" to add a second line. This too should be inside the every block.
Click on the next line AFTER the every block.
Click "+" to insert a line above the AFTER line -- this should insert a line outside of the "every" block.

In GitLab by @daveseah on Apr 14, 2022, 12:39

added 4 commits

6749a154 - showFeatureProps: Recursively dIsplay props and methods for each feature in...
f25b6955 - showFeatureProps: Show methods only if `gsType` === 'method'
0b662a24 - showFeatureProps: doc
259053f9 - Merge branch 'dev-next-gui-bl/showFeatureProps' into 'dev-next-gui'

theRAPTLab / gsgo