プロジェクトファイルとチェック

エージェントのために。作業するファイルのこと。

エージェントはプロジェクトファイルの中で作業し、Kit の結果を読み取ります。完全なリファレンスは Kit 付属のガイドにあります。

プロジェクトファイル

スクリプト、レイアウト、翻訳、プロジェクト設定はテキストファイルです。

スクリプト

.aiko スクリプトにはラベル、台詞、選択肢、演出のコマンドが書かれます。キャラクター、素材、変数は project.json で宣言します。スクリプトには、プログラミング言語は組み込まれていません。

チェック

validate の検出結果には固定のコードと重大度があり、ソース上の位置があればファイル、行、列も示されます。

walk は、ブラウザなしで物語のルートを一本たどります。ルートごとに一度ずつ実行します。

キャプチャ

capture は指定した台詞の画面を PNG 画像として記録し、位置と動きを JSON に残します。capture-compare は 2 つのキャプチャの違いを報告し、どちらも書き換えません。

validate --browser は、宣言したすべてのロケールで、台詞と全画面テキストが 1920×1080、1280×720、800×600、844×390、390×844 に収まることを確かめます。

はじめの一歩

スタータープロジェクト:最初の数行からキャプチャまで

下のスクリプトはスタータープロジェクトの冒頭です。4 つのコマンドは Kit のフォルダで実行します。

story/main.aiko · スタータープロジェクトの冒頭

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

    Kit のフォルダでガイドを開く。

    aikotoba.cmd docs
  2. 2

    starter-project をコピーし、AGENTS.md を読んでから、コピーを検証する。

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

    ルートをたどる。この例では、最初の選択肢で 2 番目の項目を選ぶ。

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

    台詞を 1 つ、プロジェクトと 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

    Kit のフォルダでガイドを開く。

    sh ./aikotoba docs
  2. 2

    starter-project をコピーし、AGENTS.md を読んでから、コピーを検証する。

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

    ルートをたどる。この例では、最初の選択肢で 2 番目の項目を選ぶ。

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

    台詞を 1 つ、プロジェクトと 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 · 想定される Kit の出力:スタータープロジェクトのコピーで、5 行目の {i} が閉じられていない場合

> 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 はまだ開発中です。 以下の機能の一部はプライベートベータにまだ入っておらず、どの機能も変わることがあります。

エージェント向けの詳細

12 項目
  1. 台詞には固定の @id を付けられます。セーブデータ、巻き戻し、翻訳ファイルはこの ID を使い、重複した ID は validate がエラーとして報告します。
  2. --format json に対応したコマンドは、スキーマを公開している、バージョン番号付きのプロトコルで応答します。
  3. スタータープロジェクトには AGENTS.md とプロジェクトスキルが付属します。スキルはエージェントに、物語のテキスト、コメント、読み込んだファイルを指示ではなくデータとして扱うよう伝えます。
  4. capture、preview、validate --browser には、インストール済みの Chrome か Edge、macOS では Chrome か Chromium を使います。
  5. Aikotoba は AI モデルを呼び出しません。プロジェクトを編集し、Kit のコマンドを実行するのはあなた自身のエージェントです。
  6. Kit の JSON コマンドは、エージェントから MCP ツールとしても使え、結果は同じです。
  7. キャプチャを実行すると、記録したエビデンスの索引ページが作られます。
  8. 構造化編集では、台詞や選択肢の追加、台詞 ID の変更ができ、ほかの ID は変わりません。どの編集も適用前に変更内容を示し、検証に失敗すれば何も変更されません。
  9. 参照レポートは、指定した変数・ラベル・キャラクター・衣装・素材が使われている場所と、削除すると壊れる参照を一覧にします。
  10. 台詞に宣言済みの変数の値を表示でき、1 つの if 文で複数の条件を順に判定できます。
  11. 変数にはリストやマップを入れられ、呼び出しでは引数を渡せます。
  12. Visual Studio Code の拡張機能で、.aiko の構文が色分けされ、対応する括弧が強調表示されます。

物語は、あなたの手で。
舞台は、AIの手で。