benloh commented 2 years ago

Merges dev-bl/feature-help -> dev-next

Branch: dev-bl/feature-help

Includes if !269

This is a first pass implementation of the full help system for the GUI Wizard scripting. It's rather complex and will need to be refined. It includes:

Line Help -- (always visible) General non-keyword-specific help for editing a single line (e.g. "Click 'Save Line' to save changes to this line."). This is essentially static text that is the same for all keywords.
Selected Keyword Help -- (always visible) General help for the whole line based on the selected keyword (e.g. "[prop] lets you set or modify a property value").
Syntax Help -- (hover) Informational help that explains the gemscript role of each slot (e.g. hover over "method" to see "a method is an action that can be performed by a property or features"). Displayed when you hover over the slot label above each slot.
Empty Slot Help -- (hover) Instructional help that explains what you should do to fill the empty slot. Once you select a symbol or input a value, the help changes to Filed Slot Help.
Filled Slot Help -- (hover) Informational help that explains what the currently selected choice is (e.g. hover over the "prop" in the "keyword" slot to see "[prop] lets you set or modify a property value"). Displayed when you hover over the filled slot.
Slot Instructions Help -- (always visible) General instructions for the currently selected slot (e.g. "Choose a property"). This is generally the same as #4, but always visible once you select the slot.
General Choices Help Title -- (always visible) Informational short label that explains the choices, e.g. "SELECT A COMMAND KEYWORD".
General Choices Help -- (always visible) Informational help that explains the gemscript role of each slot. Same as #3.
Specific Choice Help -- (hover) Informational help that explains the option (e.g. when selecting a keyword, hover over "prop" to see "[prop] lets you set or modify a property value"). The intent is to help you decide which option to choose. Same as #5 when the choices match the current selection.
Selected Choice Help -- (always visible) Info help that explains what the currently selected choice is (same content as #5 and #9) (e.g. "Sets the property to a value" for "setTo").

Much of the help content is actually the same, and what is displayed at any particular spot is dependent on what information is available and not available. Sometimes one type of help will override another type of help (e.g. for a slot, the selected slow item help is displayed by priority, if it is not available, we display the general slot help).

screenshot_1101

Other Changes

The "Save Line" button is moved to the top of the Line Editor panel (right panel) so the buttons are more prominent, always approximately in the same place, sand do not scroll off the screen with longer choice lists.
IMPORTANT propTypes are now lowercased: string, number, boolean. You'll need to change any addProp lines to reflect this. String will not have help available, but string will. (This was actually a change from about a month ago, and should be done with conversions. I believe the compiler does deal with the case issue, but the help system does not).

Testing

Fully QAing/Testing the Help system is a rather daunting task. Ideally, you would review:

Every keyword
Every slot for every keyword
Every prop type
Every method for every prop type
Every feature
Every feature prop
Every feature method

Things to watch out for:

Does an empty slot have the correct help?
Does a filled slot show the help for the selected item?
Check all 7 help locations for each slot for each line -- do they all show the right help?
Create a new line with the keyword from scratch -- does each slot have the right help?
Edit an existing line, systematically changing only one of the parameters along the way. Does a change in any one slot affect the others correctly?
Change an existing line's keyword to another keyword. Are the rest of the slots correct?
Select each slot. While the slot is selected, checke the syntax and symbol help for all the other slots -- are they correct?

Review the big picture:

Are students getting enough information for them to know what to do?
Is there some information that is missing? e.g. an explanation of units, a list of valid parameters/values?
Is there help that is really not needed and can be removed to simplify the UI?

[for the wiki]

HELP AUTHORING

These are the Types of help fields that have been defined (not all are currently in use):

input -- Actions that the user should take (instructions)
info -- General description of the item (keyword, feature, method, parameter)

[These types have also been defined in the yaml file, but they are not currently being used. For simplicity's sake, we might leave them out.

hint -- A short tooltip (not currently used)
syntax -- Specification of the type of data that should be entered (not currently used)
glossary -- Longer definition of a particular feature (not currently used)

]

Where help appears:

	Location	Visibility	Type	Description	Example
1	Line Help	static	info	General non-keyword-specific help for editing a single line. This is essentially static text that is the same for all keywords.	Click 'Save Line' to save changes to this line
2	Selected Keyword Help	static	info	General help for the whole line based on the selected keyword	[prop] lets you set or modify a property value
3	Syntax Help	hover	info	Informational help that explains the gemscript role of each slot. Displayed when you hover over the slot label above each slot.	a method is an action that can be performed by a property or features
4	Empty Slot Help	hover	input	Instructional help that explains what you should do to fill the empty slot. Once you select a symbol or input a value, the help changes to Filed Slot Help.	Select a method (action). Available methods are determined by the property type or feature selected.
5	Filled Slot Help	hover	info	Informational help that explains what the currently selected choice is. Displayed when you hover over the filled slot.	[prop] lets you set or modify a property value
6	Slot Instructions Help	static	input	General instructions for the currently selected slot. This is generally the same as #4, but always visible once you select the slot.	Choose a property
7	General Choices Help Title	static	info	Informational short label that explains the choices.	SELECT A COMMAND KEYWORD
8	General Choices Help	hover	info	Informational help that explains the gemscript role of each slot. Same as #3	a method is an action that can be performed by a property or features
9	Specific Choice Help	static	info	Informational help that explains the option. The intent is to help you decide which option to choose. Same as #5 when the choices match the current selection.	[prop] lets you set or modify a property value
10	Selected Choice Help	static	info	Informational help that explains what the currently selected choice is (same content as #5 and #9).	[prop] lets you set or modify a property value

NOTES:

Note that we also generate help for the "inactive" slots as well (#3 Syntax Help, #4 Empty Slot Help, #5 Filled Slot Help) so that you can always review the whole script line context.
Object References (e.g. selectors for prop<bp>.<prop>, featCall <bp>.<feat>, and featProp <bp>.<feat>.<prop>) essentially duplicates the top level help with informational and instrucitonal help keyed off of the syntax, selected tokens, and available choices.

Help Content Files

Most of the help text content are in files called codex-*.yaml:

codex-conditions.yaml
codex-events.yaml
codex-features.yaml
codex-gsargs.yaml
codex-keywords.yaml
codex-types.yaml

In addition, help for GVAR methods are defined in each GVAR method:

class-sm-boolean.ts
class-sm-number.ts
class-sm-string.ts

Most of the current help text is rough still and needs a refinement pass. The easiest way to find where the help text is defined is simply to search for the text.

In general, you can safely modify the info: and input: fields. Watch for quotes and encoding issues.

Modifying any other parameters may break the indexing and require modifications across the system. So only do so with care.

Mapping GEMSCRIPT Symbols to Help Content

AKA "How do I figure out which help a particular symbol is using?"

Help is keyed off of two pieces of information that have been defined for each symbol: gsName and gsType.

gsName -- syntax, input instructions
gsType-- informational, info

Where are gsName and gsType defined? It depends on the symbol.

Keywords
- ex: addProp, featCall
- Keywords just use the keyword itself as the gsType
- codex-keywords.yaml
Keyword args
- ex: addProp <prop name arg>, prop <prop name objref>
- Keywords often reference specific types of arguments.
- These are defined by the keyword file. Looking them up is relatively complex. Generally, the lookup workflow is:
  1. Look at keyword definition -- e.g. prop.tsx
  2. Look for validate method.
  3. Note the shelper methods in class-symbol-interpreter for the specific slot -- e,g, shelper.agentObjRef()
  4. Note the type passed in the HELP.ForGSrg() method. -- e,g, agentObjRef
  5. Look up the type in codex-gsargs.yaml -- e.g. 'prop:objref'
  6. The first value mapped is gsName, the second value is the gsType These are the index values to help.
gvar methods and method args (boolean, number, string)
- ex: setTo, add
- The base gvar classes define their own gsName and gsType for each arg in the static Symbols: TSymbolData line at the end of each file.
- The first arg value is the gsName, the second is the gsType. e.g. for setMin, gsName = min value, gsType = number
Feature props
- ex: movementType, costumeName
- Look up the list of feature props in the static Symbols: TSymbolData line at the end of each feature file (e.g. feat-movmeent.ts)
- Each feature prop should have a matching entry in codex-features.yaml that explains what the property is.
Feature prop method args (subtypes)
- ex: featProp AgentWidgets.text setTo 'Charlie', featProp Movement.movementType setTo <prop method arg>
- Since feature props generally use the built in gvar objects (e.g. boolean, number, string), they also default to using the methods and method args help for the standard gvar objects (e.g. "setTo", "string").
- You can look up the mapping of the feature props in the static Symbols: TSymbolData line at the end of each feature file (e.g. feat-movmeent.ts)
- Even though feature props use the standard gvars, oftentimes you want to provide extra help for the specific prop. e.g. you want to be able to explain that valid movementTypes includ wander and stop, or that glow is a time value in seconds.
- We added a hack that allows to specify a gvar subtype, and then provide help on that subtype that allows us to map method args to specific gsName and gsType definitions. For example, movementType is really just a string gvar, but we want to be able to display movmeentType specific help for students to help them know what they should enter. See Subtype Help below for instructions.
Feature methods
- e.g. featCall Touches.monitor
- Feature methods are listed in the static Symbols: TSymbolData line at the end of each feature file (e.g. feat-movmeent.ts)
- In this case, gsName and gsType are automatically set to the method name.
- Each method should have a corresponding entry in codex-features.yaml

Feature method args

e.g. featCall Touches.monitor <target blueprint arg> <touch type arg>
Feature method args are specified in static Symbols: TSymbolData methods section.
The gsName and gsType definitions map to args defined in codex-features.yaml. For example for the Touches monitor method, the two args targetBlueprintName and touchType are defined in the Touches section of code-features.yaml e.g. in feat-movement.ts the definitions are...

static Symbols: TSymbolData = {
  methods: {
    monitor: { args: ['targetBlueprintName:string', 'touchType:identifier'] }

...which maps to...

Touches:
info: 'Adds tests to detect when characters touch each other'
...
# method args
targetBlueprintName:
  name: 'target blueprint name'
  info: 'Sets the character for this method to act upon'
  input: 'Use an existing character name'
touchType:
  name: 'touch type'
  info: 'Sets the type of touches to monitor:  "b2b" is bounds to bounds, "binb" is bounds in bounds, "c2c" is center to center, "c2b" is center to bounds'
  input: 'Valid touch types: "b2b" is bounds to bounds, "binb" is bounds in bounds, "c2c" is center to center, "c2b" is center to bounds'

Many of these method args have not yet been defined in codex-features.yaml. Look for sections labeled # <feature> method args for examples.

Conditions tests
- Test for the when keyword are defined in codex-conditions.yaml.
- There is generally a one-to-one mapping between the condition test and the entry in the yaml file.
events
- Event types for the onEvent keyword are define din codex-events.yaml
- There is generally a one-to-one mapping between the event name and the entry in the yaml file.

Feature Prop Subtype Syntax Label Help

Feature props often require specific entries that are not obvious. The generic string/number/boolean help is not sufficient for helping students figure out what they need to enter.

For example, for featProp movementType setTo 'wander' the argument for the featprop needs to be a specific identifier string (e.g. 'wander', 'stop', 'jitter', etc.). In order to provide this help, we need to set multiple things.

1. Set a custom subtype for the gvar method in the feature definition.

In the feature definition, change the generic GVAR symbol maping to a custom value.

For example, for movementType, we would:

a. Edit feat-movement.ts

b. Change this:

static Symbols: TSymbolData = {
    props: {
      movementType: SM_String.Symbols,

...to this...

static Symbols: TSymbolData = {
    props: {
      movementType: SM_String.SymbolizeCustom({
        setTo: ['movementTypeString:string']
      }),

What we're doing here is replacing the standard string setTo method gsName:gsType specification of string:string with a custom subtype movementTypeString:string. Now when the help system tries to look up help for the argument, instead of using the standard string help, it'll try to find a movementTypeStringhelp.

NOTE that we called it movementTypeSTRING to differentiate it from the movementType property name.

NOTE you have to do this for every method you want to replace. Though in general setTo is probably sufficient.

2. Add a custom subtype to `codex-features.yaml`

For every custom subtype you define, you need to add a corresponding entry in the codex-features.yaml file.

Look for the # prop args section for each feature.

IMPORTANT: The entry needs to come under the feature the subtype belongs to. e.g. if you add movementType under Physics:by accident, it will not be found.

For example:

Movement:
  info: 'Add different ways to move or be controlled'
  ...
  # Movement prop args
  movementTypeString:
    info: '"movementTypeString" value determines how a character will move'
    input: 'Valid movementTypes are: "stop", "wander", "edgeToEdge", "setLocation", "goLocation", "jitter"'

Help Authoring Incomplete Items

While most of the Help infrastructure is now in place, there are still some key places that need to be fleshed out.

[ ] Feature Props that need subtype prop help (e.g. 'compassDirection') need to be converted from generic GVARS to GVARS with specific arg types. See feat-movement.ts's `movementType' for an exmaple of how this is done.
[ ] Help text is 'tbd' / 'xxx' / '' -- a lot of help text is still placeholder text. Review all the code-*.yaml files.
[ ] REMOVE DEBUGGING LABELS e.g. GSNAME.info
[x] BUG: ObjRefSelector seems to mysteriously add "LOAD" as blueprint choice.
[x] BUG: Inserting a reference to a wrong agent (e.g. in "Fish" enter a reference to "Algae" in a featProp call) will cause Main sim to stop with error.
[x] BUG: popup label for "x" is one letter wide. Where did the min-width go?

See also !261 & !265 for original Merge Request.