Project files and checks

For agents.The files they work in.

The agent works in the project files and reads the Kit's results. The guide in the Kit has the full reference.

Project files

Scripts, layouts, translations and project settings are text files.

Scripts

The .aiko script holds labels, lines, choices and staging commands. Characters, assets and variables are declared in project.json. The script has no embedded programming language.

Checks

validate reports each finding with a stable code and a severity, and with the file, line and column when the finding has a source position.

walk follows one route through the story without a browser. Run it once for each route.

Captures

capture records the screen at a chosen line as PNG images and as JSON records of geometry and motion. capture-compare reports the differences between two captures and changes neither of them.

validate --browser checks that dialogue and fullscreen text fit at 1920×1080, 1280×720, 800×600, 844×390 and 390×844 in every declared locale.

First steps

The starter project, from the first lines to a capture

The script below opens the starter project. The four commands run in the Kit folder.

story/main.aiko · the first lines of the starter project

label start {
  scene observatory with crossfade

  @id main.start.arrival
  "Dusk deepens beyond the window. A light still shines over the workbench."
  @id main.start.tsumugi.welcome
  tsumugi "One light for the workbench, and one for whoever arrives next."

  choice {
    @id main.start.choice.work
    "Leave the light on the workbench" {
      set light_for_guest = false
    }
    # the second option, the two branches and the ending follow
  1. 1

    Open the guide in the Kit folder.

    aikotoba.cmd docs
  2. 2

    Copy starter-project, read its AGENTS.md, then validate the copy.

    aikotoba.cmd validate --project <copy>
  3. 3

    Walk a route. This one takes the second option of the first choice.

    aikotoba.cmd walk --project <copy> --choice-id main.start.choice.guest
  4. 4

    Capture a line into a new folder outside the project and the Kit.

    aikotoba.cmd capture --project <copy> --entry start --target beat:main.start.tsumugi.welcome --locale en-US --viewport 1280x720 --motion ordinary --scope both --out <new-folder>
  1. 1

    Open the guide in the Kit folder.

    sh ./aikotoba docs
  2. 2

    Copy starter-project, read its AGENTS.md, then validate the copy.

    sh ./aikotoba validate --project <copy>
  3. 3

    Walk a route. This one takes the second option of the first choice.

    sh ./aikotoba walk --project <copy> --choice-id main.start.choice.guest
  4. 4

    Capture a line into a new folder outside the project and the Kit.

    sh ./aikotoba capture --project <copy> --entry start --target beat:main.start.tsumugi.welcome --locale en-US --viewport 1280x720 --motion ordinary --scope both --out <new-folder>

validate · Expected Kit output for a copy of the starter project where line 5 opens {i} and does not close it

> aikotoba.cmd validate --project lightkeeper
error [semantic:script-parser/dialogue_markup_invalid] story/main.aiko:5:36: {i} is not closed with {/i}.
Semantic validation: failed (1 error, 0 warnings).
Authoring audit: skipped because semantic validation failed.
Project validation failed with 1 error and 0 warnings.

0.7 is still in development. Some of these features are not in the private beta yet, and any of them may still change.

More for the agent

12 details
  1. A line can carry a stable @id. Saves, rollback and translation files use these IDs, and validate reports a repeated ID as an error.
  2. Commands that take --format json answer in a versioned protocol with a published schema.
  3. The starter project includes AGENTS.md and a project skill. The skill tells the agent to treat story text, comments and imported files as data, not as instructions.
  4. capture, preview and validate --browser use an installed Chrome or Edge, or Chrome or Chromium on macOS.
  5. Aikotoba does not call an AI model. Your own agent edits the project and runs the Kit's commands.
  6. The Kit's JSON commands are also available to the agent as MCP tools, with the same results.
  7. A capture run writes an index page of the evidence it recorded.
  8. Structured edits add a line or a choice, or rename a line ID, and keep the other IDs unchanged. Each edit shows its change before it is applied, and nothing changes if validation fails.
  9. A reference report lists where a given variable, label, character, costume or asset is used, and which references a removal would break.
  10. A line can show the value of a declared variable, and one if statement can test several conditions in turn.
  11. Variables can hold lists and maps, and a call can pass arguments.
  12. A Visual Studio Code extension highlights .aiko syntax and matches brackets.

You write the story.
It sets the stage.