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
.aikoscript holds labels, lines, choices and staging commands. Characters, assets and variables are declared inproject.json. The script has no embedded programming language.- Checks
validatereports each finding with a stable code and a severity, and with the file, line and column when the finding has a source position.walkfollows one route through the story without a browser. Run it once for each route.- Captures
capturerecords the screen at a chosen line as PNG images and as JSON records of geometry and motion.capture-comparereports the differences between two captures and changes neither of them.validate --browserchecks 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
Open the guide in the Kit folder.
aikotoba.cmd docs
- 2
Copy
starter-project, read itsAGENTS.md, then validate the copy.aikotoba.cmd validate --project <copy>
- 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
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
Open the guide in the Kit folder.
sh ./aikotoba docs
- 2
Copy
starter-project, read itsAGENTS.md, then validate the copy.sh ./aikotoba validate --project <copy>
- 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
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- A line can carry a stable
@id. Saves, rollback and translation files use these IDs, andvalidatereports a repeated ID as an error. - Commands that take
--format jsonanswer in a versioned protocol with a published schema. - The starter project includes
AGENTS.mdand a project skill. The skill tells the agent to treat story text, comments and imported files as data, not as instructions. capture,previewandvalidate --browseruse an installed Chrome or Edge, or Chrome or Chromium on macOS.- Aikotoba does not call an AI model. Your own agent edits the project and runs the Kit's commands.
- The Kit's JSON commands are also available to the agent as MCP tools, with the same results.
- A capture run writes an index page of the evidence it recorded.
- 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.
- A reference report lists where a given variable, label, character, costume or asset is used, and which references a removal would break.
- A line can show the value of a declared variable, and one
ifstatement can test several conditions in turn. - Variables can hold lists and maps, and a call can pass arguments.
- A Visual Studio Code extension highlights
.aikosyntax and matches brackets.