GML dialects

As the number of games that use GML-like scripting languages for modding APIs slowly grows (Nuclear Throne, Rivals of Aether, Forager, etc.), it may be desirable (from both developer and modder perspective) to have adequate tooling for writing the code.

Recent GMEdit versions (starting with Sep 2019) can aid with that by introducing custom dialect support. Dialects are small folders of files, defining available GML features, functions, and rules for auto-completion.

Installing dialects

• Open Preferences (in the main menu ☰), scroll to the "Other useful things" (bottom of the list), click "GML dialects directory"
• Unzip your downloaded dialect to thatdirectory so that you have .../GMEdit/api//config.json
• Click "Reload GMEdit" in the same section

Using dialects

Dialects can specify the naming convention for their project files, and GMEdit will open the containing directory as a project when dragging such a file. Consult your installation instructions or section below on more information.

Making dialects

To create a new dialect, create a directory inside the dialects directory (see above) and create a config.json file inside it.

The full list of things that can be added to the file can be found here, so let's look at the basics (config.json):

{
	"parent": "gml2",
	"name": "Cool Game™",
	
	"indexingMode": "local",
	"projectRegex": "^(.+?)\\.coolgame$",
	
	"apiFiles": ["api.gml"],
	"assetFiles": ["assets.gml"]
}

Here,

• "parent" defines the parent configuration (to inherit default values from).
  You usually want to use either "gml1" (GM:S GML) or "gml2" (GMS2 GML) unless you're willing to fill out all those feature fields by hand.
• "name" is purely display-only and is shown in Preferences.
• "indexingMode" defines how GMEdit will treat the code
  • "local" means that each file will be considered a self-contained program and thus any scripts/macros/variables defined inside should be kept local to it.
  • "directory" means that all GML files inside the directory will be considered a combined program; file names will be used to determine the name of the top-most script inside any given file.
• "projectRegex" is a regular expression that should be matches for an input file to be considered a project file for your dialect. Here we're taking anything that has the "coolgame" extension.
• "apiFiles" is an array of paths to files containing API definitions. We'll get to this in a bit
• "assetFiles" is an array of paths to files containing resource lists. Same as above.

API files

These can contain variable, function, and constant definitions in several formats,

• function_name(<...arguments>)
  Optional arguments can be hinted via ?argname or argname=value.
  Trailing arguments can be hinted via ...argname.
• variable_name Add a [from..to] if a variable is an array (e.g. view_xview[0..7]).
  Add a @ if it is an instance variable. Add a * if a variable is read-only.
• constant_name#, constant_name = value If a value is provided, it will be shown in auto-completion. Here's an example (api.gml) following the earlier configuration:

cool_message(text)
cool_math(a, op, b)
cool_trace(...values)
cool_var
cool_const#
cool_number = 4

Asset files

GMEdit will pick up any identifier (as with regex /\w+/g) inside these, so you can dump all your asset names in these while using spaces or line breaks for separators.

Here's an example (assets.gml) following the earlier configuration:

cool_sprite
cool_sound

In conclusion

With a little bit of work, you too can have some good support for language of your passion