You can insert comments using //.

e.g.

// Count number of predators

• Comments need to be on their own lines, they cannot be inserted AFTER GEMSCRIPT. e.g.

prop energyLevel setTo 5 // THIS IS NOT A VALID COMMENT

Unpredictable things will happen with inline comments. Most likely they will be treated as additional parameters for the GEMSCRIPT keyword.

There are two useful comment features: 1. Comment Types and 2. Bookmarks.

You can define a "Comment Type" style based on a simple match string for the comment. The comment type serves two purposes:

1. You can add a comment by selecting a predefined comment type using the wizard. Any matching comment type will be styled according to the setting.
2. You can use the Bookmark menu to quickly jump to a line of code that matches a comment type.

The system has a number of default comment types, but you can define your own comment type in the project assets root folder.

• "Built-in Comment Types" are defined in the COMMENTTYPEMAP defined in gs_packages/gem-srv/src/modules/sim/script/tools/comment-utilities.ts.
• New Comment Types can be defined using the a /gs_assets/art-assets/preferences/_comment_types.toml file.
• See the _comment_types.toml file for examples. (attached as a .txt file for ease of reading) _comment_types.toml.txt
• Comment Types in preferences files will override built-in comment types (the console will display a warning that a comment type was previously defined).
• color and backgroundColor can be defined for each comment type.

# PREFERENCES
#
#   Preferences are site-wide settings that apply to all projets.
#
#   Current Preferences support:
#     * Comment Types
#
# Comment Types
#   Comment Types are used to define the visual display of comments
#   in the ScriptEditor views.  You can define:
#     * `matchString` -- the search string used to set the visual style
#     * `cssClass` -- use a pre-defined css class (from `gem-ui.css`)
#     * `color` / `backgroundColor` -- css colors to use inplace of cssClasses
#     * `help` -- Short help blurb to display in the comment edit pane
#     * `isBookmark` -- flag to mark the comment type as a bookmark, 
#                       selectable from the ScriptEditor script lines view
#
#   To set the comment colors, use either:
#     A.`cssClass` to one of the predefined styles, or...
#        - commentKeyHeader
#        - explanationCommentHeader
#        - explanationCommentBody
#        - changeCommentHeader
#        - changeCommentBody
#     B. 'color' and/or 'backgroundColor' to override the color
#        You can use either 'color', or 'backgroundColor' or both.
#        Any colors defined will override the cssClass style.
#        Colors are defined as css values.  You can use:
#        * hexadecimal "#rgb" "#rrggbb", e.g. "#f00" for red
#        * rgb alpha "rgba(r,g,b,a)", e.g. "rgba(255,0,0,0.5)" for a transparent red
# 
#   You can override existing styles by adding them by using the
#   same `matchString` in the COMMENTTYPEMAP defined in
#   `gs_packages/gem-srv/src/modules/sim/script/tools/comment-utilities.ts`

Comment lines can now be selected and edited via the wizard. In addition, you can now select a comment style via a popup selection menu and the full comment line will be automatically generated.

• Styles are optional. To select a comment without a style, leave the menu selection "empty" with "-- no style --".
• Select a style from the popup menu to automatically change the comment text to include the style snippet.
• Add comment text to the input field as you would with any GEMSCRIPT code

Technical Background: GEMSCRIPT scripts are text lines that are parsed and converted into tokens corresponding to keywords and parameters for each line of script. The input UI system uses an elaborate system of components to convert the keywords and parameters into the wizard UI. Comments however are not strictly speaking keywords. In order to provide a wizard UI for comments, we construct a secondary UI that handles the destructuring of comment text into prefix styles and comment body text so that they can be independently edited, and the reconstructed into a single comment line. See cf91c683ee19c30fc640a8b8a904135ab1de5069.

Bookmarks can be added to GEMSCRIPT code. When opening a script, users can select a bookmark from a list of bookmarks and automatically scroll to the selected line and enable editing for the line.

• Bookmarks are defined by designating a particular match string as a bookmark. Any comment that matches the matchstring will automatically create a bookmark.
• Bookmarks listed and selected via a SELECTION menu.

See #751, #758