@liminalia/runtime 0.0.0-stage → 0.8.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/LICENSE +106 -0
  2. package/dist/src/chat.js +60 -0
  3. package/dist/src/commands-play.js +300 -0
  4. package/dist/src/commands.js +534 -0
  5. package/dist/src/coverage.js +208 -0
  6. package/dist/src/headless.js +109 -0
  7. package/dist/src/host.js +1 -0
  8. package/dist/src/index.js +15 -0
  9. package/dist/src/prefetch.js +80 -0
  10. package/dist/src/program.js +131 -0
  11. package/dist/src/project-options.js +84 -0
  12. package/dist/src/retranslate.js +44 -0
  13. package/dist/src/route.js +242 -0
  14. package/dist/src/runtime.js +1929 -0
  15. package/dist/src/save.js +51 -0
  16. package/dist/src/scenario-test.js +200 -0
  17. package/dist/src/state.js +62 -0
  18. package/dist/src/value.js +464 -0
  19. package/dist/src/voice-observe.js +82 -0
  20. package/package.json +33 -4
  21. package/src/chat.ts +109 -0
  22. package/src/commands-play.ts +280 -0
  23. package/src/commands.ts +457 -0
  24. package/src/coverage.ts +257 -0
  25. package/src/headless.ts +139 -0
  26. package/src/host.ts +116 -0
  27. package/src/index.ts +16 -0
  28. package/src/prefetch.ts +78 -0
  29. package/src/program.ts +186 -0
  30. package/src/project-options.ts +128 -0
  31. package/src/retranslate.ts +67 -0
  32. package/src/route.ts +365 -0
  33. package/src/runtime.ts +2143 -0
  34. package/src/save.ts +60 -0
  35. package/src/scenario-test.ts +218 -0
  36. package/src/state.ts +353 -0
  37. package/src/value.ts +443 -0
  38. package/src/voice-observe.ts +85 -0
  39. package/types/src/chat.d.ts +63 -0
  40. package/types/src/commands-play.d.ts +2 -0
  41. package/types/src/commands.d.ts +2 -0
  42. package/types/src/coverage.d.ts +100 -0
  43. package/types/src/headless.d.ts +77 -0
  44. package/types/src/host.d.ts +140 -0
  45. package/types/src/index.d.ts +16 -0
  46. package/types/src/prefetch.d.ts +18 -0
  47. package/types/src/program.d.ts +107 -0
  48. package/types/src/project-options.d.ts +103 -0
  49. package/types/src/retranslate.d.ts +39 -0
  50. package/types/src/route.d.ts +181 -0
  51. package/types/src/runtime.d.ts +553 -0
  52. package/types/src/save.d.ts +21 -0
  53. package/types/src/scenario-test.d.ts +43 -0
  54. package/types/src/state.d.ts +357 -0
  55. package/types/src/value.d.ts +61 -0
  56. package/types/src/voice-observe.d.ts +26 -0
  57. package/README.md +0 -3
