[[TOC]]

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:

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.

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.

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 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.

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.

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"'
  

See also !268