VgScript documentation

VgScript is a plain-text language for game narrative. A script is made from bracket-tagged lines for scenes, speakers, dialogue, actions, conditions, and decisions. The editor plugins add highlighting and live checks; the bundled vgs tool keeps each script's runtime metadata in sync.

The one rule to remember: edit .vgs files, never .vgs.meta files. Run Fix + Reconcile after editing and let VgScript regenerate the sidecar.

Quick start

1. Install the VgScript plugin for VS Code or a JetBrains IDE.
2. Create a folder for your narrative, with a Scenes.txt file and one .vgs file per scene.
3. Write your scene in the .vgs file.
4. Right-click the script and choose VgScript → Fix + Reconcile.
5. Choose Validate / Find Mistakes before committing your changes.

Here is a small but complete scene:

[S1_Kitchen] Kitchen, night

[P] Anna -> Marco
[T1]
[1] Are you still awake? ->(D1)

[D1]
[1] =(T2-1)'I was reading.' ->(T2)
[2] =(T3-1)'I could not sleep.' ->(T3)

[P] Marco -> Anna
[T2]
[1] I was reading. ->(A1)

[T3]
[1] I could not sleep. ->(A1)

[A1] FadeOut ||(Timer{S})

Reconcile numbers and normalizes the entries, copies the referenced talk text into each decision, preserves stable IDs, and writes Kitchen.vgs.meta next to the script.

Language basics

Tags must begin a line. Four tags create entries; two provide context for the entries that follow.

Sublines

Numbered lines belong to the nearest entry above them. Reconcile normalizes placeholders such as [X] and long-form tags such as [T1-2] to [1], [2], and so on.

[P] Hero
[T1]
[1] So this is where it begins.
[2] Nothing here yet. Only my voice.

Flow and references

• ->(T2) starts T2 after the current line or action finishes.
• ||(Timer{S}) starts something in parallel without waiting.
• ->(S2-T1) points to entry T1 in scene S2. Run Resolve Cross-Script Links after adding or changing cross-scene jumps.
• Everything after -> or || is flow control, not visible dialogue.
• Text inside {...} is an engine-level parameter or inline marker. The vgs tool treats it as metadata and removes it from visible text.

Do not write {#guid:...} or {#dst:...} annotations yourself. They are stable reference anchors owned by the tool.

Decisions

Each numbered option points to the entry that should run when selected:

[D1]
[1] Accept  ->(A_yes)
[2] Decline ->(A_no)

Use =(T2-1) when an option should reuse the visible text from the first line of T2. Reconcile materializes that text so the choice and the dialogue cannot drift apart. An option may also start with if(...); the condition is excluded from its visible text.

Organizing a project

Keep one scene per .vgs file and list the scenes in playback order in Scenes.txt:

// Scenes:

[1] /Intro
[2] /Kitchen
[3] /Finale

The project-wide commands follow this order. Reorder Scenes can either keep filenames unchanged and write [n] prefixes in Scenes.txt, or rename files to S<n>_<Name>.vgs when the editor's rename setting is enabled.

Reconcile and validate

Every .vgs file has a generated <file>.vgs.meta JSON sidecar. Your game reads this stable, machine-friendly representation. A reconcile pass:

• numbers entries and normalizes their sublines;
• retains entry identity across edits using tool-managed anchors, codes, and content matching;
• fills decision text referenced from talk lines;
• annotates cross-script destinations and reports missing ones;
• rewrites the .meta and may add stable anchors to the .vgs.

Run the file workflow after writing or editing a scene:

vgs fix Kitchen.vgs
vgs find-mistakes Kitchen.vgs

Before a build or after changing several scenes, run the project workflow:

vgs fix-all .
vgs check-all .

Editor actions and CLI commands

VS Code and JetBrains expose the same actions from the VgScript context menu: a .vgs file offers the two actions that work on that script, while a folder or Scenes.txt offers the project-wide ones. In JetBrains, the VgScript status-bar button lists all five. The plugins bundle the vgs engine for one platform per release, so on that platform nothing else is installed; elsewhere, put a vgs on your PATH or set its path in the plugin settings.

CLI exit codes are stable: 0 means success, 1 means find-mistakes or check-all found problems, and 2 means the script or Scenes.txt could not be found. resolve-links and reorder-scenes report through their console output rather than the exit code.

Working with an AI assistant

Give the assistant project context and the VgScript workflow before asking it to edit narrative files. The complete agent guide documents the language, the tool commands, and the writing conventions in a reusable form: hand your assistant the plain-text version, or copy it into your repo's AGENTS.md. The public VgScript example project is a working sample of a repo set up that way.

An assistant should always:

1. edit the .vgs, never its .meta;
2. run vgs fix after an edit;
3. run vgs find-mistakes to verify the result;
4. reuse existing actions unless you explicitly approve a new one.

Troubleshooting

An editor action says the binary is missing

Marketplace builds bundle the correct vgs binary. If you are developing the plugin from source, set the editor's VgScript binary path, build core/tool, or put vgs on your system PATH.

Colors or live diagnostics do not appear

Check that semantic decorations and diagnostics are enabled in the plugin settings. Open the IDE's VgScript output or run console for details; if only colors are affected, test another theme because themes can override token colors.

A cross-script jump is missing

Confirm that both scenes have reconciled .meta files, check that Scenes.txt contains the target scene, then run Resolve Cross-Script Links again.

For implementation details and issue reports, see the VgScript plugin repository.