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.

How the macro data is produced

The hover/completion/handbook content lives in macros.json, generated by tools/gen-macro-metadata.js, which joins the engine's macro signatures (dist/macro-signatures.json) with the reference docs and the category map in tools/macro-categories.js. It is bundled into the extension, so a packaged .vsix is self-contained (it does not read your workspace).

After changing a macro signature or its reference docs, rebuild the data with npm run build:extension (from the repo root) — it refreshes macros.json and recompiles.

Building

From the repo root:

npm run build:extension     # refresh macros.json + compile vscode-extension/src → out/
npm run package:extension   # also produce ana-language-support-0.0.1.vsix

extension.js is compiled output under out/: the extension does nothing until out/ exists.

Developing (F5)

Open the vscode-extension/ 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 VSIX

1. npm run package:extension (repo root) → produces vscode-extension/ana-language-support-0.0.1.vsix.
2. VS Code → Extensions → ... menu → Install from VSIX…

Settings

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" } }
  ]
}