Ana Language Support for VS Code

Language support for .ana passage files used by the Ana narrative game engine: syntax highlighting plus IntelliSense backed by the engine's own macro reference.

Features

Syntax highlighting — passages (:: PassageName [tags] @modifier), directives, macro calls, global/temp variables, strings, numbers, operators, and comments.
Hover docs — hover any macro name for its full description, call forms, args/kwargs, aliases, and example, pulled from the macro reference (docs/reference/*.md).
Completion + snippets — typing inside a (… call lists every macro; accepting one inserts the call form with tab-stop placeholders.
Macro Handbook — the Ana view in the Activity Bar lists every macro grouped exactly like the docs sidebar (Language / Display / World Systems / Simulation / Engine). Click a macro to open a doc panel with a link to the full online reference.
Folding — fold :: Passage sections and multi-line block-macro [...] bodies.
Go to definition — Ctrl/Cmd+click a navigation target like (goto: BarScene) to jump to its :: BarScene declaration, anywhere in the workspace.
Game stats — a status-bar item shows the total passage and word count across every .ana file in the workspace; click it for a per-file breakdown.
Media asset checks — (img:), (audio:), (audio-crossfade:) and (portrait:) get a warning when the referenced file isn't found under assets/ (e.g. a typo, or an asset you haven't created yet). Resolution mirrors the engine: images/video → assets/images/, audio → assets/audio/, portraits → assets/images/<character>/<expression>.jpg. Only static filenames (bare or quoted) are checked; variable/expression arguments are left alone.

How the macro data is produced

The hover/completion/handbook content lives in macros.json, and the grammar's highlighted macro list is derived from it. The engine is the source of truth: in the ana-engine repo, npm run gen:manifest joins the macro signatures (dist/macro-signatures.json) with the reference docs and the category map (tools/macro-categories.js) into dist/macros.json, which CI publishes to https://ana-119a06.gitgud.site/macros.json.

macros.json is committed here and bundled into the extension, so a packaged .vsix is self-contained (it does not read your workspace) and the repo builds without the engine present.

Keeping in sync with the engine

After the engine's macros or reference docs change, refresh the bundled data:

npm run sync          # copy from a local engine checkout ($ANA_ENGINE_ROOT, default ../Ana)
npm run sync:remote   # fetch the published manifest ($ANA_MANIFEST_URL, default the Pages URL)

Either command refreshes macros.json, regenerates the grammar macro list (tools/gen-grammar.js), validates the two agree (tools/check-extension.js), and recompiles.

Building

npm install
npm run compile       # compile src/ → out/  (extension does nothing until out/ exists)
npm run package       # produce ana-game-engine-0.0.1.vsix

Developing (F5)

Open this folder in VS Code and press F5 ("Run Ana Extension"). This compiles src/ and launches an Extension Development Host; open a folder containing .ana files in that window to exercise the features.

Installation

From a marketplace

VS Code Marketplace: Chloeana.ana-game-engine — or search "Ana Game Engine" in the Extensions view.
Open VSX (VSCodium, Cursor, Gitpod, etc.): Chloeana/ana-game-engine

From VSIX

npm run package → produces ana-game-engine-0.0.1.vsix.
VS Code → Extensions → ... menu → Install from VSIX…

Settings

Setting	Default	What it does
`ana.docsBaseUrl`	`https://ana-119a06.gitgud.site/`	Base URL for the "Full reference" links.
`ana.folding.enabled`	`true`	Fold passage sections and block-macro bodies.
`ana.statusBar.enabled`	`true`	Show the game-wide passage/word count in the status bar.
`ana.media.validate`	`true`	Warn when a media macro references a missing asset file.
`ana.media.assetsRoot`	`""`	Folder containing the game's `assets/` directory (absolute or workspace-relative). Defaults to the workspace folder root.

Completion vs. GitHub Copilot

Copilot's inline (ghost-text) suggestions and this extension's macro completion can compete as you type. An extension can't suppress Copilot's ghost text, but you can turn inline suggestions off for .ana files only, leaving the macro snippets in charge, by adding to settings.json:

"[ana]": {
  "editor.inlineSuggest.enabled": false
}

To customize highlight colors, add token rules for the source.ana scope to settings.json:

"editor.tokenColorCustomizations": {
  "textMateRules": [
    { "scope": "entity.name.passage.ana", "settings": { "foreground": "#7ab8fa" } },
    { "scope": "support.function.macro.ana", "settings": { "foreground": "#a6e22e" } }
  ]
}

Ana Game Engine

Chloeana