@liminalia/sdk 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.
@@ -0,0 +1,166 @@
1
+ import { type CommandSpec, type Diagnostic, type ParamType } from "@liminalia/lang";
2
+ import type { Args, CommandContext, CommandImpl, Value } from "@liminalia/runtime";
3
+ /**
4
+ * プラグインの命令の定義。この一つの表から
5
+ * - 命令の仕様(検査・補完・リファレンス)
6
+ * - 実行時の処理(状態の更新と描画側への通知)
7
+ * を作る。見た目はプラグインの描画側(WebPlugin の renderers)が担う。
8
+ * TyranoScript の .ks のタグからの変換は書き出すゲームに入れないので、ここには書かず、
9
+ * プラグインの "./import"(@liminalia/ks-import の TyranoImportProfile の mappings)に書く。
10
+ */
11
+ export interface ParamDefinition {
12
+ type: ParamType;
13
+ /**
14
+ * 既定値(.lim の書き方)。取り込み元の .ks のタグがあるなら、そのタグで省略したときの値と同じにしておく
15
+ * (取り込みは「.ks に書かれていた値のうち、既定値と違うもの」を書き出す)。
16
+ */
17
+ default?: string;
18
+ required?: boolean;
19
+ doc: string;
20
+ /** 英語の説明(任意。無ければ英語の表示でも doc を出す)。 */
21
+ docEn?: string;
22
+ }
23
+ export interface CommandDefinition {
24
+ /** .lim の命令名。 */
25
+ name: string;
26
+ summary: string;
27
+ /** 英語の要約(任意。無ければ英語の表示でも summary を出す)。Studio と VS Code の英語表示、lim reference --lang en が読む。 */
28
+ summaryEn?: string;
29
+ positional?: string[];
30
+ /** 位置引数を埋めたあとの名前なしの値一つを受ける引数(名前を付けても書ける。対象を取らない命令の時間など)。 */
31
+ bare?: string;
32
+ params: Record<string, ParamDefinition>;
33
+ example: string;
34
+ /**
35
+ * 英語の例(任意。無ければ英語の表示でも example を出す)。例に人物の名前や見せる文字があるときに、それを英語にして書く。
36
+ * Studio と VS Code の英語表示、lim reference --lang en が読む。
37
+ */
38
+ exampleEn?: string;
39
+ /**
40
+ * 引数に wait がないときに、演出の終わりを待つか。引数 wait を持つ命令は、省略するとその既定値になる。
41
+ * run で処理を差し替える命令も、ctx.present に渡す待ちと合わせて書く(制作画面の演出の流れとリファレンスが読む)。
42
+ */
43
+ waits?: boolean;
44
+ /**
45
+ * この命令でプレイが終わる(タイトルへ戻る・ゲームを終えるなど。あとの行へは進まない)。制作画面の地図は、
46
+ * この命令で終わる場面を「終わり」にして、次の場面へ矢印を引かない(バッドエンドの場面などが別の枝として出る)。
47
+ */
48
+ ends?: boolean;
49
+ /**
50
+ * 組み込みの命令か、先に読んだプラグイン(標準の命令 @liminalia/std など)の同じ名前の命令を、わざと置き換えるときに true。
51
+ * 書かずに同じ名前の命令を作ると、lim check と制作画面のチェックが警告する(plugin-replaces-command。標準の命令が増えて名前がぶつかったときに気づくため)。
52
+ */
53
+ replaces?: boolean;
54
+ /** 制作画面のパーツの欄の区切り(screen・sprite・sound・motion・flow・system)。省くと「カスタムコマンド」に並ぶ。 */
55
+ category?: string;
56
+ /** やりたいことの言葉(「揺らす」「暗転」など)。パーツの欄で探すときと、AI が命令を選ぶときに使う。 */
57
+ keywords?: string[];
58
+ /** やりたいことの言葉の英語(任意。Studio の英語表示でパーツを探すとき)。 */
59
+ keywordsEn?: string[];
60
+ /**
61
+ * セーブに残す状態の更新(stage.extra を書き換える)。
62
+ * ロードしたとき描画側は stage.extra から画面を組み立て直す。
63
+ */
64
+ apply?(args: Args, extra: Record<string, Value>): void;
65
+ /** 実行時の処理を丸ごと差し替える(結果を変数に入れる・飛ぶなど)。 */
66
+ run?(args: Args, ctx: CommandContext): Promise<void>;
67
+ /**
68
+ * 自動確認(lim playtest・lim shot・全ルートテスト)での進め方。人が操作せずに流すとき、ctx.present は描画側(renderers)に描かせずに
69
+ * これを呼び、返した値を描画側の答えの代わりにする(args は ctx.present に渡したもの)。遊ぶ人の操作を待つ画面(行き先を選ぶ地図、
70
+ * 調べる画面、ミニゲーム)や、飛ばしたい長い演出の命令に書く。
71
+ * 何も返さなければ答えなし。ctx.pick・ctx.choose で行き先を選ぶ命令は、ふつうの選択肢と同じく自動確認が選ぶ(lim playtest は
72
+ * 実行ごとに選び方を変え、--choose でも選べる)ので、`autoplay: () => undefined` だけでよい。ミニゲームの結果のように答えが要るなら、それを返す。
73
+ */
74
+ autoplay?(args: Args, ctx: CommandContext): Value | void | Promise<Value | void>;
75
+ /**
76
+ * この命令が飛ぶかもしれない先(`#ラベル`・`ファイル`・`ファイル#ラベル`)。台本だけではわからない飛び先(作品のデータで
77
+ * 決まる選択など)を、制作画面の地図が矢印にするのに使う(実行には使わない)。args は台本に書いた値(書いたままの文字列。
78
+ * 位置引数も名前で引ける)、data は作品のデータ(paths.data の .json。無ければ undefined)を読む。
79
+ * leaves を true にすると、この命令のあとの行へは進まない(かならずどれかへ飛ぶ)とみなす。
80
+ */
81
+ targets?(args: Readonly<Record<string, string>>, data: (name: string) => unknown): {
82
+ targets: string[];
83
+ leaves?: boolean;
84
+ };
85
+ /**
86
+ * この命令の一行ごとの検査(lim check・lim build・制作画面のチェックが、台本のこの命令の行ごとに呼ぶ)。引数の型・必須・素材の実在など、
87
+ * 仕様(params)で決まることはエンジンが確かめるので、ここには引数どうしの組み合わせや作品のデータとの突き合わせを書く。
88
+ * args は台本に書いた値(書いたままの文字列。位置引数も名前で引ける。式で書いた引数は入らない)。返した診断の file・line を省くと、この行になる。
89
+ * 同期の関数で書く。投げてもチェックは止まらず、そのプラグインの診断になる。
90
+ */
91
+ validate?(args: Readonly<Record<string, string>>, ctx: CommandValidateContext): readonly CommandDiagnostic[] | void;
92
+ }
93
+ /** 命令の一行ごとの検査(CommandDefinition.validate)に渡すもの。 */
94
+ export interface CommandValidateContext {
95
+ /** 台本のファイル(拡張子なし)と行。 */
96
+ file: string;
97
+ line: number;
98
+ /** 作品のデータ(paths.data の .json。無ければ undefined)。 */
99
+ data(name: string): unknown;
100
+ /** 素材のフォルダ(image・bgimage など)の中にあるか。 */
101
+ assetExists(folder: string, path: string): boolean;
102
+ /** キャストにある名前か。 */
103
+ isCast(name: string): boolean;
104
+ /** 飛び先(`#ラベル`・`ファイル`・`ファイル#ラベル`)があるか(`#ラベル` はこの行のファイル)。 */
105
+ targetExists(target: string): boolean;
106
+ }
107
+ /** 命令の一行ごとの検査が返す診断(file・line を省くとその行。code・message・severity は必ず書く)。 */
108
+ export type CommandDiagnostic = Pick<Diagnostic, "severity" | "code" | "message"> & Partial<Pick<Diagnostic, "messageEn" | "file" | "line" | "column" | "hint" | "hintEn" | "fix" | "fixes">>;
109
+ export declare function toSpec(c: CommandDefinition): CommandSpec;
110
+ export declare function toImplementation(c: CommandDefinition): CommandImpl;
111
+ export declare const t: {
112
+ /** suggest は入力の候補(制作画面で一覧から選べる。ほかの値も書ける)。 */
113
+ string: (doc: string, def?: string, suggest?: readonly string[]) => ParamDefinition;
114
+ /**
115
+ * プレイヤーに見せる文(章題・テロップ・ダイアログの文など)。多言語の作品では、台本に字面で書いた値が訳のファイル(lim i18n)に
116
+ * 「コマンドの文字」として並び、実行するときに遊んでいる言語の訳に替わる(訳が空なら原文のまま)。
117
+ */
118
+ text: (doc: string, def?: string) => ParamDefinition;
119
+ /** 人の名前(話者や相手の名前)。多言語の作品では、訳のファイルの speakers に並ぶ(訳して見せるのは命令の実装。ctx.runtime.translator?.speaker)。 */
120
+ name: (doc: string, def?: string) => ParamDefinition;
121
+ /** 数。range の min・max を書くと、その外の値を lim check が知らせ、制作画面の欄もその幅にする。 */
122
+ number: (doc: string, def?: string, range?: {
123
+ min?: number;
124
+ max?: number;
125
+ }) => ParamDefinition;
126
+ /** 整数。range は number と同じ。 */
127
+ int: (doc: string, def?: string, range?: {
128
+ min?: number;
129
+ max?: number;
130
+ }) => ParamDefinition;
131
+ bool: (doc: string, def: boolean) => ParamDefinition;
132
+ duration: (doc: string, def?: string) => ParamDefinition;
133
+ color: (doc: string, def?: string) => ParamDefinition;
134
+ enum: (values: string[], doc: string, def?: string) => ParamDefinition;
135
+ /**
136
+ * 素材のパス。cg を付けると、この素材を出したときに CG として解放する(liminalia.json の extra.cg か extra.cgAuto のフォルダにある画像なら。
137
+ * @bg と同じく、台本に @cg-unlock を書かなくてよい。章末の扉絵など、作品の命令で一枚絵を出すときに使う)。
138
+ */
139
+ asset: (folder: string, doc: string, o?: {
140
+ cg?: boolean;
141
+ }) => ParamDefinition;
142
+ required: (p: ParamDefinition) => ParamDefinition;
143
+ /** 値を入れる変数(`game.x`・`system.x`・`temp.x`)。命令の結果を受け取るときに。lim check が書き方を確かめ、値を入れる変数として数える。 */
144
+ variable: (doc: string, def?: string) => ParamDefinition;
145
+ /** 飛び先(`#ラベル`・`ファイル`・`ファイル#ラベル`)。lim check がラベルとファイルの実在を確かめ、制作画面が候補を出し、地図が矢印を引く。 */
146
+ target: (doc: string, def?: string) => ParamDefinition;
147
+ /**
148
+ * キャストの名前。lim check がキャストにあるかを確かめ、制作画面が一覧から選ばせる。shown を付けると、表示中の立ち絵の人物に効く引数
149
+ * (消す、動かす、揺らす、漫符を付けるなど)として、制作画面の補完がその行で表示中の人物を上に並べる(ほかの人物も候補に残す。検査と実行は変わらない)。
150
+ */
151
+ cast: (doc: string, def?: string, o?: {
152
+ shown?: boolean;
153
+ }) => ParamDefinition;
154
+ /** 条件。必ず式(`(…)`)で書き、実行するときに評価した真偽が渡る(@if と同じ)。 */
155
+ condition: (doc: string, def?: string) => ParamDefinition;
156
+ /**
157
+ * 作品のデータの中の名前(file は paths.data の .json、path はその中の辞書か並びへの道。`places`・`maps/town/spots` のように / で区切る)。
158
+ * 辞書なら鍵、並びなら項目の id を名前とみなし、lim check が実在を確かめ、制作画面が候補を出す。
159
+ */
160
+ dataKey: (file: string, path: string, doc: string, def?: string) => ParamDefinition;
161
+ /**
162
+ * 演出をクリックで終わりまで飛ばせるか(skip。既定 true)。時間のかかる演出を出す命令に付ける。
163
+ * 描画側は何もしなくてよい(Element.animate の動きと ctx.delay の待ちは早送りで終わる。自分で動かす演出は ctx.onFastForward)。
164
+ */
165
+ skip: () => ParamDefinition;
166
+ };
@@ -0,0 +1,92 @@
1
+ import { type DataDeclaration, type DataField, type DataText, type DeclaredData, type Diagnostic } from "@liminalia/lang";
2
+ import type { CommandPlugin, PluginCheckProject } from "./plugin.js";
3
+ /**
4
+ * データの形の宣言を短く書く部品。プラグインの data に並べる。
5
+ * ```ts
6
+ * data: [{ file: "stamps.json", title: "スタンプ帳", root: d.map(d.record({ image: d.asset("image", "画像", { cg: true }), memo: d.text("メモ") })) }]
7
+ * ```
8
+ */
9
+ type Label = {
10
+ label?: string;
11
+ labelEn?: string;
12
+ doc?: string;
13
+ docEn?: string;
14
+ required?: boolean;
15
+ };
16
+ export declare const d: {
17
+ /** 一行の文字。suggest は候補。translate なら遊ぶ人に見せる文で、lim i18n が訳のファイルに並べる(描画は dataText で訳を引く)。 */
18
+ string: (label?: string | Label, o?: {
19
+ suggest?: readonly string[];
20
+ translate?: boolean;
21
+ }) => DataField;
22
+ /** 複数行の文字(本文・説明)。translate は string と同じ。 */
23
+ text: (label?: string | Label, o?: {
24
+ translate?: boolean;
25
+ }) => DataField;
26
+ number: (label?: string | Label, o?: {
27
+ min?: number;
28
+ max?: number;
29
+ }) => DataField;
30
+ int: (label?: string | Label, o?: {
31
+ min?: number;
32
+ max?: number;
33
+ }) => DataField;
34
+ bool: (label?: string | Label) => DataField;
35
+ enum: (values: readonly string[], label?: string | Label) => DataField;
36
+ /**
37
+ * 素材。cg なら、プラグインがこの画像を CG として解放する(どこからも出ない CG の検査がこれを数える)。
38
+ * also は folder に無ければ探すほかのフォルダ(置き場所を替えた欄で、前の場所に置いた素材も読めるように。描画の側も同じ順に探す)。
39
+ */
40
+ asset: (folder: string, label?: string | Label, o?: {
41
+ cg?: boolean;
42
+ also?: readonly string[];
43
+ }) => DataField;
44
+ /** フラグ。use は、このデータでプラグインが立てる(set)か読む(read)か。 */
45
+ flag: (use: "set" | "read", label?: string | Label) => DataField;
46
+ /** 条件の式。 */
47
+ expr: (label?: string | Label) => DataField;
48
+ cast: (label?: string | Label) => DataField;
49
+ /** 飛び先。base は `#ラベル` のファイルを決める、外側の記録の欄の名前。 */
50
+ scene: (label?: string | Label, o?: {
51
+ base?: string;
52
+ bare?: boolean;
53
+ }) => DataField;
54
+ file: (label?: string | Label) => DataField;
55
+ /** 同じデータの中の名前(to は一覧の欄への道。`/entries`)。 */
56
+ ref: (to: string, label?: string | Label) => DataField;
57
+ /** 背景の上の矩形。image は背景の素材の欄の名前。 */
58
+ rect: (label?: string | Label, o?: {
59
+ image?: string;
60
+ }) => DataField;
61
+ /**
62
+ * 絵の上の点({ x, y }。既定は絵の左上からの割合 0〜100、unit が px なら舞台の px)。image は背景の素材の欄の名前(`ref の欄>素材の欄` なら ref が指す項目の欄)。
63
+ * keys を書くと、同じ記録の二つの欄(`["x", "y"]`)に置く(制作画面は絵を出して、押した所と引きずった所に点を置く)。
64
+ */
65
+ point: (label?: string | Label, o?: {
66
+ image?: string;
67
+ unit?: "percent" | "px";
68
+ keys?: readonly [string, string];
69
+ }) => DataField;
70
+ list: (of: DataField, label?: string | Label, o?: {
71
+ sortable?: boolean;
72
+ key?: string;
73
+ }) => DataField;
74
+ record: (fields: Record<string, DataField>, label?: string | Label, o?: {
75
+ title?: string;
76
+ }) => DataField;
77
+ map: (of: DataField, label?: string | Label) => DataField;
78
+ json: (label?: string | Label) => DataField;
79
+ /** 必須にする。 */
80
+ required: (f: DataField) => DataField;
81
+ };
82
+ /** プラグインのデータの宣言(同じファイルは後のプラグインが勝つ)。 */
83
+ export declare function dataDeclarations(plugins: readonly CommandPlugin[]): DataDeclaration[];
84
+ /** 宣言のあるデータのうち、作品にあるもの。 */
85
+ export declare function declaredData(plugins: readonly CommandPlugin[], read: (name: string) => unknown, text?: (name: string) => string | undefined): DeclaredData[];
86
+ /** 作品のデータの訳す文(宣言で translate の印の付いた欄。lim i18n と制作画面の訳の画面が updateTranslation の data に渡す)。 */
87
+ export declare function projectDataTexts(plugins: readonly CommandPlugin[], read: (name: string) => unknown): DataText[];
88
+ /** プラグインが作品のデータから CG として解放する画像(`フォルダ/パス`)。checkExtra に渡す。 */
89
+ export declare function pluginDataCg(plugins: readonly CommandPlugin[], read: (name: string) => unknown): Set<string>;
90
+ /** データの形の検査とフラグの突き合わせ(runPluginChecks が呼ぶ)。 */
91
+ export declare function checkDeclaredData(plugins: readonly CommandPlugin[], project: PluginCheckProject): Diagnostic[];
92
+ export {};
@@ -0,0 +1,7 @@
1
+ export { t, toImplementation, toSpec, type CommandDefinition, type CommandDiagnostic, type CommandValidateContext, type ParamDefinition } from "./command.js";
2
+ export { checkDeclaredData, d, dataDeclarations, declaredData, pluginDataCg, projectDataTexts } from "./data.js";
3
+ export { apiSatisfies, checkPluginManifest, combinePlugins, commandArgs, dataKeys, defineCommandPlugin, engineMismatches, PLUGIN_API_VERSION, pluginWrittenVariables, runPluginChecks, undeclaredOverrides, type CommandPlugin, type PluginCheckProject, type PluginDiagnostic, type PluginFunction } from "./plugin.js";
4
+ export { defineState, type PluginState } from "./state.js";
5
+ export { packTranslationScope, parsePacks, pluginTargetHooks, projectDiagnostics, type PackCheckSource, type ParsedPack, type ProjectCheckConfig, type ProjectCheckInput } from "./project-check.js";
6
+ export { RULE_PARAMS, RULE_PATTERNS } from "@liminalia/lang";
7
+ export { withEnglish, type CommandEnglish } from "@liminalia/lang";
@@ -0,0 +1,134 @@
1
+ import { PLUGIN_API_VERSION, type Argument, type Cast, type CommandSpec, type DataDeclaration, type Diagnostic, type Registry, type Script } from "@liminalia/lang";
2
+ import { type Value } from "@liminalia/runtime";
3
+ import { type CommandDefinition } from "./command.js";
4
+ export { PLUGIN_API_VERSION };
5
+ /**
6
+ * プラグインが足す式の関数(CommandPlugin.functions)。台本の式(@if・@set・{…}・条件の式)から `名前(引数…)` で呼べる。
7
+ * 引数は評価した値の写し(書き換えても台本の変数は変わらない)、返すのは値(数・文字・真偽・null・配列・オブジェクト)。
8
+ * 乱数は env.random()(作品の乱数のシードに従うので、ロードしても同じ値になる)。同期の関数で、状態を持たない(同じ引数なら同じ値)ように書く。
9
+ */
10
+ export interface PluginFunction {
11
+ /** 引数の数(数一つならちょうどその数、[最小, 最大]。最大は Infinity も書ける)。lim check と実行器が確かめる。 */
12
+ args: number | readonly [min: number, max: number];
13
+ /** 説明(lim reference の式の関数の表に出す)。 */
14
+ doc: string;
15
+ docEn?: string;
16
+ /** 書き方の例(`rank(game.score)` など。無ければ `名前()`)。 */
17
+ usage?: readonly string[];
18
+ run(args: Value[], env: {
19
+ random(): number;
20
+ }): Value;
21
+ }
22
+ /**
23
+ * プラグインの命令側(Node でも読める部分)。プロジェクト設定の plugins に書いたパッケージの
24
+ * "./commands" がこれを default export する。検査・画面なしの実行・書き出し・プレイヤーが読む。
25
+ * 見た目(描画・システム画面)は同じパッケージの "./web" が担う(@liminalia/web の WebPlugin)。
26
+ * TyranoScript の .ks からの取り込み(タグの変換表・[iscript] の置き換え・扱わないタグ)は "./import" が担う
27
+ * (@liminalia/ks-import の TyranoImportProfile)。書き出すゲームには入らない。
28
+ */
29
+ export interface CommandPlugin {
30
+ name: string;
31
+ commands: readonly CommandDefinition[];
32
+ /**
33
+ * 作品全体を読んで診断を返す(lim check・lim build・制作画面のチェックが呼ぶ。保存のたびにも呼ぶので重い処理は避ける。同期の関数で書く)。
34
+ * 分類は「プラグイン」に入る。投げても全体のチェックは止まらず、そのプラグインの診断として出る。
35
+ */
36
+ check?(project: PluginCheckProject): readonly PluginDiagnostic[];
37
+ /**
38
+ * 作品のデータ(paths.data の .json)の形の宣言(@liminalia/sdk の d で書く)。この宣言から、lim check と制作画面のチェックが形・素材・
39
+ * キャスト・飛び先・式を確かめ、データの中のフラグと台本の @set を突き合わせ、制作画面が自動のフォームを作り、シーン・ファイル・素材・
40
+ * 変数・キャストの名前を変えたらデータも書き換える。CG の印(d.asset(…, { cg: true }))の素材は、どこからも出ない CG の検査が出ているものと数える。
41
+ */
42
+ data?: readonly DataDeclaration[];
43
+ /**
44
+ * このプラグインの命令が値を入れる変数("game.x"。末尾を .* にすると、その下の名前すべて。"game.codex.*" など)。
45
+ * lim check と制作画面のチェックは、どこでも値を入れずに読むだけの変数を綴り違いとして知らせるので、プラグインが ctx.runtime.setVariable などで
46
+ * 値を入れる変数はここに書く。
47
+ */
48
+ variables?: readonly string[];
49
+ /**
50
+ * 式の関数(名前 → 定義)。台本の式から呼べる(lim check の unknown-function にならない)。組み込みの関数と同じ名前は使えない
51
+ * (lim check が plugin-function-clash を出し、組み込みのほうを使う)。
52
+ */
53
+ functions?: Readonly<Record<string, PluginFunction>>;
54
+ /**
55
+ * このプラグインを書いたときのプラグインの口の版(PLUGIN_API_VERSION)。エンジンの版より新しければ、lim check と制作画面のチェックが
56
+ * 「新しいエンジンが要る」と知らせる(plugin-api-version)。書かなければ確かめない。
57
+ */
58
+ apiVersion?: number;
59
+ }
60
+ /** プラグインが値を入れる変数(宣言 variables)と、作品のデータが立てるフラグ。変数の綴り違いの検査に渡す。 */
61
+ export declare function pluginWrittenVariables(plugins: readonly CommandPlugin[], read: (name: string) => unknown): string[];
62
+ /** プラグインの check が読む作品。 */
63
+ export interface PluginCheckProject {
64
+ /** 作品のフォルダ。 */
65
+ root: string;
66
+ /** liminalia.json の中身。 */
67
+ config: Readonly<Record<string, unknown>>;
68
+ /** ファイル(拡張子なし)→ 構文木。 */
69
+ scripts: ReadonlyMap<string, Script>;
70
+ /** 台本の文字(拡張子なし)。 */
71
+ text(file: string): string;
72
+ cast: Readonly<Cast>;
73
+ speakers: readonly string[];
74
+ /** 命令の仕様(組み込み・標準・プラグイン)。 */
75
+ registry: Registry;
76
+ /** 作品のデータ(paths.data の .json。無ければ undefined)。 */
77
+ data(name: string): unknown;
78
+ /** 素材のフォルダ(image・bgimage など)の中にあるか。 */
79
+ assetExists(folder: string, path: string): boolean;
80
+ /** 作品のデータの文字(診断の行を求めるのに使う。無ければ 1 行目に出す)。 */
81
+ dataText?(name: string): string | undefined;
82
+ /** 診断に書くデータのフォルダの名前(作品のフォルダからのパス。既定 data)。 */
83
+ dataFolder?: string;
84
+ }
85
+ /**
86
+ * プラグインの check が返す診断。file を省くと liminalia.json、line を省くと 1。訳があれば messageEn・hintEn に書く(無ければ英語の表示でも原文のまま)。
87
+ * fix・fixes に直し方(行の置き換え・行の削除・話者に足す・シーンを作る)を書くと、制作画面のチェックとエディタに「修正」が出る。
88
+ */
89
+ export type PluginDiagnostic = Pick<Diagnostic, "severity" | "code" | "message"> & Partial<Pick<Diagnostic, "messageEn" | "file" | "line" | "column" | "hint" | "hintEn" | "fix" | "fixes">>;
90
+ /**
91
+ * 命令の行の、書いたままの文字の引数(位置引数も名前で引ける。式で書いた引数は入らない)。
92
+ * spec を渡すと、検査と実行器と同じ読み方(normalizeBooleanArgs)にする(名前なしの値を bare の引数に、真偽値の省略形をその名前に当てる)。
93
+ */
94
+ export declare function commandArgs(args: readonly Argument[], positional: readonly string[], spec?: CommandSpec): Record<string, string>;
95
+ /** 作品のデータの path(/ で区切る)の下の名前(辞書なら鍵、並びなら項目の id)。道が無ければ null。 */
96
+ export declare function dataKeys(data: unknown, path: string): string[] | null;
97
+ /**
98
+ * 合うエンジンの宣言(liminalia.api: 要る口の版、engines.liminalia: 合う口の版の範囲)のうち、このエンジンの口の版(PLUGIN_API_VERSION)に
99
+ * 合わないもの("3"、">=3" など、書いたままの形)。合えば、宣言が無ければ、読めなければ空。
100
+ * プラグインの package.json、テーマの theme.json、作品とひな形の liminalia.json で同じ形を読む。
101
+ */
102
+ export declare function engineMismatches(manifest: unknown, version?: number): string[];
103
+ /**
104
+ * プラグインの package.json の宣言(liminalia.api: 要るプラグインの口の版、engines.liminalia: 合うプラグインの口の版の範囲)を、このエンジンと比べる。
105
+ * spec は liminalia.json の plugins に書いた形(診断に出す)。合わなければ警告(plugin-engine-version)。
106
+ */
107
+ export declare function checkPluginManifest(spec: string, manifest: unknown): Diagnostic[];
108
+ /**
109
+ * プラグインの口の版 version が範囲 range に入るか。`2`、`>=2`、`>2`、`<=3`、`<3`、`^2`(2 以上 3 未満)、`2 - 4`、`*`、
110
+ * 空白区切り(すべて満たす)と `||`(どれか)を読む。読めない範囲は入るとみなす(知らない書き方で止めない)。
111
+ */
112
+ export declare function apiSatisfies(version: number, range: string): boolean;
113
+ /**
114
+ * 組み込みの命令か、先に読んだプラグインの同じ名前の命令を、宣言(replaces: true)なしに上書きしている命令。後に読んだプラグインの命令が使われる
115
+ * (combinePlugins と実行器)。over は上書きされた側(組み込みならエンジン、そうでなければそのプラグインの名前)。
116
+ */
117
+ export declare function undeclaredOverrides(plugins: readonly CommandPlugin[], builtIn?: Iterable<string>): {
118
+ plugin: string;
119
+ name: string;
120
+ over: string | null;
121
+ }[];
122
+ /** プラグインの check を順に呼ぶ。投げたもの・形の合わないものは、チェック全体を止めずにそのプラグインの診断にする。 */
123
+ export declare function runPluginChecks(plugins: readonly CommandPlugin[], project: PluginCheckProject): Diagnostic[];
124
+ export declare function defineCommandPlugin(plugin: CommandPlugin): CommandPlugin;
125
+ /**
126
+ * 複数のプラグインの命令をまとめて、仕様と実装にする。プラグインの式の関数(functions)も、検査(@liminalia/lang)と実行器(@liminalia/runtime)に
127
+ * 入れる(前に入れたものと入れ替える。組み込みと同じ名前のものは入れない)。
128
+ */
129
+ export declare function combinePlugins(plugins: readonly CommandPlugin[]): {
130
+ commands: CommandDefinition[];
131
+ specs: CommandSpec[];
132
+ implementations: import("@liminalia/runtime").CommandImpl[];
133
+ functions: Record<string, PluginFunction>;
134
+ };
@@ -0,0 +1,162 @@
1
+ import { type Diagnostic, type JsonSchema, type PluginScreens, type ProjectFiles, type ScreenTemplateRules, type ProjectFileCheckCache, type Registry, type Script, type TargetHook } from "@liminalia/lang";
2
+ import { type CommandPlugin } from "./plugin.js";
3
+ /**
4
+ * パック(packs/<フォルダ>/)の台本と訳の中身(@liminalia/project の listPackSources が読むもの)。
5
+ * dir は作品のフォルダからのパス、speakers はパックの cast.json の話者、scripts は台本の名前 → 中身、translations は言語 → 訳のファイルの中身。
6
+ */
7
+ export interface PackCheckSource {
8
+ dir: string;
9
+ /** 遊ぶ側の並び(pack.json の order、id)。渡す並びもこの順にする(listPackSources の順)。 */
10
+ id?: string;
11
+ order?: number;
12
+ speakers: readonly string[];
13
+ scripts: ReadonlyMap<string, string>;
14
+ translations: ReadonlyMap<string, string>;
15
+ }
16
+ /** 読み解いたパック(台本は、本体の話者にパックの cast.json の話者を足して読む。遊ぶ側はパックの cast.json で本体のものを差し替える)。 */
17
+ export interface ParsedPack {
18
+ dir: string;
19
+ scripts: Map<string, Script>;
20
+ translations: ReadonlyMap<string, string>;
21
+ }
22
+ /**
23
+ * その言語の訳のファイル(owner が無ければ本体の lang、あればそのパックの lang)と一緒に遊ばれるパックの台本。遊ぶ側は、入っているパックのうち
24
+ * 並びの最後でその言語の訳を持つもの(無ければ本体)の訳を、すべての台本に使う。遊ぶ人はパックのどの組み合わせでも入れうるので、
25
+ * その訳が使われる組み合わせ(owner を入れ、owner より後ろで訳を持つパックを入れない組)のどれかで出る台本を shown にする
26
+ * (組み合わせを並べずに、台本の持ち主と owner だけを入れた組で決める。パックの数によらずすべての組み合わせと同じ結果)。
27
+ * - shown: この訳で出るパックの台本(訳し漏れにも数える)。本体の訳なら、その言語の訳を持たないパック。パックの訳なら、訳を持たないパックと、
28
+ * 並びがそのパックより前で訳を持つパック。どちらも、並びがそのパックより前のパックの台本は、そのパックが同じ名前の台本で差し替えるものを除く
29
+ * - used: この訳では出ないが、使われているに数えるパックの台本(どの組み合わせで入っても訳を消さないよう、広めに数える)
30
+ */
31
+ export declare function packTranslationScope(packs: readonly ParsedPack[], language: string, owner?: ParsedPack): {
32
+ alsoShown: Map<string, Script>[];
33
+ alsoUsedBy: Map<string, Script>[];
34
+ };
35
+ /** パックの台本を読み解く(検査、lim voice-lock と制作画面の「番号を固定」、lim i18n が同じ読み方をする)。 */
36
+ export declare function parsePacks(packs: readonly PackCheckSource[], speakers: readonly string[]): ParsedPack[];
37
+ /**
38
+ * 作品全体の検査(lim check、制作画面のチェック、VS Code の拡張、MCP の check_text が同じ入力から同じ一覧を作る)。
39
+ * ファイルは読まない。読んだもの(台本、設定の字面、訳のファイル、素材の有無など)と読む口を呼ぶ側が渡す。
40
+ * checkProject などに渡す入力(台本の外から指すジャンプ先、commandDefaults で使うマクロ、変数、プラグインが値を入れる変数)も、
41
+ * 訳の検査と書式の版の検査も、ここで一度だけ組み立てる。呼ぶ側で足したり省いたりすると、同じ作品に違う結果が出る。
42
+ */
43
+ /** 検査に使う liminalia.json の項目(読み解いたもの。@liminalia/project の ProjectConfig をそのまま渡せる)。 */
44
+ export interface ProjectCheckConfig {
45
+ entry?: unknown;
46
+ afterLoad?: unknown;
47
+ extra?: unknown;
48
+ variables?: unknown;
49
+ commandDefaults?: unknown;
50
+ chapters?: unknown;
51
+ ui?: unknown;
52
+ items?: unknown;
53
+ scenes?: unknown;
54
+ languages?: unknown;
55
+ allowScript?: unknown;
56
+ format?: unknown;
57
+ title?: unknown;
58
+ endingKinds?: unknown;
59
+ autoLayout?: unknown;
60
+ playtest?: unknown;
61
+ /** プロジェクトのプラグイン(cast.json の model を描くものがあるかの見分けに使う)。 */
62
+ plugins?: unknown;
63
+ check?: {
64
+ punctuation?: unknown;
65
+ severity?: unknown;
66
+ variables?: unknown;
67
+ rules?: unknown;
68
+ sound?: unknown;
69
+ unusedSpeakers?: unknown;
70
+ } | undefined;
71
+ }
72
+ export interface ProjectCheckInput {
73
+ /** 作品のフォルダ(プラグインの check に渡す)。 */
74
+ root: string;
75
+ /** 台本(ファイル名 → 構文木と字面。名前の順)。 */
76
+ files: ReadonlyMap<string, {
77
+ script: Script;
78
+ text: string;
79
+ }>;
80
+ /** liminalia.json(読み解いたもの)と、その字面(無い・読めないなら null。JSON の誤りの位置、型に無い項目、項目の行に使う)。 */
81
+ config: ProjectCheckConfig;
82
+ configText: string | null;
83
+ /** cast.json の cast と speakers、その字面(無ければ null)。 */
84
+ cast: Readonly<Record<string, unknown>>;
85
+ speakers: readonly string[];
86
+ castText: string | null;
87
+ /** 診断に書く cast.json の名前(作品のフォルダからのパス。既定 cast.json)。 */
88
+ castFile?: string;
89
+ /**
90
+ * 設定の JSON Schema(読めない環境では null。型に無い項目を見ない)。null の項目は、JSON として読めない所だけを知らせる
91
+ * (VS Code は liminalia.json と cast.json の型をエディタの JSON の検証に任せる)。
92
+ */
93
+ schemas?: {
94
+ liminalia?: JsonSchema | null;
95
+ cast?: JsonSchema | null;
96
+ lang?: JsonSchema | null;
97
+ };
98
+ /** 命令の仕様(作品の既定値 commandDefaults を重ねたもの)と、重ねる前のもの(既定値そのものの検査に使う)。 */
99
+ registry: Registry;
100
+ baseRegistry?: Registry;
101
+ /** 読み込んだプラグイン(標準の命令も)。命令の教えるジャンプ先、値を入れる変数、データの CG、プラグインの check に使う。 */
102
+ plugins: readonly CommandPlugin[];
103
+ /** 作品のデータ(paths.data の .json)を名前で読む口と、その字面(診断の行)。 */
104
+ data: (name: string) => unknown;
105
+ dataText?: (name: string) => string | undefined;
106
+ /** 診断に書くデータのフォルダの名前(作品のフォルダからのパス。既定 data)。 */
107
+ dataFolder?: string;
108
+ /** 原文以外の言語の訳のファイルの字面(無ければ null)。liminalia.json の languages の 2 番目からの順。 */
109
+ translations: readonly {
110
+ language: string;
111
+ text: string | null;
112
+ }[];
113
+ /**
114
+ * 素材の有無(無ければ素材の実在を見ない)。actual は大文字と小文字の違いを見る(@liminalia/lang の assetNameResolver)。
115
+ * head は素材のファイルの頭(Git LFS のポインタのままの素材を見分ける。@liminalia/project の assetHeads)。
116
+ */
117
+ assets?: {
118
+ exists: (folder: string, path: string) => boolean;
119
+ files?: (folder: string) => readonly string[] | undefined;
120
+ actual?: (folder: string, path: string) => string | null | undefined;
121
+ head?: (folder: string, path: string) => Uint8Array | null | undefined;
122
+ } | null;
123
+ /** voice-lock.json の字面(無ければ null)。 */
124
+ voiceLockText?: string | null;
125
+ /**
126
+ * パック(packs/<フォルダ>/。@liminalia/project の listPackSources)。パックの台本だけが使う訳の鍵とボイスの番号の固定を「使われていない」にせず、
127
+ * パックの訳(packs/<フォルダ>/lang/<言語>.json)を、本体にパックを重ねた台本で確かめる。無ければパックを見ない。
128
+ */
129
+ packs?: readonly PackCheckSource[];
130
+ /**
131
+ * 作品のフォルダの中のファイルを読む口(作品の CSS ui.css と、その中の url() と @import の検査。パスは作品のフォルダからの / 区切り)。
132
+ * 無ければ作品の CSS を見ない。
133
+ */
134
+ projectFiles?: ProjectFiles | null;
135
+ /** 素材の others のフォントを読む口(縦書きの字送り幅の検査。無ければ見ない)。 */
136
+ readFont?: (file: string) => Uint8Array | null;
137
+ /** UTF-8 で読めない台本(ファイル → 文字コードの名前)。そのファイルは bad-encoding だけにする。 */
138
+ encodings?: ReadonlyMap<string, string>;
139
+ /**
140
+ * 作品の画面のテンプレート(liminalia.json の ui.templates)の検査に使うもの(これか projectFiles が無ければ見ない)。rules は標準の画面の決まり
141
+ * (@liminalia/web/screen-rules の screenTemplateRules)、plugins はプラグインの "./web" が差し替える画面
142
+ * (@liminalia/project/screen-templates の pluginScreens)。テンプレートのファイルは projectFiles で読む(作品の CSS と同じ読み方)。
143
+ */
144
+ screenTemplates?: {
145
+ rules: ScreenTemplateRules;
146
+ plugins?: readonly PluginScreens[];
147
+ } | null;
148
+ /** 呼ぶ側だけが分かる診断(プラグインの package.json の合うエンジンの宣言など)。 */
149
+ more?: readonly Diagnostic[];
150
+ /**
151
+ * 黙らせる(// lim-ignore と check.severity)前に一覧を整える口。syntax は構文の診断(台本の解析が出したもの)。
152
+ * 制作画面が分類を付け、読み込めなかったプラグインの命令の指摘をまとめるのに使う。
153
+ */
154
+ adjust?: (diagnostics: Diagnostic[], syntax: ReadonlySet<Diagnostic>) => Diagnostic[];
155
+ }
156
+ /** プラグインの命令が教える行き先(制作画面のフローチャートと同じ)。 */
157
+ export declare function pluginTargetHooks(plugins: readonly CommandPlugin[]): Map<string, TargetHook>;
158
+ /**
159
+ * 作品全体の診断(lim check が出すもの。並びは集めた順。呼ぶ側が並べる)。台本の // lim-ignore と liminalia.json の check.severity を当て、
160
+ * 設定のファイルの診断は誤りのある項目の行に出す。
161
+ */
162
+ export declare function projectDiagnostics(input: ProjectCheckInput, cache?: ProjectFileCheckCache): Diagnostic[];
@@ -0,0 +1,32 @@
1
+ import type { Value } from "@liminalia/runtime";
2
+ /**
3
+ * 型の付いたプラグインの状態(セーブに入る stage.extra の一つの鍵)。命令の apply・run と、描画側の renderers・restorers の両方から同じ形で読み書きする。
4
+ * ```ts
5
+ * interface Stamps { list: { image: string; x: number }[] }
6
+ * export const stamps = defineState<Stamps>("stamp.list", () => ({ list: [] }));
7
+ * // 命令: apply(args, extra) { stamps.update(extra, (s) => { s.list.push({ image: String(args.image), x: Number(args.x) }); }); }
8
+ * // 描画: restorers: [(ctx, stage) => draw(stamps.read(stage.extra))]
9
+ * ```
10
+ * 値は JSON にできる素の値だけにする(関数・Map・Date・undefined は入れない)。鍵はプラグインの名前を頭に付けて、ほかと重ならないようにする。
11
+ * `as unknown as Value` と書かずに済むように、読み書きの型をここで合わせる(中身の形までは確かめない。古いセーブの形を直すなら read の後で直す)。
12
+ */
13
+ export interface PluginState<T> {
14
+ /** stage.extra の鍵。 */
15
+ readonly key: string;
16
+ /** 今の値(無ければ undefined)。 */
17
+ get(extra: Readonly<Record<string, Value>>): T | undefined;
18
+ /** 今の値(無ければ初めの値。初めの値を渡していなければ undefined で、そのとき T は undefined を含む)。返したものを書き換えても状態は変わらない(update で書く)。 */
19
+ read(extra: Readonly<Record<string, Value>>): T;
20
+ /** 値を入れる(写しを入れる)。 */
21
+ set(extra: Record<string, Value>, value: T): void;
22
+ /** 今の値(無ければ初めの値)の写しを change で書き換えて入れ、入れた値を返す。change が値を返せばそれを入れる。 */
23
+ update(extra: Record<string, Value>, change: (value: T) => T | void): T;
24
+ /** 鍵ごと消す(空になったら消すとセーブが小さくなる)。 */
25
+ clear(extra: Record<string, Value>): void;
26
+ }
27
+ /**
28
+ * 型の付いたプラグインの状態を作る。initial は値が無いときの初めの値(呼ぶたびに新しく作る)。
29
+ * initial を渡さなければ、値が無いとき read と update は undefined を渡すので、型も T | undefined になる。
30
+ */
31
+ export declare function defineState<T>(key: string, initial: () => T): PluginState<T>;
32
+ export declare function defineState<T>(key: string): PluginState<T | undefined>;
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.