rpg-engine 0.5.0 → 0.6.1

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 (218) hide show
  1. package/dist/campaign/settings.d.ts +1 -0
  2. package/dist/campaign/settings.js +6 -5
  3. package/dist/command-line.js +12 -5
  4. package/dist/commands/advance.js +1 -1
  5. package/dist/commands/ask.d.ts +1 -1
  6. package/dist/commands/ask.js +66 -24
  7. package/dist/commands/change.js +28 -17
  8. package/dist/commands/config.d.ts +1 -1
  9. package/dist/commands/config.js +67 -21
  10. package/dist/commands/effect.js +42 -23
  11. package/dist/commands/find.js +1 -1
  12. package/dist/commands/game-adventures.js +2 -2
  13. package/dist/commands/game-catalog.d.ts +13 -0
  14. package/dist/commands/game-catalog.js +26 -2
  15. package/dist/commands/game-checks.js +23 -21
  16. package/dist/commands/{game-hit-dice.d.ts → game-dice-pool.d.ts} +3 -3
  17. package/dist/commands/{game-hit-dice.js → game-dice-pool.js} +7 -7
  18. package/dist/commands/game-effects.d.ts +12 -4
  19. package/dist/commands/game-effects.js +21 -13
  20. package/dist/commands/game-examples.d.ts +22 -0
  21. package/dist/commands/game-examples.js +72 -0
  22. package/dist/commands/game-extension-list.d.ts +31 -3
  23. package/dist/commands/game-extension-list.js +83 -7
  24. package/dist/commands/game-images.d.ts +1 -1
  25. package/dist/commands/game-images.js +3 -2
  26. package/dist/commands/game-library.d.ts +3 -0
  27. package/dist/commands/game-library.js +2 -2
  28. package/dist/commands/game-mode.js +1 -1
  29. package/dist/commands/game-package-code.d.ts +87 -0
  30. package/dist/commands/game-package-code.js +648 -0
  31. package/dist/commands/game-package-hooks.d.ts +37 -0
  32. package/dist/commands/game-package-hooks.js +116 -0
  33. package/dist/commands/game-recipes.js +2 -2
  34. package/dist/commands/game-reminders.d.ts +5 -2
  35. package/dist/commands/game-reminders.js +7 -4
  36. package/dist/commands/game-rules.d.ts +4 -1
  37. package/dist/commands/game-rules.js +7 -1
  38. package/dist/commands/game-upkeep.js +3 -3
  39. package/dist/commands/game-view-place.d.ts +8 -20
  40. package/dist/commands/game-view-place.js +16 -35
  41. package/dist/commands/game-widgets.d.ts +39 -10
  42. package/dist/commands/game-widgets.js +138 -35
  43. package/dist/commands/game-world.d.ts +17 -0
  44. package/dist/commands/game-world.js +70 -12
  45. package/dist/commands/image.js +1 -1
  46. package/dist/commands/init.js +2 -2
  47. package/dist/commands/mode.d.ts +1 -1
  48. package/dist/commands/package.d.ts +8 -0
  49. package/dist/commands/package.js +81 -24
  50. package/dist/commands/progression.d.ts +2 -0
  51. package/dist/commands/progression.js +7 -2
  52. package/dist/commands/roll.d.ts +2 -0
  53. package/dist/commands/roll.js +50 -24
  54. package/dist/commands/rules.js +6 -4
  55. package/dist/commands/scene.d.ts +1 -1
  56. package/dist/commands/scene.js +13 -10
  57. package/dist/commands/sheet.js +10 -1
  58. package/dist/commands/status.d.ts +1 -0
  59. package/dist/commands/status.js +14 -4
  60. package/dist/commands/trade.js +6 -4
  61. package/dist/commands/translate.js +2 -2
  62. package/dist/commands/travel.js +1 -1
  63. package/dist/commands/validate.js +2 -2
  64. package/dist/commands/view.d.ts +8 -4
  65. package/dist/commands/view.js +7 -6
  66. package/dist/commands/worked-out.js +11 -5
  67. package/dist/commands/write.d.ts +8 -1
  68. package/dist/commands/write.js +84 -25
  69. package/dist/core/command-reference.js +3 -2
  70. package/dist/core/consents.d.ts +18 -0
  71. package/dist/core/consents.js +93 -0
  72. package/dist/core/context.d.ts +51 -29
  73. package/dist/core/context.js +3 -1
  74. package/dist/core/examples.d.ts +25 -0
  75. package/dist/core/examples.js +19 -0
  76. package/dist/{extensions/api.d.ts → core/package-api.d.ts} +134 -32
  77. package/dist/core/package-declarations.d.ts +102 -0
  78. package/dist/core/package-declarations.js +81 -0
  79. package/dist/core/registry.d.ts +2 -0
  80. package/dist/core/text.d.ts +5 -0
  81. package/dist/core/text.js +12 -0
  82. package/dist/dashboard/acts.js +31 -24
  83. package/dist/dashboard/address.js +4 -1
  84. package/dist/dashboard/api.js +54 -0
  85. package/dist/dashboard/app.js +140 -96
  86. package/dist/dashboard/ask-card.js +76 -25
  87. package/dist/dashboard/asked-dice.js +57 -0
  88. package/dist/dashboard/dice/tray.js +3 -3
  89. package/dist/dashboard/extension-widgets.js +104 -10
  90. package/dist/dashboard/i18n/ar.json +25 -29
  91. package/dist/dashboard/i18n/cs.json +25 -29
  92. package/dist/dashboard/i18n/da.json +25 -29
  93. package/dist/dashboard/i18n/de.json +25 -29
  94. package/dist/dashboard/i18n/el.json +25 -29
  95. package/dist/dashboard/i18n/es.json +25 -29
  96. package/dist/dashboard/i18n/fi.json +25 -29
  97. package/dist/dashboard/i18n/fr.json +25 -29
  98. package/dist/dashboard/i18n/he.json +25 -29
  99. package/dist/dashboard/i18n/hi.json +25 -29
  100. package/dist/dashboard/i18n/hu.json +25 -29
  101. package/dist/dashboard/i18n/is.json +25 -29
  102. package/dist/dashboard/i18n/it.json +25 -29
  103. package/dist/dashboard/i18n/ja.json +25 -29
  104. package/dist/dashboard/i18n/ko.json +25 -29
  105. package/dist/dashboard/i18n/nb.json +25 -29
  106. package/dist/dashboard/i18n/nl.json +25 -29
  107. package/dist/dashboard/i18n/pl.json +25 -29
  108. package/dist/dashboard/i18n/pt.json +25 -29
  109. package/dist/dashboard/i18n/ro.json +25 -29
  110. package/dist/dashboard/i18n/ru.json +25 -29
  111. package/dist/dashboard/i18n/sv.json +25 -29
  112. package/dist/dashboard/i18n/tr.json +25 -29
  113. package/dist/dashboard/i18n/uk.json +25 -29
  114. package/dist/dashboard/i18n/zh.json +25 -29
  115. package/dist/dashboard/icons.js +4 -1
  116. package/dist/dashboard/kit.js +35 -0
  117. package/dist/dashboard/labels.js +1 -0
  118. package/dist/dashboard/pack-card.js +7 -2
  119. package/dist/dashboard/package-page.js +50 -0
  120. package/dist/dashboard/packages.js +172 -23
  121. package/dist/dashboard/page-code.js +248 -0
  122. package/dist/dashboard/party.js +13 -14
  123. package/dist/dashboard/people.js +4 -0
  124. package/dist/dashboard/person-panel.js +110 -0
  125. package/dist/dashboard/place-map-view.js +11 -6
  126. package/dist/dashboard/scene.js +12 -9
  127. package/dist/dashboard/settings.js +55 -9
  128. package/dist/dashboard/sheet.js +21 -13
  129. package/dist/dashboard/status.js +69 -15
  130. package/dist/dashboard/style.css +592 -825
  131. package/dist/dashboard/top.js +75 -25
  132. package/dist/dashboard/turns.js +34 -13
  133. package/dist/dashboard/widgets.js +9 -2
  134. package/dist/dashboard-server.js +189 -10
  135. package/dist/dice/roll-dice.js +1 -1
  136. package/dist/effects/effect.d.ts +7 -4
  137. package/dist/effects/effect.js +12 -9
  138. package/dist/extensions/engine.d.ts +4 -0
  139. package/dist/extensions/engine.js +74 -0
  140. package/dist/extensions/extension.d.ts +25 -37
  141. package/dist/extensions/extension.js +26 -48
  142. package/dist/extensions/index.d.ts +3 -2
  143. package/dist/extensions/index.js +4 -1
  144. package/dist/extensions/packages.d.ts +6 -0
  145. package/dist/extensions/packages.js +100 -11
  146. package/dist/index.d.ts +1 -3
  147. package/dist/mcp-server.js +51 -14
  148. package/dist/page-words.d.ts +4 -0
  149. package/dist/page-words.js +4 -4
  150. package/dist/page.d.ts +218 -0
  151. package/dist/page.js +2 -0
  152. package/dist/pages/load.d.ts +7 -1
  153. package/dist/pages/load.js +10 -5
  154. package/dist/pages/page-file.js +1 -1
  155. package/dist/pages/stack-writes.js +5 -4
  156. package/dist/pages/world.d.ts +8 -0
  157. package/dist/pages/world.js +9 -2
  158. package/dist/systems/game-system.d.ts +52 -26
  159. package/dist/systems/game-system.js +141 -42
  160. package/dist/systems/index.d.ts +3 -3
  161. package/dist/systems/index.js +3 -3
  162. package/dist/systems/system-code.d.ts +29 -88
  163. package/dist/systems/system-code.js +68 -23
  164. package/dist/systems/words.d.ts +2 -0
  165. package/dist/systems/words.js +11 -0
  166. package/dist/testing.d.ts +20 -5
  167. package/dist/testing.js +49 -14
  168. package/instructions/combat.md +2 -2
  169. package/instructions/core.md +2 -2
  170. package/instructions/dashboard.md +2 -2
  171. package/instructions/mentor-tutorial.md +1 -1
  172. package/instructions/play.md +3 -3
  173. package/instructions/setup.md +1 -1
  174. package/package.json +10 -2
  175. package/systems/5e/LICENSE.md +13 -3
  176. package/systems/5e/dist/dying.js +83 -16
  177. package/systems/5e/dist/index.js +2 -2
  178. package/systems/5e/dist/page-style.js +634 -0
  179. package/systems/5e/dist/page.js +166 -0
  180. package/systems/5e/dist/shown.js +23 -0
  181. package/systems/5e/instructions/combat.md +1 -0
  182. package/systems/5e/package.json +4 -2
  183. package/systems/5e/system.yaml +37 -9
  184. package/systems/5e/versions/srd-5.1/system.yaml +2 -0
  185. package/systems/5e/words/ar.yaml +30 -0
  186. package/systems/5e/words/cs.yaml +30 -0
  187. package/systems/5e/words/da.yaml +30 -0
  188. package/systems/5e/words/de.yaml +30 -0
  189. package/systems/5e/words/el.yaml +30 -0
  190. package/systems/5e/words/es.yaml +30 -0
  191. package/systems/5e/words/fi.yaml +30 -0
  192. package/systems/5e/words/fr.yaml +30 -0
  193. package/systems/5e/words/he.yaml +30 -0
  194. package/systems/5e/words/hi.yaml +30 -0
  195. package/systems/5e/words/hu.yaml +30 -0
  196. package/systems/5e/words/is.yaml +30 -0
  197. package/systems/5e/words/it.yaml +30 -0
  198. package/systems/5e/words/ja.yaml +30 -0
  199. package/systems/5e/words/ko.yaml +30 -0
  200. package/systems/5e/words/nb.yaml +30 -0
  201. package/systems/5e/words/nl.yaml +30 -0
  202. package/systems/5e/words/pl.yaml +30 -0
  203. package/systems/5e/words/pt.yaml +30 -0
  204. package/systems/5e/words/ro.yaml +30 -0
  205. package/systems/5e/words/ru.yaml +30 -0
  206. package/systems/5e/words/sv.yaml +30 -0
  207. package/systems/5e/words/tr.yaml +30 -0
  208. package/systems/5e/words/uk.yaml +30 -0
  209. package/systems/5e/words/zh.yaml +30 -0
  210. package/dist/commands/game-extensions.d.ts +0 -34
  211. package/dist/commands/game-extensions.js +0 -407
  212. package/dist/commands/game-system-code.d.ts +0 -33
  213. package/dist/commands/game-system-code.js +0 -188
  214. package/dist/dashboard/death-save.js +0 -67
  215. package/dist/dashboard/dying.js +0 -46
  216. package/dist/dashboard/save-outcome.js +0 -42
  217. package/dist/dashboard/spend.js +0 -115
  218. /package/dist/{extensions/api.js → core/package-api.js} +0 -0
