Sound Shapes GameMonkey for VS Code
Editor support for Sound Shapes' GameMonkey scripts (.gm), built from api/engine.json in soundshapes-engine-docs.
Completion: global natives, global objects (Video, Audio, Input, ...), constants and the game's own script
functions; after a ., the methods of the receiver's type. Inside an argument that takes a constant family
(PHYSICSTYPE_, FILEHELPER_AREA_, ...) those constants come first.
Hover: signature, description, what the function returned when tested in the game (and whether it crashes),
how often the game's scripts call it, and an example call.
Signature help while typing arguments.
Go to definition (Ctrl+click) on an engine method, global function, global object, constant or type opens its
reference page, rendered, in the Sound Shapes reference panel beside the editor, scrolled to it: signature,
parameters, description, what it returned when tested in the game, and how the game's scripts use it. A type's page
has all its methods; constants are grouped by family (KEYBOARD_*). Every name on a page is a link to its own page,
with ← Back to return. Sound Shapes: Open the reference page (also in the editor's context menu) opens the page of
what is under the cursor, or lets you search them all. Go to type definition on a variable opens its type's page.
Set soundshapes.referenceView to markdown to get the pages as Markdown text instead.
Highlighting for keywords, strings, numbers (0.71f), natives, constants and global objects.
Problems as you type in a .gm file. The engine reports none of these itself: in the game, calling a function
that doesn't exist does nothing and returns null.
- Syntax errors: a missing
;, an unclosed bracket or string, a stray else. The parser accepts all 918 of the
game's own scripts.
- Calls to functions that aren't engine natives and that neither the game's scripts nor your workspace's
.gm files
define (warning).
- Calls to methods the engine's global objects don't have, such as
Video.pushMatrix() (warning). Other objects
aren't checked, since entities and processes also get methods from their script tables.
- Too few arguments to a native that reads them without checking:
MATH_SQRT() reads garbage (warning). More
arguments than a native reads are ignored (information).
Turn it off with soundshapes.diagnostics. test/corpus.js runs the checks over the game's scripts, extracted from
its archives; the warnings it finds there are the game's own typos and dead code (OnlineCoodrinator_isOnline).
How receiver types are found
For x. the extension works out the type of x, in this order:
- a global object (
Video → VIDEO);
- the last assignment to
x (or to a member path like this.def) before the cursor, followed through calls:
local pd = EntityManager.createEntity().getPhysicsData(); → MULTIBODYPHYSICSDATA, and COLOUR(...) → COLOUR;
- the type the game's scripts use that name for most of the time (
pb → PHYSICSBODY,
this.PhysicsData → MULTIBODYPHYSICSDATA). Hovers mark these as guessed.
If none of these works it offers every method of every type, labelled with the types that have it.
Build and install
npm run build-api # ../soundshapes-engine-docs/api/engine.json -> data/api.json and the grammar
# (or: node scripts/build-api.js path/to/engine.json)
npm test # checks the analysis on small snippets
npm run package # makes soundshapes-gamemonkey-<version>.vsix (fetches @vscode/vsce with npx)
code --install-extension soundshapes-gamemonkey-0.1.0.vsix
Run npm run build-api again after rebuilding api/engine.json, then repackage. To try a new api.json without
repackaging, set soundshapes.apiPath to its path.
Releases
Releases are automatic. When api/engine.json changes on soundshapes-engine-docs' main, its pipeline starts this
project's update-api job, which rebuilds data/api.json and the grammar from it. If they changed, the job bumps the
patch version, pushes a commit and a vX.Y.Z tag, and the tag's pipeline builds the .vsix and makes a release with
it (Deploy > Releases). The job can also be run by hand: Build > Pipelines > Run pipeline on main.
Pushing needs a RELEASE_TOKEN CI/CD variable: a project access token with the write_repository scope and the
Maintainer role (Settings > Access tokens), saved masked under Settings > CI/CD > Variables. A tag pushed by hand
still releases as before.
For other extensions
activate returns { api, analysis }: the slimmed engine API (data/api.json) and the analysis module
(sanitize, Analyzer, …). The SoundShaper Mods extension uses them, and this extension also serves its .gm.edit
files (the gm-edit language), reading only the code inside the blocks.
| |