@@ -0,0 +1,553 @@
1
+ import { type AutoLayoutRules, type EndingKinds, CORE_COMMANDS, type CastEntry, type ChapterInfo, type CommandDefaults, type CommandSpec, type Diagnostic, type Expr, type Inline, type Registry, type Script, type VoiceLock } from "@liminalia/lang";
2
+ import { type ChatDialogue } from "./chat.js";
3
+ import type { Host, PresentEvent } from "./host.js";
4
+ import { type Program } from "./program.js";
5
+ import { type GameState, type Position, type SaveData, type Snapshot } from "./state.js";
6
+ import { type Scope, type Value } from "./value.js";
7
+ export type Args = Record<string, Value>;
8
+ export interface CommandContext {
9
+ runtime: Runtime;
10
+ state: GameState;
11
+ /** 状態を更新したあとに呼び、描画側に反映させる。 */
12
+ present(args: Args, wait: boolean): Promise<Value | void>;
13
+ signal: AbortSignal;
14
+ /** @end までの行をそのまま持つ命令(@html)の中身(字下げをそろえたもの)。ほかの命令では無い。 */
15
+ body?: string;
16
+ /**
17
+ * 式(`(…)`)で書いた引数の、式の元の文字(括弧の中。引数の名前 → 文字)。値は args に評価済みで入る。変数が変わるたびに
18
+ * 評価し直したい命令(常駐の表示の if= など)が、式を状態に残すのに使う。
19
+ */
20
+ sources?: Readonly<Record<string, string>>;
21
+ /**
22
+ * この命令の実行中にセーブされたら、この命令からやり直すようにする(UI を出して結果を待つ命令用)。
23
+ * 命令が終われば元に戻る。
24
+ */
25
+ resumeHere(): void;
26
+ /**
27
+ * 選択肢を出して選ばせる(選んだ番号。null なら実行を終える)。プラグインの命令が自分の画面で行き先を選ばせるとき、
28
+ * 描画側が答えを返さない(画面なしで流す: 道筋の探索・網羅・lim trace)場合はこれで選ぶ。そうすると、探索や網羅が
29
+ * ふつうの選択肢と同じく選び方を変えて流せる。targets は選択肢ごとの飛び先("ファイル" か "ファイル#ラベル"。分かれば)。
30
+ */
31
+ choose(options: string[], targets?: (string | null)[]): Promise<number | null>;
32
+ /**
33
+ * 行き先を選ばせる命令の結果を決める。outcomes は起こりうる結果の一覧(見出し・飛び先・値)で、行き先はここに一度だけ書く。
34
+ * answer は描画側が返した答えを命令が読み替えたもの。あればそれを返し、無ければ(画面なしで流すとき)一覧をそのまま
35
+ * choose に渡して選んだものの値を返す(先頭が既定の選び方)。こうすると、探索や網羅が一覧のどの行き先も試せる。
36
+ * null なら実行を終える(一覧が空のときも null)。
37
+ */
38
+ pick<T>(outcomes: readonly PickOutcome<T>[], answer?: T | null): Promise<T | null>;
39
+ /**
40
+ * おまけの CG の画像を解放する(@cg-unlock と同じ。全セーブ共通の system.cg_unlocked に入れる)。image は extra.cg の images に書いたパス。
41
+ * 調べる場所の一時の絵など、命令が自分で出した絵を CG にするときに、system 変数を直に触らずに使う。画面なしで流すときも同じに効く。
42
+ */
43
+ unlockCg(image: string): void;
44
+ /**
45
+ * 作品のデータ(paths.data の .json。`items` と `items.json` は同じ)を読む。無い・読めないなら undefined。
46
+ * 同じ実行器の中では一度だけ読む(読み直すには作り直す)。返す値は書き換えない。
47
+ */
48
+ data(name: string): Promise<unknown>;
49
+ /**
50
+ * この命令を描画側へ渡すのを、次の場面の切れ目まで待たせる(@notify when=scene-break)。present の代わりに呼ぶ。
51
+ * 場面の切れ目は @scene-change、背景の切り替え(@bg で別の絵)、暗転(@mask)、@jump と選択肢でほかのファイル(章)へ移ったとき。
52
+ * 切れ目を過ぎたら、次の本文か選択肢を出す前に、引数をそのまま描画側へ渡す(待たない)。待っているものはセーブに入り、
53
+ * 渡したものはその後のセーブから外れるので、待っている間にセーブとロードをしても消えず、二度も出ない。
54
+ */
55
+ atSceneBreak(args: Args): void;
56
+ }
57
+ /** ctx.pick の結果の一つ。target はその結果で飛ぶ先("ファイル" か "ファイル#ラベル"。分からなければ null)。 */
58
+ export interface PickOutcome<T> {
59
+ label: string;
60
+ target: string | null;
61
+ value: T;
62
+ }
63
+ /** 命令の実装。仕様(spec)はレジストリと共有する。 */
64
+ export interface CommandImpl {
65
+ spec: CommandSpec;
66
+ run(args: Args, ctx: CommandContext): void | Promise<void>;
67
+ /**
68
+ * 自動確認(Host.automated。lim playtest・lim shot・全ルートテスト)での進め方。あれば、ctx.present は描画側へ描かせずに
69
+ * これを呼び、返した値を描画側の答えの代わりにする(args は ctx.present に渡したもの)。何も返さなければ答えなしで、
70
+ * ctx.pick・ctx.choose で行き先を選ぶ命令は、ふつうの選択肢と同じく自動確認が選ぶ。遊ぶ人の操作を待つ画面や、飛ばしたい動画の命令に書く。
71
+ */
72
+ autoplay?(args: Args, ctx: CommandContext): Value | void | Promise<Value | void>;
73
+ }
74
+ /**
75
+ * 実行器をまたいで使う、読んだ台本の控え(ファイル → 本文と、それを読み解いたもの)。巻き戻しやロードで実行器を作り直しても、
76
+ * 本文が同じなら読み解き直さない。本文が変われば(開発中の書き換え)読み直す。中身は読むだけで書き換えない。
77
+ */
78
+ export type ProgramCache = Map<string, {
79
+ source: string;
80
+ speakers: string;
81
+ program: Program;
82
+ script: Script;
83
+ }>;
84
+ export interface RuntimeOptions {
85
+ /** 実行器をまたいで使う読んだ台本の控え(遊ぶ側が一回のプレイを作り直すたびに渡す)。 */
86
+ programCache?: ProgramCache;
87
+ /** 話者として認める名前(project.lim.json の speakers)。 */
88
+ speakers?: Iterable<string>;
89
+ /** 作品固有の命令。組み込みの命令と同名なら上書きする。 */
90
+ commands?: CommandImpl[];
91
+ /**
92
+ * 作品ごとのコマンドの既定値(liminalia.json の commandDefaults。@liminalia/lang の CommandDefaults)。シナリオで省いたパラメータに使う。
93
+ * 組み込みの命令にもプラグインの命令にも効く(使えない値は使わない。検査が知らせる)。
94
+ */
95
+ commandDefaults?: CommandDefaults;
96
+ /** 乱数のシード。 */
97
+ seed?: number;
98
+ /** 無限ループ対策。既定 1,000,000 命令。 */
99
+ maxSteps?: number;
100
+ /**
101
+ * 作品のデータを読む(命令の ctx.data。ホストが loadData を持たないとき、画面なしで流す網羅や探索に渡す)。
102
+ * name は paths.data からのパス(`.json` 付き)。無ければ undefined を返す。
103
+ */
104
+ loadData?(name: string): unknown;
105
+ /** 実行時エラーで止めるか(既定)、報告して続けるか。 */
106
+ onError?: "stop" | "continue";
107
+ /**
108
+ * @call で呼ばれていない所の @return を、誤りにせずに次の行へ進むか(lim coverage と全ルートテストのファイルごとの流し。
109
+ * @call で呼ぶだけのファイルも先頭から流すので、ラベルごとの @return は呼ばれずに通る)。既定は誤り。
110
+ */
111
+ returnWithoutCall?: "error" | "continue";
112
+ /**
113
+ * 変数に値を入れたときに呼ぶ(@set・@let・命令の結果を受け取る setVariable)。制作画面が「その値を決めた行」を示すのに使う。
114
+ * path は game.x・system.x・temp.x(入れ子は game.a.b)か、局所変数の名前。value は入れたあとの値。at はその命令の行。
115
+ */
116
+ onAssign?(path: string, value: Value, at: {
117
+ file: string;
118
+ line: number;
119
+ }): void;
120
+ /**
121
+ * 一つの命令(本文・選択肢・ラベル・@if なども含む)を実行する直前に呼ぶ。at はその命令の行。
122
+ * このときの save() は、その命令から再開するセーブ(=前の命令を実行した直後の状態)になる。
123
+ * 制作画面が、命令の行を実行した直後の状態を控えるのに使う。
124
+ */
125
+ onStep?(at: {
126
+ file: string;
127
+ line: number;
128
+ }): void;
129
+ /**
130
+ * 一つの命令を実行する直前に呼び、Promise を返したら解決するまでその命令を実行しない(制作画面のブレークポイント)。
131
+ * 待っているあいだに捨てられた(dispose した)実行器は、そこで止まる。
132
+ */
133
+ beforeStep?(at: {
134
+ file: string;
135
+ line: number;
136
+ }): Promise<void> | void;
137
+ /** 変数の初期値(liminalia.json の variables。"game.x"・"system.x" → 値)。 */
138
+ variables?: Readonly<Record<string, Value>>;
139
+ /** 式の lang() が返す言語(省くと ""。描画側は遊んでいる言語、画面なしで流すものは原文の言語を入れる)。runtime.language で替えられる。 */
140
+ language?: string;
141
+ /** 訳(多言語)。runtime.translator で替えられる。省けば訳さない。 */
142
+ translator?: Translator | null;
143
+ /** 式の platform()・app() が返す機種(省くとパソコンのブラウザ)。 */
144
+ platform?: Platform;
145
+ /** 章の情報(liminalia.json の chapters)。式の chapter() と runtime.chapter が読む。 */
146
+ chapters?: readonly ChapterInfo[];
147
+ /** 数を数える実績の目標(liminalia.json の extra.achievements の id → goal)。@achieve-progress が届いたら解除する。 */
148
+ achievementGoals?: Readonly<Record<string, number>>;
149
+ /**
150
+ * 見たエンディングの数で進める実績(extra.achievements の endings。id → 種類("*" はどれも)と goal。@liminalia/lang の endingAchievements)。
151
+ * プレイを終える命令を動かすたびに、その種類のエンディングを見た数を今の数にし、goal に届いたら解除する。
152
+ */
153
+ endingAchievements?: Readonly<Record<string, {
154
+ endings: string;
155
+ goal: number;
156
+ }>>;
157
+ /** 作品が足したエンディングの種類(liminalia.json の endingKinds)。ending= を種類として読み、前の書き方の文言と見分けるのに使う。 */
158
+ endingKinds?: unknown;
159
+ /**
160
+ * キャストの定義(cast.json の cast)。あれば @chara のたびに、無い立ち絵セット・差分・立ち位置を実行時の診断で知らせる
161
+ * (検査で拾えない、書かなかった値を保った結果の組み合わせも)。
162
+ */
163
+ cast?: Readonly<Record<string, CastEntry>>;
164
+ /** 立ち絵の登場順の自動配置の並べ方(liminalia.json の autoLayout を autoLayoutRules で読み解いたもの)。省けば前からの並べ方。 */
165
+ autoLayout?: AutoLayoutRules;
166
+ /**
167
+ * 連番のボイスの番号の固定(voice-lock.json)。あれば @voice-auto は台詞ごとに固定した番号を鳴らし、
168
+ * 固定に無い台詞は鳴らさない(数え方の番号は、行を足すとずれるため)。
169
+ */
170
+ voiceLock?: VoiceLock | null;
171
+ /**
172
+ * ロードの直後に呼び出す位置(`ファイル#ラベル`。liminalia.json の afterLoad)。セーブに入らない temp を計算し直すなど。
173
+ * @return でロードしたページへ戻る。
174
+ */
175
+ afterLoad?: string;
176
+ /**
177
+ * CG として解放する画像か(@liminalia/lang の cgMatcher(extra)。liminalia.json の extra.cg と extra.cgAuto)。あれば、CG として解放する印の
178
+ * あるパラメータ(@bg の image など)で出した画像を system.cg_unlocked に入れる。描画しない実行(道筋の探索・網羅)やスキップ中でも同じに効く。
179
+ */
180
+ cg?: (folder: string, image: string) => boolean;
181
+ /**
182
+ * 読み終えたページと選んだ選択肢をチャットの列に積む(ui.chat.dialogue のとき。stage.extra の "std.chat")。
183
+ * セーブから組み立て直すので、画面なしで流して状態を作るもの(道筋の探索など)にも同じ値を渡す。
184
+ */
185
+ chatDialogue?: ChatDialogue;
186
+ /**
187
+ * 選択肢を本文の流れに出す(ui.choice.position が inline のとき)。@nvl の間、選んだ選択肢を本文の一部として stage.nvlPages に残し、
188
+ * ロードで描画側が出し直せるようにする。描画の出し方は描画側(dom-host)が決める。
189
+ */
190
+ inlineChoices?: boolean;
191
+ /**
192
+ * 台詞の外側の括弧と引用符を外すか(ui.text.quotes が strip。遊んでいる言語の ui.languages を重ねたもの)。台詞のページを出すたびに呼ぶ。
193
+ * true なら本文(訳があれば訳)の外側の一組の「…」『…』“…”"…" を外してから描画側へ送る(メッセージ枠・NVL・履歴・吹き出しに同じく効く)。
194
+ */
195
+ stripQuotes?: () => boolean;
196
+ /**
197
+ * 作品の版(liminalia.json の version)。セーブに入れ、式の save.version で読める(ロードの後の処理 afterLoad で、
198
+ * 前の版のセーブの変数を付け替えるため)。
199
+ */
200
+ gameVersion?: string;
201
+ }
202
+ /** start の指定。 */
203
+ export interface StartOptions {
204
+ /** おまけの回想として再生するなら、その id(式の replaying() が true になる)。 */
205
+ replay?: string;
206
+ /** 始める前に入れる変数("game.x"・"temp.x" → 値。回想の variables)。初期値より優先する。 */
207
+ variables?: Readonly<Record<string, Value>>;
208
+ }
209
+ /**
210
+ * 訳(多言語)。本文の行・選択肢の文は、ファイル名と原文(printInline で書き直したもの)から訳を引く。
211
+ * 訳が無ければ null を返し、原文を出す。話者名は出すときだけ訳す。
212
+ * arg はコマンドの文字(仕様で translate: "text" の引数。引数を読むときに訳す)、text は作品の設定の文字(liminalia.json の章の題など)。
213
+ * context は実行している場面(直前のラベルの名前。無ければ "")。訳のファイルに場面ごとの訳(contexts)があればそちらを使う。
214
+ * id は行末に書いた固定の行 ID(#line:ID)。あれば原文ではなく ID で訳を引く(原文を書き換えても訳が外れない)。
215
+ */
216
+ export interface Translator {
217
+ line(file: string, source: string, context?: string, id?: string): Inline[] | null;
218
+ option(file: string, source: string, context?: string, id?: string): Inline[] | null;
219
+ speaker(name: string): string | null;
220
+ arg?(file: string, source: string, context?: string): string | null;
221
+ text?(source: string): string | null;
222
+ }
223
+ export type RunResult = {
224
+ reason: "end";
225
+ at: Position;
226
+ } | {
227
+ reason: "stopped";
228
+ at: Position;
229
+ } | {
230
+ reason: "max-steps";
231
+ at: Position;
232
+ } | {
233
+ reason: "error";
234
+ at: Position;
235
+ message: string;
236
+ };
237
+ export declare class Runtime {
238
+ private readonly host;
239
+ state: GameState;
240
+ /** 全セーブ共通の変数。保存は Host 側で行う。 */
241
+ system: Scope;
242
+ /** 訳(多言語)。null なら原文。遊んでいる途中で言語を替えたら、次のページから効く。 */
243
+ translator: Translator | null;
244
+ private readonly programs;
245
+ private readonly implementations;
246
+ readonly registry: Registry;
247
+ private readonly speakers;
248
+ private readonly maxSteps;
249
+ private readonly onError;
250
+ private readonly returnWithoutCall;
251
+ private readonly onAssign;
252
+ private readonly onStep;
253
+ private readonly beforeStep;
254
+ /** ロードの直後に呼び出す位置(options.afterLoad)。 */
255
+ private readonly afterLoad;
256
+ /** 作品のコマンドの既定値(options.commandDefaults)。@define のマクロを呼ぶときに重ねる。 */
257
+ private readonly commandDefaults;
258
+ /** 変数の初期値(options.variables を置き場所ごとに分けたもの)。 */
259
+ private readonly gameDefaults;
260
+ private readonly systemDefaults;
261
+ /** 実行中の命令(at が返す)。 */
262
+ private currentUnit;
263
+ private currentLine;
264
+ private halt;
265
+ /** 表示中のページや選択肢の位置。この間にセーブしたら、ここから再開する。 */
266
+ private resumeAt;
267
+ /**
268
+ * メッセージ枠のページをクリックで送ったあと、まだ命令を描画側に渡していない(TyranoScript の [p] の改ページと同じく、
269
+ * 次に渡す命令に afterPage を付け、描画側がそこで前のページの本文を消す)。NVL、チャットの画面、{noclick} のページでは立てない。
270
+ */
271
+ private pageRead;
272
+ /**
273
+ * resumeAt に着いた時点の状態。ページの途中でセーブしたら、位置だけでなく状態もページの頭のものにする。
274
+ * そうしないと、ロードしてページを頭から流し直したとき、本文中の命令({@…})が二度効く。
275
+ */
276
+ private resumeState;
277
+ private steps;
278
+ /** 本文のページを出している最中か(本文の中の命令を実行しているとき true)。 */
279
+ private inPage;
280
+ /** 出しているページの話者(地の文と、ページの外は null)。 */
281
+ private pageSpeaker;
282
+ private readonly abort;
283
+ private readonly voiceLock;
284
+ /** CG として解放する画像か(options.cg)。 */
285
+ private readonly isCg;
286
+ /** ふだんの台詞をチャットの列に積む設定(options.chatDialogue)。無ければ null。 */
287
+ readonly chatDialogue: ChatDialogue | null;
288
+ /** 台詞の外側の括弧と引用符を外すか(options.stripQuotes)。 */
289
+ private readonly stripQuotes;
290
+ /** 作品の版(options.gameVersion。無ければ空)。 */
291
+ private readonly gameVersion;
292
+ /**
293
+ * 作ったときの設定(渡したものそのまま)。同じ作品を画面なしで先へ流す実行器(@liminalia/web の「次の選択肢へ」「次の未読へ」)を、
294
+ * 遊んでいる実行器と同じ設定で作るのに使う。言語と訳は作ったあとにも替わるので、今の値は language と translator を読む。
295
+ */
296
+ readonly options: Readonly<RuntimeOptions>;
297
+ constructor(host: Host, options?: RuntimeOptions);
298
+ /**
299
+ * target(`chapter1`・`chapter1#start`)から実行を始める。
300
+ * temp(そのプレイ中だけの変数)は引き継ぐ。タイトル画面などが始める前に temp を入れておけるようにするため(load と同じ)。
301
+ */
302
+ start(target: string, options?: StartOptions): Promise<RunResult>;
303
+ /** system の変数のうち、まだ値の無いものを初期値にする。 */
304
+ private fillSystemDefaults;
305
+ /** 現在の状態をセーブデータにする。ページや選択肢の途中なら、そのページ(選択肢)から再開する位置にする。 */
306
+ save(): SaveData;
307
+ /** 読み込み済みの実行単位(無ければ undefined。save は同期なので読み込まない)。 */
308
+ private loadedUnit;
309
+ /**
310
+ * 呼び出しの戻り先の目印。戻り先の一つ前が呼んだ命令(@call・マクロ・@with の中身)ならその命令(after)、
311
+ * そうでなく戻り先が選択肢(call=true の選択肢は、その選択肢へ戻る)ならその選択肢。
312
+ */
313
+ private returnAnchor;
314
+ /** その位置の命令の目印(本文・選択肢の行と文の鍵。ほかの命令は付けない)。読み込み済みの単位だけ(save は同期なので)。 */
315
+ private anchorOf;
316
+ /**
317
+ * セーブした位置を、今の台本に合わせる。目印の鍵(本文・選択肢の文)が同じ命令があればそこ(いくつもあれば元の行に近いもの)、
318
+ * 無ければ元の行にいちばん近い本文か選択肢。合わせ直したら知らせる(作品を更新して台本が変わったとき)。
319
+ */
320
+ private relocate;
321
+ /**
322
+ * 呼び出しの戻り先を、今の台本に合わせる。目印があれば同じ命令(呼んだ命令の次か、call=true の選択肢)を探す(いくつもあれば元の行に近いもの)。
323
+ * 目印の無い前の版のセーブは、戻り先の一つ前が呼んだ命令でも選択肢でもない(行がずれている)ときだけ、呼ばれた先を呼ぶ命令のうち
324
+ * 元の位置にいちばん近いものの次へ直す。見つからなければそのまま。直したら知らせる(save-relocated)。
325
+ */
326
+ private relocateReturns;
327
+ /**
328
+ * セーブデータから再開する。描画側には現在の状態をそのまま渡し直す。
329
+ * options.call は、再開したページから場面(`#ラベル`・`ファイル#ラベル`)を呼ぶ(常駐のボタンの call=)。呼んだ場面は @return か、
330
+ * 次のラベルかファイルの終わりで戻り、そのページを出し直す。options.afterLoad を false にすると、作品の afterLoad を呼ばない
331
+ * (同じプレイの続きを組み立て直すとき)。
332
+ */
333
+ load(raw: SaveData, options?: {
334
+ call?: string;
335
+ afterLoad?: boolean;
336
+ }): Promise<RunResult>;
337
+ stop(): void;
338
+ /**
339
+ * 命令から場面(`#ラベル`・`ファイル#ラベル`)を呼び出す。呼んだ場面が次のラベルかファイルの終わりに着いたら、@return を書かなくても戻る。
340
+ * again なら、戻ったときにこの命令をもう一度実行する(調べる場所の画面を出し直すなど)。そうでなければ次の行へ進む。
341
+ * 場面の中で @jump したり選択肢でほかへ飛んだりしたら戻らない(@return を書けば、そこで戻る)。
342
+ */
343
+ callScene(target: string, again?: boolean, from?: "command" | "here"): Promise<void>;
344
+ /** 場面の呼び出しの枠から戻る(次のラベルかファイルの終わりに着いた)。 */
345
+ private returnFromScene;
346
+ /** 場面の呼び出しの中で、ほかへ飛んだ(戻らない)。 */
347
+ private leaveScene;
348
+ /** 読んだ作品のデータ(名前 → 値)。 */
349
+ private readonly dataCache;
350
+ private readonly dataLoader;
351
+ /** 作品のデータを読む(ctx.data)。ホストが読めなければ undefined。 */
352
+ loadData(name: string): Promise<unknown>;
353
+ /** 命令から飛ぶ(`ファイル`・`#ラベル`・`ファイル#ラベル`)。 */
354
+ jump(target: string): Promise<void>;
355
+ /** `game.x` のような変数に値を入れる(命令の結果を受け取るとき)。 */
356
+ setVariable(path: string, value: Value): void;
357
+ /** キャストの定義(options.cast)。開発中に cast.json を書き換えたときは、プレイヤーが差し替える。 */
358
+ cast: Readonly<Record<string, CastEntry>> | undefined;
359
+ /** 立ち絵の登場順の自動配置の並べ方(options.autoLayout)。開発中に liminalia.json を書き換えたときは、プレイヤーが差し替える。 */
360
+ autoLayout: AutoLayoutRules | undefined;
361
+ /** 実行中の命令の行に診断を出す(命令の実装が、止めずに知らせたいとき)。 */
362
+ report(severity: Diagnostic["severity"], code: string, message: string): void;
363
+ /** 実行中の命令の位置(ファイルと行)。始める前は null。 */
364
+ get at(): {
365
+ file: string;
366
+ line: number;
367
+ } | null;
368
+ /**
369
+ * 今いるファイルとラベル(その位置より前で最後のラベル。ラベルより前なら label は null)。@define の中なら、呼び出したところ。
370
+ * セーブの一覧に章の名前を出すのに使う。読み込む前は null。
371
+ */
372
+ get label(): {
373
+ file: string;
374
+ label: string | null;
375
+ } | null;
376
+ waitClick(): Promise<void>;
377
+ /** 読み込んだファイルの、本文の行 → ページの鍵(既読を覚えるのに使う)。まだ読み込んでいなければ undefined。 */
378
+ pageKeysOf(file: string): ReadonlyMap<number, string> | undefined;
379
+ /** 本文のページを出している最中か(@voice が「その場で鳴らす」か「次の台詞で鳴らす」かを決める)。 */
380
+ get speaking(): boolean;
381
+ /** 出しているページの話者(地の文と、ページの外は null)。本文の中の @voice のフィルターに使う。 */
382
+ get speakerNow(): string | null;
383
+ dispose(): void;
384
+ /** 今の状態を取っておく。位置は実行中の命令の次。 */
385
+ snapshot(): Snapshot;
386
+ /**
387
+ * 取っておいた状態に戻り、描画側に画面を組み立て直させる。
388
+ * keepVariables なら game. は今の値を、keepBgm なら BGM は今鳴っているものを残す。
389
+ */
390
+ restoreSnapshot(snapshot: Snapshot, o: {
391
+ keepVariables: boolean;
392
+ keepBgm: boolean;
393
+ }): Promise<void>;
394
+ run(): Promise<RunResult>;
395
+ private execute;
396
+ private say;
397
+ private sayPage;
398
+ /**
399
+ * 名前欄に出す名前(話者と違うときだけ。同じなら null)。この行の {name …}、無ければ @name で替えた名前、どちらも無ければ話者名。
400
+ * 訳があれば訳す(表示名の訳は、話者名と同じく訳のファイルの speakers に書く)。
401
+ */
402
+ private speakerLabel;
403
+ /** 名前欄に出す名前の原文(この行の {name …}、無ければ @name で替えた名前、どちらも無ければ話者名)。 */
404
+ private shownName;
405
+ /**
406
+ * 置いたままの文字(stage.extra の中の、i18n を持つもの。retranslate.ts)を、今の言語(translator)で書き換える。
407
+ * ロードしたときと巻き戻したときに呼び、言語を替えたときはシステム画面が呼んで描画側に出し直させる。書き換えたものがあれば true。
408
+ */
409
+ retranslate(): boolean;
410
+ /** 読み終えた本文の一ページを、元(origin)から今の言語で作り直す。変わったら true。 */
411
+ private retranslatePage;
412
+ private retranslateField;
413
+ /** 本文を、描画側に送るのと同じ一片の並びにする(本文中の命令とクリック待ちは除く。式はいまの値)。 */
414
+ private partsOf;
415
+ /** 選んだ選択肢を自分の吹き出しとして積み、描画側へ知らせる(ui.chat.dialogue のとき。絵のボタン・押せる範囲は積まない)。 */
416
+ private chatChosen;
417
+ /**
418
+ * このページで鳴らすボイス。@voice で決めたものがあればそれ、なければ話者の連番(番号を一つ進める)。
419
+ * 番号の固定があれば、その台詞に固定した番号(固定に無い台詞は鳴らさない)。
420
+ */
421
+ private takeVoice;
422
+ private nextVoice;
423
+ /** その台詞に固定したボイスの番号(固定が無い・その台詞が無ければ null)。 */
424
+ private lockedVoice;
425
+ /** この先の台詞で鳴る連番のボイス(先読み用。分岐は両方とも数えるので、番号は目安)。 */
426
+ private voicePrefetch;
427
+ private plain;
428
+ /** plain と partsOf が出し分けを読むときの鍵の頭(ファイルと原文)と、何番目か。advance でなければ前に出したものを読む。 */
429
+ private variantScope;
430
+ private withVariants;
431
+ /** withVariants の中なら、その鍵で出し分けを選ぶ。外なら頭のもの(表示名の {name …} の中など)。 */
432
+ private scopedVariant;
433
+ /**
434
+ * 出し分けで今回出すもの。advance なら通った回数を一つ進めて選び(seq は最後で止まる、cycle は頭に戻る、once は出し終えたら何も出さない、
435
+ * shuffle は乱数で、前と同じものを続けない)、advance でなければ前に出したものを返す(言語を替えて出し直すとき)。
436
+ */
437
+ private variantItem;
438
+ /**
439
+ * 条件(@if、@elif、@while、@for、行の if=、選択肢の if= locked= call=)の式を真偽にする。式が誤りなら、誤りを知らせて偽として扱う
440
+ * (真の枝へ黙って入らない。初期値の無い変数を数と比べたときなど)。
441
+ */
442
+ private condition;
443
+ /**
444
+ * 選択肢の条件のパラメータ。if= は出すか、locked= は押せない状態で見せるか、call= は選んだら呼び出すか。
445
+ * 書いていなければ absent。式が誤りなら偽(condition)。
446
+ */
447
+ private optionFlag;
448
+ /** 選択肢の見た目の引数を値にする。 */
449
+ private look;
450
+ private command;
451
+ /** 場面の切れ目を過ぎた。それまでに待たせていた命令を、次の本文か選択肢の前に出すようにする。 */
452
+ private sceneBreak;
453
+ /** 場面の切れ目を過ぎた待たせている命令を、描画側へ渡して外す(本文と選択肢の前。その位置のセーブには入れない)。 */
454
+ private flushSceneWait;
455
+ /** CG として解放する印のあるパラメータで出した画像が CG なら解放する(folder= があればそのフォルダで見る)。 */
456
+ private unlockCg;
457
+ /**
458
+ * 命令が作品のデータから出した画像を CG として解放する(liminalia.json の extra.cg か extra.cgAuto の画像なら。@bg で出したときと同じ)。
459
+ * 解放したら true。データの形の宣言でその欄に CG の印(d.asset(…, { cg: true }))を付けておくと、どこからも出ない CG の検査が数える。
460
+ */
461
+ unlockCgImage(folder: string, image: string): boolean;
462
+ /** 再開する位置と、その時点の状態を控える(null で外す)。 */
463
+ private holdResume;
464
+ /**
465
+ * 引数を仕様の型に合わせた値にし、既定値を補う。at(書いたファイルと場面)を渡せば、訳す印(translate: "text")のある文字の引数を
466
+ * 遊んでいる言語の訳に替える(訳が無ければそのまま)。
467
+ */
468
+ private resolveArgs;
469
+ /** そのファイルと、そのファイルが @use したファイルの @define を探す。 */
470
+ private findDefine;
471
+ /** @jump と選択肢の移動。ほかのファイル(章)へ移ったら場面の切れ目にする(@call と @return は切れ目にしない)。 */
472
+ private moveTo;
473
+ private goto;
474
+ /**
475
+ * ファイルを読んで実行できる形にする(一度読んだものは持っておく)。quiet(先読み)なら、見つけた誤りはまだ知らせず、
476
+ * そのファイルを本当に使うときに知らせる(通らない分岐の先の誤りを、遊んでいる途中に出さないため)。
477
+ */
478
+ program(file: string, quiet?: boolean): Promise<Program>;
479
+ /** 読み込み中のファイル(先読みと重なったとき、同じ読み込みを待つ)。 */
480
+ private readonly loadingPrograms;
481
+ /** 読んだが、まだ知らせていない誤り(ファイル → 診断)。使ったときに知らせる。 */
482
+ private readonly pendingDiagnostics;
483
+ private readProgram;
484
+ /** まだ知らせていない、そのファイルと @use したファイルの誤りを知らせる。 */
485
+ private flushDiagnostics;
486
+ /** 先読みした飛び先(`ファイル#ラベル`)。同じところは二度読まない。 */
487
+ private readonly prefetched;
488
+ /**
489
+ * この先(collectPrefetch と同じ範囲)の @jump・@call・選択肢の飛び先を先読みする。別のファイルならそのファイルを読んでおき、
490
+ * 飛び先の頭から使う素材を描画側に渡す(同じファイルでも、見ている範囲の外のラベルなら素材を渡す)。式の飛び先は読まない。
491
+ * 一ページに読むのは新しい飛び先 MAX_TARGET_PREFETCH 個まで。読めなくても黙る(本当に飛んだときに知らせる)。
492
+ */
493
+ private prefetchTargets;
494
+ private unit;
495
+ private readonly env;
496
+ /** そのファイルと、そのファイルが @use したファイルの @function を探す。 */
497
+ private findFunction;
498
+ /** 式の lang() が返す、遊んでいる言語。描画側が入れる(言語を替えたら入れ直す)。 */
499
+ language: string;
500
+ /** 式の platform()・app() が返す、遊んでいる機種。描画側が入れる。 */
501
+ platform: Platform;
502
+ /** 再生しているおまけの回想の id(start の replay)。回想でなければ null。 */
503
+ replay: string | null;
504
+ /** 章の情報(options.chapters)。 */
505
+ readonly chapters: readonly ChapterInfo[];
506
+ /** 数を数える実績の目標(options.achievementGoals)。 */
507
+ readonly achievementGoals: Readonly<Record<string, number>>;
508
+ /**
509
+ * 今のシナリオファイル(実行中の命令のファイル。始める前は再開する位置のファイル)の章(liminalia.json の chapters)。無ければ null。
510
+ * 章の扉や章の終わりのプラグインのコマンドは、ここから番号と題を読む。
511
+ */
512
+ get chapter(): ChapterInfo | null;
513
+ private story;
514
+ /** visits・read の鍵(`ファイル#ラベル` か `ファイル`)。`#ラベル` は式を書いたファイルのラベル。 */
515
+ private progressKey;
516
+ /** 見たエンディングで進める実績(options.endingAchievements)。 */
517
+ readonly endingAchievements: Readonly<Record<string, {
518
+ endings: string;
519
+ goal: number;
520
+ }>>;
521
+ /** 使えるエンディングの種類(組み込みと options.endingKinds)。 */
522
+ readonly endingKinds: EndingKinds;
523
+ /**
524
+ * プレイを終える命令の ending= と title=(原文。訳す前)を、見た結末として全セーブ共通の ENDINGS_KEY に残す(鍵はシーンと種類と名前)。
525
+ * 見た数で進める実績の数を合わせ、変わったものを @achieve-progress の形で返す(描画側に知らせる)。回想の間は残さない。
526
+ */
527
+ private noteEnding;
528
+ /** ラベル(かファイルの頭)に入ったことを数える(このプレイの回数と、全セーブ共通の既読)。 */
529
+ private visited;
530
+ /** 選んだ選択肢の文(原文の飾りを外したもの)を覚える。 */
531
+ private noteChosen;
532
+ eval(expr: Expr): Value;
533
+ private assign;
534
+ private assigned;
535
+ private readonly changeListeners;
536
+ /**
537
+ * 変数が変わったときに呼ぶ(@set・@let・命令の結果の setVariable・持ち物・選んだ選択肢と入った場面の数、variablesChanged で知らせたもの)。
538
+ * path は game.x・system.x・temp.x(入れ子は game.a.b)か局所変数の名前、持ち物は game.@items、選んだ選択肢は chosen、入った場面は visits、
539
+ * まとめて消したら game・system・temp。図鑑の見回しのように、変数で決まるものを変わった時点で見直すのに使う。返す関数で外す。
540
+ */
541
+ onVariableChange(listener: (path: string) => void): () => void;
542
+ /** 変数を変えたことを知らせる(state.game などを直に書き換えたプラグインが呼ぶ。setVariable は自分で知らせる)。 */
543
+ variablesChanged(...paths: string[]): void;
544
+ private fail;
545
+ private diagnostic;
546
+ }
547
+ /** 遊んでいる機種(式の platform()・app())。device は pc か mobile、app はアプリ(デスクトップ版、スマホ版)なら true。 */
548
+ export interface Platform {
549
+ device: "pc" | "mobile";
550
+ app: boolean;
551
+ }
552
+ export type { PresentEvent };
553
+ export { CORE_COMMANDS };
@@ -0,0 +1,21 @@
1
+ import type { SaveData } from "./state.js";
2
+ /**
3
+ * セーブデータの版。セーブの形(SaveData や舞台の状態)を、古いセーブがそのまま読めない形に変えたら一つ上げ、
4
+ * MIGRATIONS の末尾に「一つ前の版 → この版」の変換を足す。変換は消さない(どれだけ古いセーブも順にたどって今の版にする)。
5
+ * 項目を足すだけで、無ければ既定で補える変更(読み込み時に補う)は版を上げない。
6
+ */
7
+ export declare const SAVE_VERSION = 1;
8
+ type Raw = Record<string, unknown>;
9
+ /** 読めないセーブの理由。newer: この版のゲームより新しいゲームで作られた。broken: セーブの形をしていない・変換の途中で壊れた。 */
10
+ export type SaveProblem = "newer" | "broken";
11
+ export declare class SaveVersionError extends Error {
12
+ readonly problem: SaveProblem;
13
+ constructor(problem: SaveProblem, message: string);
14
+ }
15
+ /** セーブを今の版にする。読めなければ SaveVersionError。元の値は変えない。 */
16
+ export declare function migrateSave(raw: unknown): SaveData;
17
+ /** 読めないセーブなら理由、読めるなら null(ロードの前に知らせるため)。 */
18
+ export declare function saveProblem(raw: unknown): SaveProblem | null;
19
+ /** 変換の連なりをたどる(テストのため変換と今の版を渡せる)。 */
20
+ export declare function migrateWith(raw: unknown, migrations: readonly ((save: Raw) => Raw)[], current: number): Raw;
21
+ export {};
@@ -0,0 +1,43 @@
1
+ import { type Diagnostic, type ScenarioTest } from "@liminalia/lang";
2
+ import { type TraceEntry } from "./headless.js";
3
+ import { type RunResult, type RuntimeOptions } from "./runtime.js";
4
+ import { type Value } from "./value.js";
5
+ /**
6
+ * 台本の自動テスト(@liminalia/lang の ScenarioTest)を画面なしで流し、期待(expect)を確かめる。ブラウザでも Node でも動く(lim test)。
7
+ * 実行時のエラーは、expect no-errors を書かなくても失敗にする。
8
+ */
9
+ export interface ScenarioTestOptions {
10
+ loadSource(file: string): Promise<string>;
11
+ /** 実行器の設定(話者・作品の命令・変数の初期値など)。onStep はテストが使うので渡さない。 */
12
+ runtime?: Omit<RuntimeOptions, "onStep" | "seed">;
13
+ /** from を書かないテストの開始位置(liminalia.json の entry)。 */
14
+ entry: string;
15
+ /** from-state のファイルを読む(パスはテストのファイルに書いたまま)。読めなければ例外。 */
16
+ readState?(path: string): unknown;
17
+ }
18
+ /** 失敗一つ。line はテストのファイルの行。diagnostic は実行時の診断から来たもの(英語にするため)。 */
19
+ export interface TestFailure {
20
+ line: number;
21
+ ja: string;
22
+ en: string;
23
+ diagnostic?: Diagnostic;
24
+ }
25
+ export interface ScenarioTestResult {
26
+ name: string;
27
+ line: number;
28
+ ok: boolean;
29
+ failures: TestFailure[];
30
+ result: RunResult;
31
+ /** 出したページの数と、選んだ選択肢(文の並びと選んだ番号。0 始まり)。 */
32
+ pages: number;
33
+ choices: {
34
+ options: string[];
35
+ selected: number | null;
36
+ }[];
37
+ /** 終わったときのゲームの変数。 */
38
+ game: Record<string, Value>;
39
+ }
40
+ /** テストの既定のページ数の上限(これに達したら、終わらないテストとして失敗にする)。 */
41
+ export declare const DEFAULT_TEST_LIMIT = 5000;
42
+ export declare function runScenarioTest(test: ScenarioTest, o: ScenarioTestOptions): Promise<ScenarioTestResult>;
43
+ export type { TraceEntry };