@@ -0,0 +1,93 @@
1
+ // The player's yes to the code of a package not ours, an extension's or a game system's (D-478, D-510, D-511): kept on this computer beside the packages npm
2
+ // installed, never in a campaign, for the package, its version and the fingerprint of its files; any other version, or a file changed since, has no yes.
3
+ import { createHash } from "node:crypto";
4
+ import { readdirSync, readFileSync, statSync } from "node:fs";
5
+ import { dirname, join, relative, sep } from "node:path";
6
+ import { installedFromFolder } from "./files.js";
7
+ import { files } from "./store.js";
8
+ /** The file of the yeses, beside the folder of the packages npm installed. */
9
+ const consentsFile = "consents.json";
10
+ /** The npm scope of the packages RPG Engine publishes, verified: their code runs without a yes (D-441). */
11
+ export const ourScope = "@rpgengine/";
12
+ /**
13
+ * Whether the code of the package in this folder may run (D-478, D-511): one the engine ships, outside npm's folders; one of ours from npm; one installed from
14
+ * a folder or a file of the player's; or another's the player said yes to, at this version and with these files.
15
+ */
16
+ export function packageCodeMayRun(folder) {
17
+ let manifest;
18
+ try {
19
+ manifest = JSON.parse(readFileSync(join(folder, "package.json"), "utf8"));
20
+ }
21
+ catch {
22
+ return false;
23
+ }
24
+ const name = typeof manifest.name === "string" ? manifest.name : "";
25
+ const linked = installedFromFolder(folder);
26
+ return consentsPath(folder) === undefined || linked || name.startsWith(ourScope) || hasConsent(folder, name, typeof manifest.version === "string" ? manifest.version : "");
27
+ }
28
+ /**
29
+ * The fingerprint of a package's files as installed: every file but those npm or git keep beside them, by its path and its bytes. Worked out again only when
30
+ * a file's size or time changed: it is asked at each load of the package's code.
31
+ */
32
+ export function packageFingerprint(folder) {
33
+ const paths = packageFiles(folder);
34
+ const signature = paths.map((path) => {
35
+ const stat = statSync(path);
36
+ return `${path}|${stat.size}|${stat.mtimeMs}`;
37
+ }).join("\n");
38
+ const known = fingerprints.get(folder);
39
+ if (known?.signature === signature) {
40
+ return known.fingerprint;
41
+ }
42
+ const hash = createHash("sha256");
43
+ for (const path of paths) {
44
+ hash.update(`${relative(folder, path).split(sep).join("/")}\0`).update(readFileSync(path)).update("\0");
45
+ }
46
+ const fingerprint = hash.digest("hex");
47
+ fingerprints.set(folder, { signature, fingerprint });
48
+ return fingerprint;
49
+ }
50
+ const fingerprints = new Map();
51
+ /** Records the player's yes to a package installed in a folder of npm's packages: its version and its files as they are now. */
52
+ export function recordConsent(folder, name, version) {
53
+ const file = consentsPath(folder);
54
+ if (file !== undefined) {
55
+ files().write(file, `${JSON.stringify({ ...readConsents(file), [name]: { version, fingerprint: packageFingerprint(folder) } }, null, 2)}\n`);
56
+ }
57
+ }
58
+ /** Takes the player's yes to a package away, as when it leaves this computer. */
59
+ export function dropConsent(folder, name) {
60
+ const file = consentsPath(folder);
61
+ const kept = file === undefined ? {} : readConsents(file);
62
+ if (file !== undefined && Object.hasOwn(kept, name)) {
63
+ files().write(file, `${JSON.stringify(Object.fromEntries(Object.entries(kept).filter(([one]) => one !== name)), null, 2)}\n`);
64
+ }
65
+ }
66
+ /** Whether the player said yes to this package's code as it is installed now: its name, its version and its files. */
67
+ export function hasConsent(folder, name, version) {
68
+ const file = consentsPath(folder);
69
+ const given = file === undefined ? undefined : readConsents(file)[name];
70
+ return given !== undefined && given.version === version && given.fingerprint === packageFingerprint(folder);
71
+ }
72
+ /** The file of the yeses for a package in a folder of npm's packages, as node_modules/@scope/name; undefined for one elsewhere. */
73
+ function consentsPath(folder) {
74
+ const parts = folder.split(/[\\/]/);
75
+ const at = parts.lastIndexOf("node_modules");
76
+ return at < 0 ? undefined : join(dirname(parts.slice(0, at + 1).join(sep)), consentsFile);
77
+ }
78
+ function readConsents(file) {
79
+ try {
80
+ const read = JSON.parse(files().text(file) ?? "{}");
81
+ return typeof read === "object" && read !== null && !Array.isArray(read) ? read : {};
82
+ }
83
+ catch {
84
+ return {};
85
+ }
86
+ }
87
+ /** A package's own files, in a fixed order: not those npm or git keep beside them. */
88
+ function packageFiles(folder) {
89
+ return readdirSync(folder, { withFileTypes: true })
90
+ .filter((entry) => !["node_modules", ".git"].includes(entry.name))
91
+ .sort((first, second) => (first.name < second.name ? -1 : first.name > second.name ? 1 : 0))
92
+ .flatMap((entry) => (entry.isDirectory() ? packageFiles(join(folder, entry.name)) : entry.isFile() ? [join(folder, entry.name)] : []));
93
+ }
@@ -23,24 +23,32 @@ export interface Context {
23
23
  /** The folders that hold the installed game systems, nearest first (SYS-1). */
24
24
  systemFolders: string[];
25
25
  /**
26
- * The code of the systems that bring some, by name, loaded as the command line, the MCP server or the dashboard starts (D-448): its hooks, which the
27
- * systems module types, or what kept it from loading.
26
+ * The code of the systems that bring some, by name, loaded as the command line, the MCP server or the dashboard starts (D-448): what it gives, a package's
27
+ * code (D-514), or what kept it from loading, as another's code without the player's yes (D-511) or one made for another API.
28
28
  */
29
- systemCode?: Record<string, {
30
- hooks: object;
29
+ systemCode?: Record<string, ({
30
+ code: object;
31
31
  } | {
32
32
  problem: string;
33
+ } | {
34
+ refused: string;
35
+ }) & {
36
+ version?: string;
33
37
  }>;
34
38
  /** The folders that hold the installed extensions, each a package folder or npm's node_modules (D-436); none where missing. */
35
39
  extensionFolders?: string[];
36
40
  /** The AI app the MCP server serves, by the name it gives itself, such as claude-code; missing on the command line. */
37
41
  host?: () => string | undefined;
42
+ /** The packages the player said no to in a window in this session, by the name npm describes: never asked again until the server starts again (D-510). */
43
+ declined?: Set<string>;
38
44
  /** The chat the MCP server serves, as the dashboard needs it for the player's sentences (D-495); missing on the command line. */
39
45
  chat?: ChatState;
40
46
  /** The command was typed by the player in their own terminal: their own hands, as the yes to a package not ours needs (D-441). */
41
47
  terminal?: boolean;
42
48
  /** npm on this computer, which installs the packages in the engine's own folder (D-436); missing where nothing installs, as in most tests. */
43
49
  packages?: PackageManager;
50
+ /** rpg-engine itself on npm, which the player updates from the dashboard, never the master (D-515 (3)); missing outside the game's server, and in tests. */
51
+ engine?: EngineUpdater;
44
52
  /** A window of the player's operating system, for a yes the master cannot give (D-478); only where a player sits, never in the tests. */
45
53
  confirm?: Confirm;
46
54
  /** Downloads a file over https, at most `most` bytes (ADV-1); missing where nothing reaches the web, as in the tests. */
@@ -100,6 +108,11 @@ export interface PackageInfo {
100
108
  code?: boolean;
101
109
  /** Whether it needs other packages, which npm installs beside it. */
102
110
  dependencies?: boolean;
111
+ /** Its latest version, when that one needs a newer rpg-engine than this one and this is the newest this one reads (D-515 (2)): with the first engine that reads it. */
112
+ newer?: {
113
+ version: string;
114
+ engine?: string;
115
+ };
103
116
  }
104
117
  /** What the window of the player's operating system said: yes, no, or none when it could not be shown. */
105
118
  export type Confirmed = "yes" | "no" | "none";
@@ -126,6 +139,30 @@ export interface PackageManager {
126
139
  failed: string;
127
140
  }>;
128
141
  }
142
+ /** How this rpg-engine is installed (D-515 (3)): globally by npm, which updates it; as npm link of a folder in development; or any other way, from that folder. */
143
+ export type EngineInstall = {
144
+ how: "global";
145
+ } | {
146
+ how: "link";
147
+ folder: string;
148
+ } | {
149
+ how: "other";
150
+ folder: string;
151
+ };
152
+ /** rpg-engine itself on npm (D-515 (3)): its latest version, how this one is installed, and its update to a version, as it was installed. */
153
+ export interface EngineUpdater {
154
+ /** The latest version npm has; why not when npm cannot be asked. */
155
+ latest(): Promise<{
156
+ version: string;
157
+ } | {
158
+ failed: string;
159
+ }>;
160
+ installed(): Promise<EngineInstall>;
161
+ /** The version in its folder now, which a chat started after an update runs, the running one being read as the server starts. */
162
+ onDisk(): string;
163
+ /** Installs that version globally with npm: undefined once it is installed, else why not. */
164
+ update(version: string): Promise<string | undefined>;
165
+ }
129
166
  /** A program of this computer that writes and draws outside the chat, with the player's own login (D-424). */
130
167
  export type HelperName = "codex" | "claude";
131
168
  /** How a helper program stands: not on this computer, there without the player's login, signed in with an API key, which the engine never uses, or ready. */
@@ -220,11 +257,10 @@ export interface PictureMaker {
220
257
  export interface Said {
221
258
  said: string;
222
259
  }
223
- /** Whose sheet a roll's checks read, and by button the field each one rolls, for the page to light that row of the sheet (ASK-12); a death save, what it is. */
260
+ /** Whose sheet a roll's checks read, and by button the field each one rolls, for the page to light that row of the sheet (ASK-12). */
224
261
  export interface Rows {
225
262
  who: string;
226
263
  fields: (string | null)[];
227
- save?: SaveAsked;
228
264
  /** By button, its name and the note under it when a package words it, as Reroll and 3 left (D-507). */
229
265
  buttons?: ({
230
266
  name: string;
@@ -233,9 +269,11 @@ export interface Rows {
233
269
  /** The rule under the buttons, in a line. */
234
270
  rule?: string;
235
271
  card?: CardAsked;
272
+ /** The roll is forced (D-507): no button turns it down, and no words of the player's take its place. */
273
+ forced?: true;
236
274
  }
237
275
  /**
238
- * The card of a package's widget a question is asked in (D-507): the widget, by its extension's name and its own, as lockpicking.lock, and which attempt it is;
276
+ * The card of a package's widget a question is asked in (D-507): the widget, by its package's name and its own, as lockpicking.lock, and which attempt it is;
239
277
  * what it shows, read when it is asked for, never in the way of the question.
240
278
  */
241
279
  export interface CardAsked {
@@ -243,26 +281,6 @@ export interface CardAsked {
243
281
  key: string;
244
282
  shows(): Promise<unknown>;
245
283
  }
246
- /** A death save the question asks (DIE-4, D-460): its die, the total that succeeds, its counters as they stand, and what the lowest and highest faces do. */
247
- export interface SaveAsked {
248
- sides: number;
249
- atLeast: number;
250
- successes: {
251
- field: string;
252
- value: number;
253
- most: number;
254
- };
255
- failures: {
256
- field: string;
257
- value: number;
258
- most: number;
259
- };
260
- lowest?: number;
261
- highest?: {
262
- field: string;
263
- value: number;
264
- };
265
- }
266
284
  /** A square of a place's map the player touched, by its name, such as E4 (ASK-11). */
267
285
  export interface Picked {
268
286
  square: string;
@@ -293,6 +311,8 @@ export interface SpendAsked {
293
311
  adds: number;
294
312
  total: number;
295
313
  }[];
314
+ /** A package's rule under the dice (D-514). */
315
+ rule?: string;
296
316
  }
297
317
  /**
298
318
  * The dice of a rest as a page asks them (ASK-14): what it shows now, a die of a counter spent, or why not, and what the master hears of the dice spent when
@@ -307,13 +327,15 @@ export interface Player {
307
327
  choose(question: string, title: string, labels: string[], signal?: AbortSignal, rows?: Rows): Promise<number | Said | undefined | "unavailable" | "absent">;
308
328
  /** Asks where a player character, who, moves on the map of its place (ASK-11): the square, the change of mind as its one button (0), or the player's words; only a page can. */
309
329
  chooseSquare?(question: string, title: string, change: string, who: string, signal?: AbortSignal): Promise<Picked | 0 | Said | undefined | "absent">;
310
- /** Asks the player to spend the dice of a rest one at a time (ASK-14), until the button that ends it (0); only a page can. */
311
- spendDice?(question: string, title: string, done: string, spending: Spending, signal?: AbortSignal): Promise<0 | undefined | "absent">;
330
+ /** Asks the player to spend the dice of a rest one at a time (ASK-14), until the button that ends it (0), maybe in a package's card (D-514); only a page can. */
331
+ spendDice?(question: string, title: string, done: string, spending: Spending, signal?: AbortSignal, card?: CardAsked): Promise<0 | undefined | "absent">;
312
332
  /** Whether a question waits for the player there now, as on the dashboard's page; a form does not say. */
313
333
  asking?(): boolean;
314
334
  /** As the call whose questions were asked in a card ends: the card as it is after the last dice (D-507). */
315
335
  cardEnded?(card: CardAsked): void;
316
336
  }
317
337
  export declare function defaultContext(folder?: string): Context;
338
+ /** The folder of the game systems the engine ships, from src/core/ and from dist/core/ alike two levels up: those it brings without npm (D-171). */
339
+ export declare const engineSystemsFolder: string;
318
340
  /** Where the engine installs the packages, with npm, on this computer (D-436): the player's local data, beside the programs it installs (D-425). */
319
341
  export declare function packagesFolder(): string;
@@ -12,7 +12,7 @@ export function defaultContext(folder = process.cwd()) {
12
12
  actor: "master",
13
13
  platform: process.platform,
14
14
  // From src/core/ and from dist/core/ alike, the package's systems/ folder is two levels up; then those npm installed (D-485).
15
- systemFolders: [fileURLToPath(new URL("../../systems/", import.meta.url)), join(packagesFolder(), "node_modules")],
15
+ systemFolders: [engineSystemsFolder, join(packagesFolder(), "node_modules")],
16
16
  extensionFolders: [join(packagesFolder(), "node_modules")],
17
17
  home: userDataFolder(),
18
18
  bookIndex: join(dirname(packagesFolder()), "library"),
@@ -20,6 +20,8 @@ export function defaultContext(folder = process.cwd()) {
20
20
  pageFolder: fileURLToPath(new URL("../../dist/dashboard/", import.meta.url)),
21
21
  };
22
22
  }
23
+ /** The folder of the game systems the engine ships, from src/core/ and from dist/core/ alike two levels up: those it brings without npm (D-171). */
24
+ export const engineSystemsFolder = fileURLToPath(new URL("../../systems/", import.meta.url));
23
25
  /** Where the engine installs the packages, with npm, on this computer (D-436): the player's local data, beside the programs it installs (D-425). */
24
26
  export function packagesFolder() {
25
27
  const home = homedir();
@@ -0,0 +1,25 @@
1
+ /** What the descriptions' examples name, by placeholder. */
2
+ export interface Examples {
3
+ /** The counter damage takes from, as hp. */
4
+ counter: string;
5
+ /** A roll of a number of the sheet, as 1d20+str-save. */
6
+ roll: string;
7
+ /** Two checks of ask, each with its name and its dice, as Atletica 1d20+athletics. */
8
+ check: string;
9
+ otherCheck: string;
10
+ /** A coin and a smaller one, as gp and sp. */
11
+ coin: string;
12
+ smallCoin: string;
13
+ /** Three uses of a turn, as action, bonus action, reaction. */
14
+ uses: string;
15
+ /** A rest, as long rest. */
16
+ rest: string;
17
+ /** A counter of a pool of dice spent in a rest, as hit-dice-d6. */
18
+ pool: string;
19
+ /** A field an effect adds to, as bonus-ac. */
20
+ bonus: string;
21
+ }
22
+ /** The examples of a game without a system, or with one that does not name them. */
23
+ export declare const neutralExamples: Examples;
24
+ /** A description with its {{placeholders}} filled from the examples; one the examples lack stays as written. */
25
+ export declare function withExamples(text: string, examples?: Examples): string;
@@ -0,0 +1,19 @@
1
+ // The examples in the commands' descriptions (D-518): a description writes {{counter}} where an example names a game's thing, filled with the names of the
2
+ // campaign's system where the MCP server runs in one, else with neutral names, as the command line and the reference have them.
3
+ /** The examples of a game without a system, or with one that does not name them. */
4
+ export const neutralExamples = {
5
+ counter: "health",
6
+ roll: "2d6+wits",
7
+ check: "Forza 2d6+strength",
8
+ otherCheck: "Agilità 2d6+agility",
9
+ coin: "gold",
10
+ smallCoin: "silver",
11
+ uses: "action, move, reaction",
12
+ rest: "night's rest",
13
+ pool: "stamina-d6",
14
+ bonus: "bonus-armor",
15
+ };
16
+ /** A description with its {{placeholders}} filled from the examples; one the examples lack stays as written. */
17
+ export function withExamples(text, examples = neutralExamples) {
18
+ return text.replace(/\{\{(\w+)\}\}/g, (whole, name) => (Object.hasOwn(examples, name) ? examples[name] : whole));
19
+ }
@@ -1,26 +1,62 @@
1
1
  import type { z } from "zod";
2
- /** What an extension's code gets when it loads: zod, to describe its commands' input with the same library the engine checks them with. */
3
- export interface ExtensionKit {
2
+ /** What a package's code gets when it loads: zod, to describe its commands' input with the same library the engine checks them with. */
3
+ export interface PackageKit {
4
4
  z: typeof z;
5
5
  }
6
- /** The default export of an extension's code: given the kit, its commands and what it does when time passes. */
7
- export type ExtensionEntry = (kit: ExtensionKit) => ExtensionCode;
8
- /** What an extension's code gives rpg-engine. */
9
- export interface ExtensionCode {
6
+ /** The default export of a package's code: given the kit, what it gives rpg-engine. */
7
+ export type PackageEntry = (kit: PackageKit) => PackageCode;
8
+ /**
9
+ * What a package's code gives rpg-engine, each part optional, the same for every kind of package (D-511, D-514). The hooks after the engine's own writes,
10
+ * counterChanged, turnStarted, rolled and effectAdded, are called for the campaign's game system first, then for its extensions in order, each giving lines for
11
+ * the command's output; they are called at once, never waiting.
12
+ */
13
+ export interface PackageCode {
10
14
  /** Its commands, which the command line and the MCP server give the master beside the core's (D-63). */
11
- commands?: ExtensionCommand<any>[];
15
+ commands?: PackageCommand<any>[];
12
16
  /** After advance or travel moved the game date: lines for their output, such as the weather of a new morning (D-436). */
13
17
  timePassed?(passage: TimePassage, game: Game): string[] | Promise<string[]>;
14
18
  /**
15
- * What each widget its extension.yaml declares shows now, by the widget's name there (D-502): called as the dashboard reads the game, it only reads; nothing
16
- * shows for undefined. Read as the card of a question, it is given the card's key, the attempt to show (D-507).
19
+ * What each widget its extension.yaml or system.yaml declares shows now, by the widget's name there (D-502): called as the dashboard reads the game, it only
20
+ * reads; nothing shows for undefined. Read as the card of a question, it is given the card's key, the attempt to show (D-507), and whose roll it is; for a card or a page of
21
+ * its page code that names it, the character the card shows, as who (D-514); in place person, each of the party in turn, as who.
17
22
  */
18
- widgets?: Record<string, (game: GameView, card?: {
19
- key: string;
23
+ widgets?: Record<string, (game: GameView, asked?: {
24
+ key?: string;
25
+ who?: string;
20
26
  }) => Widget | undefined | Promise<Widget | undefined>>;
27
+ /** After change, or a rest's dice, wrote a counter of a page. Writes made through the game call no hook. */
28
+ counterChanged?(change: CounterChange, game: Game): string[];
29
+ /** As someone's turn starts in a scene. */
30
+ turnStarted?(turn: {
31
+ who: string;
32
+ }, game: Game): string[];
33
+ /** After a roll for someone was logged, never a hidden one. */
34
+ rolled?(roll: Rolled & {
35
+ who: string;
36
+ }, game: Game): string[];
37
+ /** After an effect was added to a page, never to a copy. */
38
+ effectAdded?(added: {
39
+ page: string;
40
+ effect: string;
41
+ }, game: Game): string[];
42
+ /**
43
+ * Before the core's ask shows its buttons: how the dashboard asks this roll (D-507), as game.ask words it, such as in the card of one of its widgets and with
44
+ * no button to turn it down; undefined to ask as always. The first package that gives one words the roll. It only reads.
45
+ */
46
+ asking?(question: AskingQuestion, game: GameView): Asking | undefined;
47
+ }
48
+ /**
49
+ * What the core's ask asks, as asking gets it: whose roll, the checks' names and their dice, in order; for the dice of a rest, the recipe, the checks being the
50
+ * counters of dice and the notations a die of each, as 1d8.
51
+ */
52
+ export interface AskingQuestion {
53
+ who: string;
54
+ checks: string[];
55
+ notations: string[];
56
+ recipe?: string;
21
57
  }
22
- /** A command of an extension: its name is the extension's, or starts with it and a hyphen, as weather or weather-set (D-63). */
23
- export interface ExtensionCommand<Input extends z.ZodObject = z.ZodObject> {
58
+ /** A command of a package: its name is the package's, or starts with it and a hyphen, as weather or weather-set (D-63). */
59
+ export interface PackageCommand<Input extends z.ZodObject = z.ZodObject> {
24
60
  name: string;
25
61
  /** Written for an AI: what it does (the first sentence), when to use it, an example. */
26
62
  description: string;
@@ -29,6 +65,8 @@ export interface ExtensionCommand<Input extends z.ZodObject = z.ZodObject> {
29
65
  readOnly?: boolean;
30
66
  /** Fields the command line takes as positional arguments, in order: weather-set 2. */
31
67
  positionals?: string[];
68
+ /** The player may run it too, from the package's code in the dashboard's page, with run (D-510); the master hears it at their next call. */
69
+ player?: boolean;
32
70
  /**
33
71
  * It may ask the player with game.ask (D-505): through MCP the host is told it waits for the player, so that it does not give up. Unlike the core's ask it
34
72
  * stays on the command line and where nothing shows buttons, where ask gives the question in words.
@@ -56,6 +94,15 @@ export interface TimePassage {
56
94
  from: GameMoment;
57
95
  to: GameMoment;
58
96
  }
97
+ /** A counter a command changed on a page: before and after, its maximum, and what damage took of it past what shields it. */
98
+ export interface CounterChange {
99
+ page: string;
100
+ field: string;
101
+ before: number;
102
+ after: number;
103
+ max?: number;
104
+ lost: number;
105
+ }
59
106
  /** The campaign as a widget reads it (D-502): what the code's commands reach, without the dice, the log, asking or writing. */
60
107
  export interface GameView {
61
108
  /** Now, in the game; undefined before the game has a date. */
@@ -85,12 +132,16 @@ export interface GameView {
85
132
  round?: number;
86
133
  turn?: string;
87
134
  } | undefined;
88
- /** The extension's own state, kept in the campaign. */
135
+ /** A setting of the campaign, as mentor; undefined when it has none. */
136
+ setting(name: string): string | undefined;
137
+ /** Whether two names are the same, as the engine compares them: case and accents aside. */
138
+ sameName(one: string, other: string): boolean;
139
+ /** The package's own state, kept in the campaign. */
89
140
  state: {
90
141
  read(): unknown;
91
142
  };
92
143
  }
93
- /** A page as an extension's code reads it (D-505), with what its effects give and what the game system works out, as show gives it. */
144
+ /** A page as a package's code reads it (D-505), with what its effects give and what the game system works out, as show gives it. */
94
145
  export interface GamePage {
95
146
  name: string;
96
147
  /** The player's character. */
@@ -109,18 +160,36 @@ export interface GamePage {
109
160
  /** A formula of the game system worked out on it, as has(skills, stealth) * proficiency; undefined when it has no value. It throws when it does not read. */
110
161
  formula(text: string): number | undefined;
111
162
  }
112
- /** The campaign as an extension's code reaches it: only through these; it writes only its own state and the fields it adds to the system (D-428, D-436, D-505). */
163
+ /**
164
+ * The campaign as a package's code reaches it: only through these (D-428, D-436, D-505, D-511): the fields and the effects of any page, its own state and the
165
+ * log. Each write has its line in the log, public or hidden as the engine shows that page.
166
+ */
113
167
  export interface Game extends GameView {
114
168
  /**
115
- * Rolls with the engine's dice, as 1d6 or 4d6kh3: the total, each die's face, and the roll as one line. With by, a roll in the log for who (D-505): in view
116
- * for the party, behind the screen for anyone else as the master-rolls setting says (D-287); with values, the faces of the player's physical dice, in view.
169
+ * Rolls with the engine's dice, as 1d6 or 4d6kh3: the total, each die's face and each die as thrown, and the roll as one line. With by, a roll in the log for
170
+ * who (D-505): in view for the party, behind the screen for anyone else as the master-rolls setting says (D-287); with values, the faces of the player's
171
+ * physical dice, in view.
117
172
  */
118
173
  roll(notation: string, by?: RollFor): Rolled;
119
174
  /**
120
- * Sets fields on a page, numbers or text, only those the extension's extension.yaml adds as fields or counters (D-505): a counter keeps its maximum. Each
121
- * field has its line in the log, which the player sees when the engine shows them that page. It throws for another field, or a name no page alone has.
175
+ * Sets fields on a page, any field, numbers or text, as write --set does, with its checks: a number on a counter keeps its maximum. It throws what write
176
+ * refuses, and for a name no page alone has, by name or alias. A counter the rules watch, such as hit points, is changed with change.
122
177
  */
123
178
  set(page: string, values: Record<string, number | string>, why: string): void;
179
+ /**
180
+ * Changes a counter or money on a page as the change command does, the way to change one the rules watch, such as hit points: by an amount, to a value, or
181
+ * spent, within its limits; its text, with the hooks' lines. Called from a command it calls the hooks of the campaign's packages after the change; from
182
+ * inside a hook, none, so that no change sets off another.
183
+ */
184
+ change(page: string, field: string, amount: {
185
+ by?: number | string;
186
+ to?: number | string;
187
+ spend?: number | string;
188
+ }, why: string): string;
189
+ /** Adds an effect without end; the engine's notes on what it breaks of what one keeps, or undefined when the page has it already. */
190
+ addEffect(page: string, name: string, why: string): string[] | undefined;
191
+ /** Ends an effect; whether the page had it. */
192
+ endEffect(page: string, name: string, why: string): boolean;
124
193
  /**
125
194
  * Asks the player for a roll of their character, with the buttons of ask (D-505): the roll, logged as theirs; declined, when they change their mind; said, their
126
195
  * own words in place of a button; in words, the question to ask them in the chat where no buttons show: with physical dice they tell the faces,
@@ -140,27 +209,35 @@ export interface RollFor {
140
209
  why: string;
141
210
  check?: string;
142
211
  values?: number[];
143
- /** What the faces mean, which the player sees in place of the total when a sum means nothing, as "4 pins, no 1": in the extension's words, translated. */
212
+ /** What the faces mean, which the player sees in place of the total when a sum means nothing, as "4 pins, no 1": in the package's words, translated. */
144
213
  says?: (faces: number[]) => WidgetText;
145
214
  /** How each die turned out, by its face in order, for the page to colour it: a 1 that resets a lock is bad (D-507). */
146
215
  tones?: (faces: number[]) => (DieTone | undefined)[];
147
216
  }
217
+ /** The colour of the moment of a card of a question (D-517), by the dashboard's token: danger, an ally's green, gold, muted. */
218
+ export type CardTint = "low" | "ally" | "gold" | "muted";
148
219
  /** How a die, or a part of a card, turned out for the one who rolls: good or bad, as the page colours it. */
149
220
  export type DieTone = "good" | "bad";
150
- /** The words of a button: its name, or its name with a note under it, as "Reroll" and "3 left"; the extension's words, translated. */
221
+ /** The words of a button: its name, or its name with a note under it, as "Reroll" and "3 left"; the package's words, translated. */
151
222
  export type ButtonWords = WidgetText | {
152
223
  label: WidgetText;
153
224
  note: WidgetText;
154
225
  };
155
226
  /**
156
- * A roll asked of the player (D-505): the question, the master's words or the extension's own, translated by its words; the check's name and its dice; the
157
- * words of the button that turns it down, in place of the core's change of mind, translated too; and what the faces mean, as for a roll with by.
227
+ * A roll asked of the player (D-505): the question, the master's words or the package's own, translated by its words; the check's name and its dice; and how
228
+ * the dashboard asks it.
158
229
  */
159
- export interface AskedRoll {
230
+ export interface AskedRoll extends Asking {
160
231
  who?: string;
161
232
  question: WidgetText;
162
233
  check: string;
163
234
  notation: string;
235
+ }
236
+ /**
237
+ * How the dashboard asks a roll, in a package's words (D-507): the roll's button; the button that turns it down, renamed, in place of the core's change of mind,
238
+ * or none when the roll is forced; the rule under the buttons; the card of one of its widgets; and what the faces mean, as for a roll with by.
239
+ */
240
+ export interface Asking {
164
241
  /** The roll's button, in place of the core's "Roll: check (dice)". */
165
242
  roll?: ButtonWords;
166
243
  /** The button that turns it down, renamed; false for none, when the roll is forced, as a death save (D-507). */
@@ -168,8 +245,8 @@ export interface AskedRoll {
168
245
  /** The rule under the buttons, in a line, as "A 1 resets the lock". */
169
246
  rule?: WidgetText;
170
247
  /**
171
- * The card the dashboard asks it in (D-507): one of the extension's widgets, by its name in extension.yaml, and which attempt it is, the same for each
172
- * question of it, as a reroll after the roll. The page shows the widget as it is before the dice and as it is after; the code writes its state first.
248
+ * The card the dashboard asks it in (D-507): one of the package's widgets, by its name in extension.yaml or system.yaml, and which attempt it is, the same for
249
+ * each question of it, as a reroll after the roll. The page shows the widget as it is before the dice and as it is after; the code writes its state first.
173
250
  */
174
251
  card?: {
175
252
  widget: string;
@@ -178,10 +255,16 @@ export interface AskedRoll {
178
255
  says?: (faces: number[]) => WidgetText;
179
256
  tones?: (faces: number[]) => (DieTone | undefined)[];
180
257
  }
181
- /** A roll made: with by, the id of its line in the log and whether it was hidden behind the screen. */
258
+ /** A roll made: its dice as written, each die as thrown, as the lower of two kept highest dropped; with by, the id of its line in the log and whether it was hidden. */
182
259
  export interface Rolled {
260
+ notation: string;
183
261
  total: number;
184
262
  faces: number[];
263
+ dice: {
264
+ sides: number | "F";
265
+ value: number;
266
+ dropped?: boolean;
267
+ }[];
185
268
  text: string;
186
269
  id?: string;
187
270
  hidden?: boolean;
@@ -207,10 +290,21 @@ export type Asked = {
207
290
  * widget's title, its note and its parts. The server checks it, and keeps it short.
208
291
  */
209
292
  export interface Widget {
210
- /** One of the icons of extension.yaml, in place of the widget's own. */
293
+ /** What only its page code draws (D-510), as the pins of a lock: JSON, kept short, which goes only to the page, never to the master. */
294
+ data?: unknown;
295
+ /** The figure of its page code that draws the whole inside of its card of a roll, the dashboard keeping the question and the field for words (D-510). */
296
+ body?: string;
297
+ /** One of the package's icons, in place of the widget's own; in place person, the mark of their state on their token. */
211
298
  icon?: string;
212
- /** The few words of a chip in the top, as 10–15 °C. */
299
+ /** The few words of a chip in the top, as 10–15 °C; in place person, the word of their state, as Dying, tinted by its lead's tone. */
213
300
  chip?: WidgetText;
301
+ /** In place person, dead by the package's rules though not yet marked so (D-516): drawn as the dead are, greyed, with the skull. */
302
+ dead?: boolean;
303
+ /**
304
+ * In the card of a question, the colour of its moment, as the 5e's death save in the red of danger (D-517): one of the dashboard's tokens, low for danger,
305
+ * ally, gold or muted; the card then has a frame of that tint, without the robot. None, as the lock's card: the question's own frame (D-509).
306
+ */
307
+ tint?: CardTint;
214
308
  /** What it says whole, in a sentence: the chip's tip, and its name for a screen reader. */
215
309
  says?: WidgetText;
216
310
  /** A note at the end of a card's head. */
@@ -218,7 +312,7 @@ export interface Widget {
218
312
  parts?: WidgetPart[];
219
313
  }
220
314
  /**
221
- * Words of the extension, written in its language: translated whole by its words/<code>.yaml, as "Light fog this morning"; or a phrase whose {names} are values
315
+ * Words of the package, written in its language: translated whole by its words/<code>.yaml, as "Light fog this morning"; or a phrase whose {names} are values
222
316
  * the page writes in its own language, as {text: "From {low} to {high}", values: {low: 10, high: 15}}.
223
317
  */
224
318
  export type WidgetText = string | {
@@ -248,16 +342,24 @@ export interface Track {
248
342
  coming?: number;
249
343
  stage?: "start" | "center" | "end";
250
344
  tone?: DieTone;
345
+ /** The figure of the package's page code that draws it, in place of the dashboard's pips (D-510); its label and value still say it in words. */
346
+ figure?: string;
347
+ /** The counter of the sheet it counts, which leaves the line of values under the name while a widget in place person shows it (D-514). */
348
+ field?: string;
251
349
  }
252
350
  /**
253
351
  * A part of a widget's card: one thing large, with its icon and its value; text; facts, as chips; values, each in a box under its label; a count as pips or a
254
- * bar; rows of a label, a value and a note; a table; a picture of the extension's images/.
352
+ * bar; rows of a label, a value and a note; a table; a picture of the package's images/.
255
353
  */
256
354
  export type WidgetPart = {
257
355
  lead: WidgetText;
258
356
  icon?: string;
259
357
  value?: WidgetValue;
260
358
  tone?: DieTone;
359
+ figure?: string;
360
+ } | {
361
+ who: string;
362
+ does?: WidgetText;
261
363
  } | {
262
364
  text: WidgetText;
263
365
  } | {