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