Lattice リファレンス · 4 分の 1

ソースファイルと宣言 ​

この章では、Linear story と CYOA の両プロジェクトで使える共通の構文を定義します。プロジェクトの展開モデルと、ストーリーの同一性およびナラティブの文脈を定めるすべての宣言を扱います。

ドキュメントの形 ​

.la ファイルには、ゼロ個以上のトップレベル項目が含まれます。トップレベルの語彙は次のとおりです。

use "./relative-file.la";

story main (...);
entity character ch_mara (...);
predicate knows (...);
state group location (...);
state st_knows_signal (...): event { ... };
pool investigation (...);
module md_decode (...) { ... }
scene garden (...) { ... }

predicate、state、pool、module は CYOA に属します。Linear プロジェクトで使えるのは、インポート、一つの Story、実体、トップレベルの Scene、およびそれらの Scene に入れ子になった Block とコンテンツだけです。

ファイルとインポート ​

プロジェクト設定は一つの entry ファイル（通常は main.la）を指定します。TypeApe はそこから始め、すべての use を再帰的に展開します。

# main.la
use "./story/entities.la";
use "./story/opening.la";

story main (
  title: "Signal Garden",
  language: "en",
  format: novel,
  entry: opening
);

インポートパスは次の条件を満たします。

• use を含むファイルからの相対的な、引用符付きパスである。
• 開いているプロジェクト内のファイルに解決される。
• .. や外向きのシンボリックリンクで外へ出られない。
• インポートの循環を形成できない。
• 異なる相対パスを通じても、同じファイルを二度読み込めない。

インポートされた宣言は、それをインポートする側の宣言より前に現れます。これは Block のフローを作りませんが、宣言の順序を決定的にし、条件を満たす CYOA Module の提示順を制御します。

展開後、プロジェクト全体には story 宣言がちょうど一つ含まれなければなりません。インポートされるファイルは、別の Story を宣言するのではなく、実体、Scene、State、Module を提供するべきです。

コメント、カンマ、セミコロン ​

行コメントを始めるのは # だけです。// は通常の不正な構文です。

# This is a Lattice comment.
entity item it_key (name: "Signal key"); # trailing comment

メタデータのプロパティとイベントフィールドはカンマで区切ります。末尾のカンマは記述された構文の一部ではないので、最後のプロパティの後には付けません。

識別子、文字列、本文 ​

Lattice は同一性、正確なテキスト、ナラティブ本文を意図的に区別します。

同一性はタイトルではない ​

次の宣言では、ch_mara が安定した同一性で、"Mara" が表示テキストです。

entity character ch_mara (name: "Mara");

読者に見える名前が変わったら name を変更します。ch_mara を変更するのは、実体の同一性が変わったときだけです。その場合はすべての参照を更新し、全体を検証します。ID 参照を引用符で囲まないでください。

# Correct
pov: ch_mara

# Wrong: this is a string, not a character reference
pov: "ch_mara"

本文の波括弧は構文 ​

本文は { で始まり } で終わります。内部の改行と通常の句読点は保持されます。

logline: {
  A patient signal hunter discovers that tomorrow
  has been answering from beneath her garden.
}

ナラティブの段落やテキストメタデータには本文を使います。language のように型が引用符付き文字列を要求するフィールドには、引用符付き文字列を使います。

メタデータ ​

メタデータは宣言 ID の後に丸括弧で続きます。

scene opening_scene (
  title: "Opening",
  beat: opening,
  pov: ch_mara
) {
  # Blocks
}

各キーは一つの宣言につき最大一度だけ現れます。フィールドは所有者ごとに固有で、型検査されます。有効な Scene フィールドでも、Story や Block では無効なことがあります。

未知のキーは、x_ で始まらない限りエラーです。

scene opening_scene (
  title: "Opening",
  x_editor_color: "blue"
) { ... }

x_ メタデータは保持されますが、意味的には不活性です。名前付きの製品機能がその拡張を明示的に定義しない限り、フローを作る、プレビューを変える、State を変更する、診断を回避する、エクスポートに影響する、といったことはできません。

Story 宣言 ​

インポートが展開された後、Story はちょうど一つ存在します。

story main (
  title: "Signal Garden",
  language: "en",
  format: novel,
  entry: opening,
  logline: { A buried signal calls its hunter home. },
  audience: "Young adult",
  content_rating: "Teen",
  genres: [mystery, science_fiction],
  themes: [memory, belonging],
  tags: [draft],
  prose_unit: word_like,
  prose_scope: authored_body,
  prose_minimum: 4500,
  prose_target: 5000,
  prose_maximum: 5500,
  beat_order: [opening, midpoint, resolution]
);

entry はメインストーリーに存在しなければなりません。Module が所有する Block は Story の entry にはできません。Linear story は空のリストも含め、initial_state を宣言してはなりません。

prose_unit、prose_scope、prose_target は一つの任意のゴールを形成し、一緒に宣言しなければなりません。存在する場合、境界は minimum <= target <= maximum を満たす必要があります。word_like は単語に似たトークンを数えます。中国語の文字数で表された依頼には non_whitespace_graphemes を使います。執筆契約に影響するのは TypeApe が所有するフィールドだけです。x_* メタデータは不活性のままです。

実体宣言 ​

宣言の形は entity <kind> <id> (...) です。

entity character ch_mara (
  name: "Mara",
  role: protagonist,
  description: { A patient signal hunter. },
  aliases: ["Mara Venn", "The Listener"],
  traits: [observant, stubborn],
  tags: [cast, point_of_view]
);

entity location loc_garden (
  name: "Signal Garden",
  description: { A buried antenna field beneath wet soil. },
  tags: [exterior]
);

entity item it_key (
  name: "Signal key",
  description: { A warm shard that pulses at midnight. }
);

対応する kind は character、location、item です。すべての実体には name テキストが必要です。

参照は kind ごとに検査されます。対話の話者と Scene の pov は登場人物でなければならず、Scene の location は場所でなければなりません。CYOA の Predicate タプルも、各実体が宣言されたフィールド kind と一致することを確認します。

Scene 宣言 ​

Scene は、共有されたナラティブの文脈の下に Block をまとめます。

scene garden (
  title: "The garden",
  summary: { Mara hears the buried signal. },
  beat: opening,
  pov: ch_mara,
  location: loc_garden,
  time: "before dawn",
  tone: [quiet, uneasy],
  prose_target: 1200,
  tags: [chapter_one]
) {
  block opening (...) { ... }
}

トップレベルの Scene はメインストーリーに属します。Module に入れ子になった Scene は、その Module にのみ属します。すべての Block は Scene の所有者を継承し、フローの対象はメインストーリーから Module へ、Module 間で、Module からメインストーリーへと越えられません。

Scene の prose_target は再配分可能な草稿予算であり、単独の有効性のしきい値ではありません。完全な Story の本文ゴールが必要です。

安全な複数ファイル構成 ​

project/
├── main.la
└── story/
    ├── entities.la
    ├── opening.la
    └── ending.la

# main.la
use "./story/entities.la";
use "./story/opening.la";
use "./story/ending.la";

story main (
  title: "Signal Garden",
  language: "en",
  format: novel,
  entry: opening
);

インポートは宣言を整理するもので、ナラティブの順序を含意しません。次の章では Block、コンテンツ、注釈、線形フローを定義します。