rpg-engine 0.4.1 → 0.5.0

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 (80) hide show
  1. package/README.md +1 -1
  2. package/dist/commands/ask.d.ts +37 -2
  3. package/dist/commands/ask.js +46 -17
  4. package/dist/commands/config.js +4 -2
  5. package/dist/commands/game-extension-list.js +12 -0
  6. package/dist/commands/game-extensions.d.ts +1 -1
  7. package/dist/commands/game-extensions.js +242 -17
  8. package/dist/commands/game-system-code.d.ts +9 -1
  9. package/dist/commands/game-system-code.js +27 -11
  10. package/dist/commands/game-widgets.d.ts +6 -1
  11. package/dist/commands/game-widgets.js +52 -4
  12. package/dist/commands/game-world.d.ts +15 -3
  13. package/dist/commands/game-world.js +45 -14
  14. package/dist/commands/package.d.ts +7 -1
  15. package/dist/commands/package.js +17 -2
  16. package/dist/commands/scene.d.ts +1 -1
  17. package/dist/commands/view.d.ts +4 -0
  18. package/dist/commands/view.js +5 -3
  19. package/dist/core/context.d.ts +19 -0
  20. package/dist/core/files.d.ts +2 -0
  21. package/dist/core/files.js +10 -1
  22. package/dist/core/registry.d.ts +2 -0
  23. package/dist/dashboard/api.js +11 -3
  24. package/dist/dashboard/app.js +88 -8
  25. package/dist/dashboard/ask-card.js +118 -0
  26. package/dist/dashboard/dice/tray.js +5 -3
  27. package/dist/dashboard/extension-widgets.js +35 -9
  28. package/dist/dashboard/faces.js +6 -4
  29. package/dist/dashboard/help.js +10 -3
  30. package/dist/dashboard/i18n/ar.json +9 -0
  31. package/dist/dashboard/i18n/cs.json +9 -0
  32. package/dist/dashboard/i18n/da.json +9 -0
  33. package/dist/dashboard/i18n/de.json +9 -0
  34. package/dist/dashboard/i18n/el.json +9 -0
  35. package/dist/dashboard/i18n/es.json +9 -0
  36. package/dist/dashboard/i18n/fi.json +9 -0
  37. package/dist/dashboard/i18n/fr.json +9 -0
  38. package/dist/dashboard/i18n/he.json +9 -0
  39. package/dist/dashboard/i18n/hi.json +9 -0
  40. package/dist/dashboard/i18n/hu.json +9 -0
  41. package/dist/dashboard/i18n/is.json +9 -0
  42. package/dist/dashboard/i18n/it.json +9 -0
  43. package/dist/dashboard/i18n/ja.json +9 -0
  44. package/dist/dashboard/i18n/ko.json +9 -0
  45. package/dist/dashboard/i18n/nb.json +9 -0
  46. package/dist/dashboard/i18n/nl.json +9 -0
  47. package/dist/dashboard/i18n/pl.json +9 -0
  48. package/dist/dashboard/i18n/pt.json +9 -0
  49. package/dist/dashboard/i18n/ro.json +9 -0
  50. package/dist/dashboard/i18n/ru.json +9 -0
  51. package/dist/dashboard/i18n/sv.json +9 -0
  52. package/dist/dashboard/i18n/tr.json +9 -0
  53. package/dist/dashboard/i18n/uk.json +9 -0
  54. package/dist/dashboard/i18n/zh.json +9 -0
  55. package/dist/dashboard/pack-card.js +92 -0
  56. package/dist/dashboard/packages.js +11 -4
  57. package/dist/dashboard/rolls.js +2 -2
  58. package/dist/dashboard/style.css +521 -3
  59. package/dist/dashboard-server.js +57 -1
  60. package/dist/extensions/api.d.ts +148 -17
  61. package/dist/extensions/extension.d.ts +10 -3
  62. package/dist/extensions/extension.js +16 -3
  63. package/dist/extensions/index.d.ts +3 -3
  64. package/dist/extensions/index.js +2 -2
  65. package/dist/extensions/packages.d.ts +8 -0
  66. package/dist/extensions/packages.js +48 -1
  67. package/dist/extensions/words.d.ts +2 -1
  68. package/dist/extensions/words.js +5 -4
  69. package/dist/index.d.ts +1 -1
  70. package/dist/mcp-server.js +1 -1
  71. package/dist/pages/index.d.ts +1 -1
  72. package/dist/pages/index.js +1 -1
  73. package/dist/pages/standard-fields.d.ts +2 -0
  74. package/dist/pages/standard-fields.js +8 -1
  75. package/dist/systems/game-system.d.ts +14 -9
  76. package/dist/systems/game-system.js +29 -19
  77. package/dist/systems/index.d.ts +1 -1
  78. package/dist/testing.d.ts +61 -0
  79. package/dist/testing.js +162 -0
  80. package/package.json +7 -2
@@ -13,9 +13,11 @@ export interface ExtensionCode {
13
13
  timePassed?(passage: TimePassage, game: Game): string[] | Promise<string[]>;
14
14
  /**
15
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.
16
+ * shows for undefined. Read as the card of a question, it is given the card's key, the attempt to show (D-507).
17
17
  */
18
- widgets?: Record<string, (game: GameView) => Widget | undefined | Promise<Widget | undefined>>;
18
+ widgets?: Record<string, (game: GameView, card?: {
19
+ key: string;
20
+ }) => Widget | undefined | Promise<Widget | undefined>>;
19
21
  }
20
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). */
21
23
  export interface ExtensionCommand<Input extends z.ZodObject = z.ZodObject> {
@@ -27,6 +29,11 @@ export interface ExtensionCommand<Input extends z.ZodObject = z.ZodObject> {
27
29
  readOnly?: boolean;
28
30
  /** Fields the command line takes as positional arguments, in order: weather-set 2. */
29
31
  positionals?: string[];
32
+ /**
33
+ * 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
+ * stays on the command line and where nothing shows buttons, where ask gives the question in words.
35
+ */
36
+ needsPlayer?: boolean;
30
37
  /** The text the master reads; an error thrown says what went wrong and how to fix it. */
31
38
  run(input: z.infer<Input>, game: Game): string | Promise<string>;
32
39
  }
@@ -49,7 +56,7 @@ export interface TimePassage {
49
56
  from: GameMoment;
50
57
  to: GameMoment;
51
58
  }
52
- /** The campaign as a widget reads it (D-502): what the code's commands reach, without the dice, the log or writing. */
59
+ /** The campaign as a widget reads it (D-502): what the code's commands reach, without the dice, the log, asking or writing. */
53
60
  export interface GameView {
54
61
  /** Now, in the game; undefined before the game has a date. */
55
62
  now(): GameMoment | undefined;
@@ -57,24 +64,69 @@ export interface GameView {
57
64
  calendarDay(day: number): CalendarDay | undefined;
58
65
  /** The units of measure the campaign tells the story in. */
59
66
  units(): "metric" | "imperial";
60
- /** Where the party is: the first living player character's places, in the order of the pages, the nearest first, and what holds there by the places' environment, such as biome: desert. */
67
+ /**
68
+ * Where the party is: the first living player character's places, in the order of the pages, the nearest first, and what holds there by the places'
69
+ * environment, such as biome: desert; and its living members, in the order of the pages (D-505).
70
+ */
61
71
  party(): {
62
72
  places: string[];
63
73
  environment: Record<string, string>;
74
+ members: {
75
+ name: string;
76
+ pc: boolean;
77
+ }[];
78
+ } | undefined;
79
+ /** A page by its name or alias (D-505); undefined when no page, or more than one, has it. */
80
+ page(name: string): GamePage | undefined;
81
+ /** The open scene: its title, when it opened, and in a fight its round and whose turn it is (D-505); undefined when none is open. */
82
+ scene(): {
83
+ title: string;
84
+ opened?: string;
85
+ round?: number;
86
+ turn?: string;
64
87
  } | undefined;
65
88
  /** The extension's own state, kept in the campaign. */
66
89
  state: {
67
90
  read(): unknown;
68
91
  };
69
92
  }
70
- /** The campaign as an extension's code reaches it: only through these, and only its own state is written (D-428, D-436). */
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. */
94
+ export interface GamePage {
95
+ name: string;
96
+ /** The player's character. */
97
+ pc: boolean;
98
+ /** The player's character or a companion. */
99
+ party: boolean;
100
+ /** A field: a number, text, or a list as text; a counter as written, such as 3/5; undefined when the page has none. */
101
+ value(field: string): number | string | string[] | undefined;
102
+ /** A counter, with its maximum when it has one. */
103
+ counter(field: string): {
104
+ value: number;
105
+ max?: number;
106
+ } | undefined;
107
+ /** Whether an effect is on it, such as a condition. */
108
+ has(effect: string): boolean;
109
+ /** 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
+ formula(text: string): number | undefined;
111
+ }
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). */
71
113
  export interface Game extends GameView {
72
- /** Rolls with the engine's dice, as 1d6 or 4d6kh3: the total, each die's face, and the roll as one line. */
73
- roll(notation: string): {
74
- total: number;
75
- faces: number[];
76
- text: string;
77
- };
114
+ /**
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.
117
+ */
118
+ roll(notation: string, by?: RollFor): Rolled;
119
+ /**
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.
122
+ */
123
+ set(page: string, values: Record<string, number | string>, why: string): void;
124
+ /**
125
+ * 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
+ * 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,
127
+ * else once they go ahead the code rolls them with roll and who, as the core's ask leaves to the master's roll.
128
+ */
129
+ ask(asked: AskedRoll): Promise<Asked>;
78
130
  state: {
79
131
  read(): unknown;
80
132
  write(value: unknown): void;
@@ -82,6 +134,74 @@ export interface Game extends GameView {
82
134
  /** A line in the campaign's log: public when the player may see it, hidden when only the master may. */
83
135
  log(text: string, visibility?: "public" | "hidden"): void;
84
136
  }
137
+ /** Whom a roll is for (D-505): who rolls, why, as the master reads it, what the player sees it as, and the faces of physical dice. */
138
+ export interface RollFor {
139
+ who: string;
140
+ why: string;
141
+ check?: string;
142
+ 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. */
144
+ says?: (faces: number[]) => WidgetText;
145
+ /** 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
+ tones?: (faces: number[]) => (DieTone | undefined)[];
147
+ }
148
+ /** 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
+ 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. */
151
+ export type ButtonWords = WidgetText | {
152
+ label: WidgetText;
153
+ note: WidgetText;
154
+ };
155
+ /**
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.
158
+ */
159
+ export interface AskedRoll {
160
+ who?: string;
161
+ question: WidgetText;
162
+ check: string;
163
+ notation: string;
164
+ /** The roll's button, in place of the core's "Roll: check (dice)". */
165
+ roll?: ButtonWords;
166
+ /** The button that turns it down, renamed; false for none, when the roll is forced, as a death save (D-507). */
167
+ decline?: ButtonWords | false;
168
+ /** The rule under the buttons, in a line, as "A 1 resets the lock". */
169
+ rule?: WidgetText;
170
+ /**
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.
173
+ */
174
+ card?: {
175
+ widget: string;
176
+ key: string;
177
+ };
178
+ says?: (faces: number[]) => WidgetText;
179
+ tones?: (faces: number[]) => (DieTone | undefined)[];
180
+ }
181
+ /** A roll made: with by, the id of its line in the log and whether it was hidden behind the screen. */
182
+ export interface Rolled {
183
+ total: number;
184
+ faces: number[];
185
+ text: string;
186
+ id?: string;
187
+ hidden?: boolean;
188
+ }
189
+ /** What the player answered when asked for a roll (D-505). */
190
+ export type Asked = {
191
+ rolled: {
192
+ id: string;
193
+ total: number;
194
+ faces: number[];
195
+ text: string;
196
+ };
197
+ } | {
198
+ declined: true;
199
+ } | {
200
+ said: string;
201
+ } | {
202
+ inWords: string;
203
+ physical: boolean;
204
+ };
85
205
  /**
86
206
  * What a widget shows now (D-502), in the dashboard's own parts: in the top, its icon and its chip, what it says whole in the chip's tip; in a card, under the
87
207
  * widget's title, its note and its parts. The server checks it, and keeps it short.
@@ -114,6 +234,21 @@ export type WidgetValue = number | string | {
114
234
  to: number;
115
235
  unit?: string;
116
236
  };
237
+ /**
238
+ * A count, as pips, a bar, or steps of a progress (D-507): its value lit; after them, those held but not yet sure, those marked, as a die that failed, and
239
+ * those the roll asked may light; in an ask's card, where it stands, and whether it is good or bad to have.
240
+ */
241
+ export interface Track {
242
+ label: WidgetText;
243
+ value: number;
244
+ max: number;
245
+ look?: "pips" | "bar" | "steps";
246
+ held?: number;
247
+ marked?: number;
248
+ coming?: number;
249
+ stage?: "start" | "center" | "end";
250
+ tone?: DieTone;
251
+ }
117
252
  /**
118
253
  * 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
119
254
  * bar; rows of a label, a value and a note; a table; a picture of the extension's images/.
@@ -122,6 +257,7 @@ export type WidgetPart = {
122
257
  lead: WidgetText;
123
258
  icon?: string;
124
259
  value?: WidgetValue;
260
+ tone?: DieTone;
125
261
  } | {
126
262
  text: WidgetText;
127
263
  } | {
@@ -132,12 +268,7 @@ export type WidgetPart = {
132
268
  value: WidgetValue;
133
269
  }[];
134
270
  } | {
135
- track: {
136
- label: WidgetText;
137
- value: number;
138
- max: number;
139
- look?: "pips" | "bar";
140
- };
271
+ track: Track;
141
272
  } | {
142
273
  rows: {
143
274
  label: WidgetText;
@@ -2,10 +2,15 @@ import { type InstructionPart } from "../core/instruction-parts.ts";
2
2
  /** The file that makes a folder an extension of rpg-engine (D-427). */
3
3
  export declare const extensionFileName = "extension.yaml";
4
4
  /**
5
- * The version of the API an extension's code is given (api.ts), which its package.json names: 2 added the widgets (D-502). A package made for this one or an
6
- * older one is read; one made for a newer one is refused, as an older rpg-engine refuses this one's.
5
+ * The version of the API an extension's code is given (api.ts), which its package.json names: 2 added the widgets (D-502), 3 its additions to the game system,
6
+ * the pages, the scene, writing its own fields and asking the player (D-505). A package made for this one or an older one is read; one made for a newer one is
7
+ * refused, as an older rpg-engine refuses this one's.
7
8
  */
8
- export declare const extensionApi = 2;
9
+ export declare const extensionApi = 3;
10
+ /** What an extension may add to the campaign's game system in extension.yaml, written as campaign.yaml writes it (CAM-2, D-505). */
11
+ export declare const systemAdditionNames: readonly ["fields", "tables", "computed", "counters", "recipes", "values"];
12
+ /** What an extension adds to the game system, by key, as extension.yaml writes it: the system checks it when it is read with it (CAM-3). */
13
+ export type SystemAdditions = Partial<Record<(typeof systemAdditionNames)[number], Record<string, unknown>>>;
9
14
  /** Whether this rpg-engine reads a package made for this version of the API: from 1 up to its own. */
10
15
  export declare function readsApi(api: number | undefined): boolean;
11
16
  /** An installed extension (D-28, D-427, D-428): an npm package with an extension.yaml, its parts of the instructions and, when it has some, its code. */
@@ -28,6 +33,8 @@ export interface Extension {
28
33
  };
29
34
  /** Its months in place of the core's, as extension.yaml writes them: the time module reads them (TIM-8). */
30
35
  calendar?: unknown;
36
+ /** What it adds to the game system, under the campaign's own additions (CAM-2). */
37
+ adds: SystemAdditions;
31
38
  /** Its icons by name, each the path of an SVG drawn on 24 by 24, as the dashboard strokes it (D-502). */
32
39
  icons: Record<string, string>;
33
40
  /** Its widgets on the dashboard, in the order written, each where it puts itself (D-502). */
@@ -12,10 +12,13 @@ export const extensionFileName = "extension.yaml";
12
12
  const aboutWords = 40;
13
13
  const partWords = 400;
14
14
  /**
15
- * The version of the API an extension's code is given (api.ts), which its package.json names: 2 added the widgets (D-502). A package made for this one or an
16
- * older one is read; one made for a newer one is refused, as an older rpg-engine refuses this one's.
15
+ * The version of the API an extension's code is given (api.ts), which its package.json names: 2 added the widgets (D-502), 3 its additions to the game system,
16
+ * the pages, the scene, writing its own fields and asking the player (D-505). A package made for this one or an older one is read; one made for a newer one is
17
+ * refused, as an older rpg-engine refuses this one's.
17
18
  */
18
- export const extensionApi = 2;
19
+ export const extensionApi = 3;
20
+ /** What an extension may add to the campaign's game system in extension.yaml, written as campaign.yaml writes it (CAM-2, D-505). */
21
+ export const systemAdditionNames = ["fields", "tables", "computed", "counters", "recipes", "values"];
19
22
  /** Whether this rpg-engine reads a package made for this version of the API: from 1 up to its own. */
20
23
  export function readsApi(api) {
21
24
  return api !== undefined && Number.isInteger(api) && api >= 1 && api <= extensionApi;
@@ -39,6 +42,8 @@ const widgetSchema = z.object({
39
42
  }).strict().refine((widget) => (widget.place === "page") === (widget.page !== undefined), {
40
43
  error: "a widget in place page names its page (scene, sheet, world or journal), and only one in a page does",
41
44
  });
45
+ /** An addition to the game system, which the system checks as it reads it (CAM-3). */
46
+ const addition = z.record(z.string(), z.unknown(), { error: "give it as a map by name, as campaign.yaml does" }).optional();
42
47
  const extensionSchema = z.object({
43
48
  title: z.string().trim().min(1),
44
49
  about: z.string().trim().min(1),
@@ -48,6 +53,12 @@ const extensionSchema = z.object({
48
53
  calendar: z.unknown().optional(),
49
54
  icons: z.record(ownName, z.string().max(longestPath).regex(/^[MmLlHhVvCcSsQqTtAaZz\d\s,.+-]+$/, "an icon is the path of an SVG, as M4 12h16")).optional(),
50
55
  widgets: z.record(ownName, widgetSchema).optional(),
56
+ fields: addition,
57
+ tables: addition,
58
+ computed: addition,
59
+ counters: addition,
60
+ recipes: addition,
61
+ values: addition,
51
62
  }).strict().superRefine((declared, check) => {
52
63
  const icons = Object.keys(declared.icons ?? {});
53
64
  const widgets = Object.entries(declared.widgets ?? {});
@@ -100,6 +111,7 @@ export function readExtension(folder) {
100
111
  throw new Error(`${owner} cannot be read, because its ${extensionFileName} is not valid: ${z.prettifyError(declared.error).replace(/\s+/g, " ")}`);
101
112
  }
102
113
  const { title, about, language, attribution, needs, calendar, icons, widgets } = declared.data;
114
+ const adds = Object.fromEntries(systemAdditionNames.flatMap((key) => (declared.data[key] === undefined ? [] : [[key, declared.data[key]]])));
103
115
  const parts = readParts(folder, owner);
104
116
  // What the master reads of it in every chat, kept short (D-441).
105
117
  const long = [["about", about, aboutWords], ...Object.entries(parts).map(([name, part]) => [`instructions/${name}.md`, part.text, partWords])]
@@ -118,6 +130,7 @@ export function readExtension(folder) {
118
130
  ...(attribution === undefined ? {} : { attribution }),
119
131
  needs: needs ?? {},
120
132
  ...(calendar === undefined ? {} : { calendar }),
133
+ adds,
121
134
  icons: icons ?? {},
122
135
  widgets: Object.entries(widgets ?? {}).map(([name, widget]) => ({ name, ...widget, order: widget.order ?? 0 })),
123
136
  parts,
@@ -1,5 +1,5 @@
1
- export type { CalendarDay, ExtensionCode, ExtensionCommand, ExtensionEntry, ExtensionKit, Game, GameMoment, GameView, TimePassage, Widget, WidgetPart, WidgetText, WidgetValue } from "./api.ts";
2
- export { type DeclaredWidget, type Extension, extensionApi, extensionFileName, findExtension, installedExtensions, readExtension, readsApi, shortName, type WidgetPage, widgetPages, type WidgetPlace, widgetPlaces } from "./extension.ts";
3
- export { isLocalSpec, isVerified, npmPackages, packageKeyword, verifiedScope } from "./packages.ts";
1
+ export type { Asked, AskedRoll, ButtonWords, CalendarDay, DieTone, ExtensionCode, ExtensionCommand, ExtensionEntry, ExtensionKit, Game, GameMoment, GamePage, GameView, Rolled, RollFor, TimePassage, Track, Widget, WidgetPart, WidgetText, WidgetValue, } from "./api.ts";
2
+ export { type DeclaredWidget, type Extension, extensionApi, extensionFileName, findExtension, installedExtensions, readExtension, readsApi, shortName, systemAdditionNames, type SystemAdditions, type WidgetPage, widgetPages, type WidgetPlace, widgetPlaces, } from "./extension.ts";
3
+ export { isLocalSpec, issuesPage, isVerified, npmPackages, packageKeyword, verifiedScope } from "./packages.ts";
4
4
  export { isTarball } from "./tarball.ts";
5
5
  export { type ExtensionWords, extensionWords, wordIn } from "./words.ts";
@@ -1,4 +1,4 @@
1
- export { extensionApi, extensionFileName, findExtension, installedExtensions, readExtension, readsApi, shortName, widgetPages, widgetPlaces } from "./extension.js";
2
- export { isLocalSpec, isVerified, npmPackages, packageKeyword, verifiedScope } from "./packages.js";
1
+ export { extensionApi, extensionFileName, findExtension, installedExtensions, readExtension, readsApi, shortName, systemAdditionNames, widgetPages, widgetPlaces, } from "./extension.js";
2
+ export { isLocalSpec, issuesPage, isVerified, npmPackages, packageKeyword, verifiedScope } from "./packages.js";
3
3
  export { isTarball } from "./tarball.js";
4
4
  export { extensionWords, wordIn } from "./words.js";
@@ -18,3 +18,11 @@ export declare function npmPackages(folder: string, run?: (args: string) => Prom
18
18
  export declare function isLocalSpec(spec: string): boolean;
19
19
  /** Whether an installed package is ours, verified: in our scope and installed from npm, never from a folder, which anyone can name so (D-428, D-441). */
20
20
  export declare function isVerified(name: string, linked: boolean): boolean;
21
+ /**
22
+ * Where a package takes reports of its problems, by its package.json: its `bugs` page, else the issues of its repository on GitHub; undefined when it says
23
+ * neither, or not over https.
24
+ */
25
+ export declare function issuesPage(manifest: {
26
+ bugs?: unknown;
27
+ repository?: unknown;
28
+ }): string | undefined;
@@ -80,6 +80,35 @@ export function isLocalSpec(spec) {
80
80
  export function isVerified(name, linked) {
81
81
  return name.startsWith(verifiedScope) && !linked;
82
82
  }
83
+ /**
84
+ * Where a package takes reports of its problems, by its package.json: its `bugs` page, else the issues of its repository on GitHub; undefined when it says
85
+ * neither, or not over https.
86
+ */
87
+ export function issuesPage(manifest) {
88
+ const bugs = httpsLink(typeof manifest.bugs === "string" ? manifest.bugs : fieldOf(manifest.bugs, "url"));
89
+ if (bugs !== undefined) {
90
+ return bugs;
91
+ }
92
+ const repository = typeof manifest.repository === "string" ? manifest.repository : fieldOf(manifest.repository, "url");
93
+ const github = repository === undefined ? null : githubRepository.exec(repository.trim());
94
+ return github === null ? undefined : `https://github.com/${github[1]}/${github[2]}/issues`;
95
+ }
96
+ // A repository on GitHub as package.json may write it: a git, https or ssh address, github:owner/name, or owner/name alone, which npm reads as GitHub's.
97
+ const githubRepository = /^(?:(?:git\+)?(?:https?|git|ssh):\/\/(?:[^@/]+@)?github\.com[/:]|git@github\.com:|github:)?([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?(?:#.*)?$/i;
98
+ /** A field of an object read from JSON, when it is a string. */
99
+ function fieldOf(value, field) {
100
+ const read = typeof value === "object" && value !== null ? value[field] : undefined;
101
+ return typeof read === "string" ? read : undefined;
102
+ }
103
+ /** A link over https, as a page may open it; undefined for anything else. */
104
+ function httpsLink(text) {
105
+ try {
106
+ return text !== undefined && new URL(text).protocol === "https:" ? new URL(text).href : undefined;
107
+ }
108
+ catch {
109
+ return undefined;
110
+ }
111
+ }
83
112
  /** What npm's registry says of a package, at a version or its latest, with what its package.json says for rpg-engine. */
84
113
  async function registryPackage(spec) {
85
114
  const checked = checkedSpec(spec);
@@ -156,7 +185,11 @@ async function installCopy(folder, spec, expected, run) {
156
185
  renameSync(target, before);
157
186
  }
158
187
  renameSync(staged, target);
159
- const ran = await run(`install --prefix ${quotedFolder(folder)} ${quotedFolder(target)} ${installOptions}`);
188
+ // npm keeps what it installed of the same version, so the copy it installed goes aside first: what runs is the one just given.
189
+ const installed = join(folder, "node_modules", read.name);
190
+ const aside = `${target}.installed`;
191
+ rmSync(aside, { recursive: true, force: true });
192
+ const ran = await installedAside(installed, aside, () => run(`install --prefix ${quotedFolder(folder)} ${quotedFolder(target)} ${installOptions}`));
160
193
  if (ran.code === 0) {
161
194
  rmSync(before, { recursive: true, force: true });
162
195
  return undefined;
@@ -167,6 +200,20 @@ async function installCopy(folder, spec, expected, run) {
167
200
  }
168
201
  return `npm said: ${npmError(ran)}`;
169
202
  }
203
+ /** Runs npm with what it installed moved aside, taken away when npm succeeds and put back when it fails. */
204
+ async function installedAside(installed, aside, install) {
205
+ const moved = existsSync(installed);
206
+ if (moved) {
207
+ renameSync(installed, aside);
208
+ }
209
+ const ran = await install();
210
+ if (moved && ran.code !== 0) {
211
+ rmSync(installed, { recursive: true, force: true });
212
+ renameSync(aside, installed);
213
+ }
214
+ rmSync(aside, { recursive: true, force: true });
215
+ return ran;
216
+ }
170
217
  function infoOf(read) {
171
218
  const marker = read["rpg-engine"];
172
219
  return {
@@ -1,7 +1,8 @@
1
- /** An extension's words in one language: its title and about, and its other words and phrases by the text its code writes. */
1
+ /** An extension's words in one language: its title and about, the names of the fields it adds to the game system, and its other words and phrases by the text its code writes. */
2
2
  export interface ExtensionWords {
3
3
  title?: string;
4
4
  about?: string;
5
+ fields?: Record<string, string>;
5
6
  words: Record<string, string>;
6
7
  }
7
8
  /** The words of the extension in this folder for a language, or for its base language (pt for pt-BR); undefined when it has none in it. It throws when they do not read. */
@@ -1,5 +1,5 @@
1
1
  // An extension's words in the languages it ships (D-502): beside its extension.yaml, words/<code>.yaml gives its title and its line in the Packages page, and
2
- // any word or phrase its widgets write, by the English as its code writes it. The core hands them on: a word the list lacks stays as written.
2
+ // the names of the fields it adds to the game system, and any word or phrase its widgets write, by the English as its code writes it. The core hands them on: a word the list lacks stays as written.
3
3
  import { join } from "node:path";
4
4
  import { z } from "zod";
5
5
  import { files } from "../core/store.js";
@@ -7,8 +7,9 @@ import { readYamlValues } from "../core/yaml-file.js";
7
7
  const wordsSchema = z.object({
8
8
  title: z.string().trim().min(1).optional(),
9
9
  about: z.string().trim().min(1).optional(),
10
+ fields: z.record(z.string().min(1), z.string().min(1)).optional(),
10
11
  words: z.record(z.string().min(1), z.string().min(1)).optional(),
11
- }, { error: "write its title, its about and its words, each word from the text the code writes to the language's own, such as {words: {Weather: Meteo}}" }).strict();
12
+ }, { error: "write its title, its about, the names of its fields and its words, each from the text the code writes to the language's own, such as {words: {Weather: Meteo}}" }).strict();
12
13
  /** The words of the extension in this folder for a language, or for its base language (pt for pt-BR); undefined when it has none in it. It throws when they do not read. */
13
14
  export function extensionWords(folder, language) {
14
15
  const file = [language, language.split("-")[0]].map((code) => join(folder, "words", `${code.toLowerCase()}.yaml`)).find((path) => files().exists(path));
@@ -19,8 +20,8 @@ export function extensionWords(folder, language) {
19
20
  if (!parsed.success) {
20
21
  throw new Error(`The words of the extension in ${file} cannot be read: ${parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}. Fix the file.`);
21
22
  }
22
- const { title, about, words = {} } = parsed.data;
23
- return { ...(title === undefined ? {} : { title }), ...(about === undefined ? {} : { about }), words };
23
+ const { title, about, fields, words = {} } = parsed.data;
24
+ return { ...(title === undefined ? {} : { title }), ...(about === undefined ? {} : { about }), ...(fields === undefined ? {} : { fields }), words };
24
25
  }
25
26
  /**
26
27
  * A text in the words' language: the whole text as the list gives it, else with its first letter's case aside, the translation's first letter taken to the
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
1
  export { getVersion } from "./core/version.ts";
2
2
  export type { SaveAsked } from "./core/context.ts";
3
- export type { CalendarDay, ExtensionCode, ExtensionCommand, ExtensionEntry, ExtensionKit, Game, GameMoment, GameView, TimePassage, Widget, WidgetPart, WidgetText, WidgetValue } from "./extensions/index.ts";
3
+ export type { Asked, AskedRoll, ButtonWords, CalendarDay, DieTone, ExtensionCode, ExtensionCommand, ExtensionEntry, ExtensionKit, Game, GameMoment, GamePage, GameView, Rolled, RollFor, TimePassage, Track, Widget, WidgetPart, WidgetText, WidgetValue, } from "./extensions/index.ts";
4
4
  export type { CounterChange, RollMade, SystemEntry, SystemGame, SystemHooks, SystemPage, SystemReader } from "./systems/index.ts";
@@ -243,7 +243,7 @@ function inputIssue(tool, issue, given) {
243
243
  return path === "" ? `${issue.message}.` : `${path}: ${issue.message}.`;
244
244
  }
245
245
  async function runTool(command, input, context, extra, prepare, outside) {
246
- const keepAlive = command.needsPlayer
246
+ const keepAlive = command.needsPlayer || command.waitsForPlayer
247
247
  ? reportProgress(extra, () => (context.page?.asking?.() === true ? "waiting for the player's click on the dashboard" : "waiting for the player"))
248
248
  : command.slow === true
249
249
  ? reportProgress(extra, () => "still working")
@@ -12,7 +12,7 @@ export { applyRename, planRename, type Renamed, renamedLinks, type RenamePlan }
12
12
  export { readStops, type Stops, stopsHelp } from "./roads.ts";
13
13
  export { countedText, entryOfKind, type EntryReading, isStackEntry, readEntry, stackEntry, withStackCount } from "./stack-entry.ts";
14
14
  export { canCount, carriesKind, entryKind, entryPage, goodsNamed, type HeldStack, heldStacks, heldStacksOfKind, isKind, kindNamed, notKindReason, ownStack, type Stack, stackName, stacksOf } from "./stacks.ts";
15
- export { canHold, containerFieldOf, containerFields, heldTypesText, isCounterField, isEmptyField, isFieldName, isStandardField, listFieldNames, misspelledFieldProblem, misspelledStandardField, newPageFields, standardValues, } from "./standard-fields.ts";
15
+ export { canHold, containerFieldOf, containerFields, heldTypesText, isCoreField, isCounterField, isEmptyField, isFieldName, isStandardField, listFieldNames, misspelledFieldProblem, misspelledStandardField, newPageFields, standardValues, } from "./standard-fields.ts";
16
16
  export { alwaysInList, alwaysInMessage, declaredKind, heldSystemPageMessage, hidingMessage, isDeclaredUncounted, kindMessage, readOnlyMessage, systemKnowsReason, systemLabel } from "./system-pages.ts";
17
17
  export { type Backlink, backlinks, bonusPages, concernsPlayer, createWorld, findPage, heldNames, isCountedItem, isInParty, isPartyMember, isPlayerCharacter, linksIn, loadWorld, locate, namesakes, type Page, pageFileNamed, type PageMatch, pageNamed, pagesWithName, pagesWithNameOrAlias, pageWithPath, parsePageReference, playerCharacters, searchPages, searchSystemPages, systemFirstFix, type SystemInfo, systemPageNamed, type SystemPages, textsIn, validHoldersOf, withPage, type World, } from "./world.ts";
18
18
  export { checkFieldChange, type PageChange, writePage } from "./write-page.ts";
@@ -13,7 +13,7 @@ export { applyRename, planRename, renamedLinks } from "./rename-page.js";
13
13
  export { readStops, stopsHelp } from "./roads.js";
14
14
  export { countedText, entryOfKind, isStackEntry, readEntry, stackEntry, withStackCount } from "./stack-entry.js";
15
15
  export { canCount, carriesKind, entryKind, entryPage, goodsNamed, heldStacks, heldStacksOfKind, isKind, kindNamed, notKindReason, ownStack, stackName, stacksOf } from "./stacks.js";
16
- export { canHold, containerFieldOf, containerFields, heldTypesText, isCounterField, isEmptyField, isFieldName, isStandardField, listFieldNames, misspelledFieldProblem, misspelledStandardField, newPageFields, standardValues, } from "./standard-fields.js";
16
+ export { canHold, containerFieldOf, containerFields, heldTypesText, isCoreField, isCounterField, isEmptyField, isFieldName, isStandardField, listFieldNames, misspelledFieldProblem, misspelledStandardField, newPageFields, standardValues, } from "./standard-fields.js";
17
17
  export { alwaysInList, alwaysInMessage, declaredKind, heldSystemPageMessage, hidingMessage, isDeclaredUncounted, kindMessage, readOnlyMessage, systemKnowsReason, systemLabel } from "./system-pages.js";
18
18
  export { backlinks, bonusPages, concernsPlayer, createWorld, findPage, heldNames, isCountedItem, isInParty, isPartyMember, isPlayerCharacter, linksIn, loadWorld, locate, namesakes, pageFileNamed, pageNamed, pagesWithName, pagesWithNameOrAlias, pageWithPath, parsePageReference, playerCharacters, searchPages, searchSystemPages, systemFirstFix, systemPageNamed, textsIn, validHoldersOf, withPage, } from "./world.js";
19
19
  export { checkFieldChange, writePage } from "./write-page.js";
@@ -15,6 +15,8 @@ export declare function isFieldName(name: string): boolean;
15
15
  export declare const listFieldNames: string[];
16
16
  /** Whether a field has a fixed meaning on pages of this type, such as an event's date: such a field is never a counter, but for an event's clock. */
17
17
  export declare function isStandardField(type: PageType | undefined, name: string): boolean;
18
+ /** Whether the core itself reads a field on some page, as role, status or contains: an extension's field never takes its name (D-505). */
19
+ export declare function isCoreField(name: string): boolean;
18
20
  /** Whether a standard field is a counter, changed with change like any other: an event's clock (EVT-2). */
19
21
  export declare function isCounterField(type: PageType | undefined, name: string): boolean;
20
22
  /** The values a standard field takes on pages of a type, such as a quest's statuses; undefined when it takes any. */
@@ -1,6 +1,6 @@
1
1
  import { readLength } from "../core/length.js";
2
2
  import { moods } from "../core/mood.js";
3
- import { sameName } from "../core/text.js";
3
+ import { comparableText, sameName } from "../core/text.js";
4
4
  import { mapHelp, readMapField } from "./maps.js";
5
5
  import { positionHelp, readPosition } from "./positions.js";
6
6
  import { readStops } from "./roads.js";
@@ -54,6 +54,13 @@ export const listFieldNames = [
54
54
  export function isStandardField(type, name) {
55
55
  return Object.hasOwn(commonRules, name) || (type !== undefined && Object.hasOwn(typeRules[type] ?? {}, name));
56
56
  }
57
+ // The other fields the core reads on pages: effects, a page's kind, a quest's deadline and clock, a vehicle's riders and how long it travelled, who is hostile.
58
+ const otherCoreFields = ["effects", "kind", "deadline", "clock-name", "riders", "travelled", "hostile", "type", "title"];
59
+ /** Whether the core itself reads a field on some page, as role, status or contains: an extension's field never takes its name (D-505). */
60
+ export function isCoreField(name) {
61
+ const key = comparableText(name);
62
+ return [...Object.keys(commonRules), ...Object.values(typeRules).flatMap((rules) => Object.keys(rules ?? {})), ...otherCoreFields].some((field) => comparableText(field) === key);
63
+ }
57
64
  /** Whether a standard field is a counter, changed with change like any other: an event's clock (EVT-2). */
58
65
  export function isCounterField(type, name) {
59
66
  const rules = rulesOf(type);
@@ -374,16 +374,21 @@ export declare function installedSystems(folders: string[]): GameSystem[];
374
374
  export declare const campaignDataNames: readonly ["fields", "tables", "computed", "counters", "recipes", "status-line", "travel", "values"];
375
375
  /** What campaign.yaml adds to the game system, as it writes it: checked when the system is read with it (CAM-3). */
376
376
  export type CampaignData = Partial<Record<(typeof campaignDataNames)[number], unknown>>;
377
+ /** What an extension or the campaign adds to the game system (CAM-1, CAM-2): from where, as messages name it, and what. */
378
+ export interface SystemLayer {
379
+ from: string;
380
+ data: CampaignData;
381
+ }
377
382
  /**
378
- * The installed system with what the campaign adds to it, the nearest layer winning (CAM-2); when the additions do not read, the system alone and why (CAM-3).
379
- * Undefined as a system when none is installed by that name.
383
+ * The installed system with the layers over it, in order, the nearest to the campaign last and winning (CAM-2); a layer with which it does not read is left out,
384
+ * with why, and the others stay (CAM-3). Undefined as a system when none is installed by that name.
380
385
  */
381
- export declare function findCampaignSystem(folders: string[], name: string, data: CampaignData): {
386
+ export declare function findCampaignSystem(folders: string[], name: string, layers: SystemLayer[]): {
382
387
  system?: GameSystem;
383
- problem?: string;
388
+ refused: {
389
+ from: string;
390
+ problem: string;
391
+ }[];
384
392
  };
385
- /**
386
- * The installed system with this name, ignoring case, from the nearest folder that has it, with what a campaign adds to it; undefined when none is. Only its own
387
- * system.yaml is read.
388
- */
389
- export declare function findSystem(folders: string[], name: string, data?: CampaignData): GameSystem | undefined;
393
+ /** The installed system with this name, ignoring case, from the nearest folder that has it; undefined when none is. Only its own system.yaml is read. */
394
+ export declare function findSystem(folders: string[], name: string): GameSystem | undefined;
@@ -268,37 +268,47 @@ export function installedSystems(folders) {
268
268
  /** What a campaign may add to its game system in campaign.yaml (CAM-1): its own fields, tables, formulas, counters, recipes, line of the player character and travel. */
269
269
  export const campaignDataNames = ["fields", "tables", "computed", "counters", "recipes", "status-line", "travel", "values"];
270
270
  /**
271
- * The installed system with what the campaign adds to it, the nearest layer winning (CAM-2); when the additions do not read, the system alone and why (CAM-3).
272
- * Undefined as a system when none is installed by that name.
271
+ * The installed system with the layers over it, in order, the nearest to the campaign last and winning (CAM-2); a layer with which it does not read is left out,
272
+ * with why, and the others stay (CAM-3). Undefined as a system when none is installed by that name.
273
273
  */
274
- export function findCampaignSystem(folders, name, data) {
275
- const system = findSystem(folders, name);
276
- if (system === undefined || campaignDataNames.every((key) => data[key] === undefined || data[key] === null)) {
277
- return { system };
274
+ export function findCampaignSystem(folders, name, layers) {
275
+ const found = systemFolders(folders).find((candidate) => comparableText(candidate.name) === comparableText(name.trim()));
276
+ const given = layers.filter((layer) => campaignDataNames.some((key) => layer.data[key] !== undefined && layer.data[key] !== null));
277
+ if (found === undefined) {
278
+ return { refused: [] };
278
279
  }
279
280
  try {
280
- return { system: findSystem(folders, name, data) };
281
+ return { system: readSystem(found.folder, found.name, given), refused: [] };
281
282
  }
282
- catch (error) {
283
- const message = error instanceof Error ? error.message : String(error);
284
- return { system, problem: message.replace(/^The game system .*? cannot be read, because .*? is not valid:\s*/s, "") };
283
+ catch {
284
+ // One layer at a time, to leave out only those that do not read.
285
285
  }
286
+ const kept = [];
287
+ const refused = [];
288
+ for (const layer of given) {
289
+ try {
290
+ readSystem(found.folder, found.name, [...kept, layer]);
291
+ kept.push(layer);
292
+ }
293
+ catch (error) {
294
+ const message = error instanceof Error ? error.message : String(error);
295
+ refused.push({ from: layer.from, problem: message.replace(/^The game system .*? cannot be read, because .*? is not valid:\s*/s, "") });
296
+ }
297
+ }
298
+ return { system: readSystem(found.folder, found.name, kept), refused };
286
299
  }
287
- /**
288
- * The installed system with this name, ignoring case, from the nearest folder that has it, with what a campaign adds to it; undefined when none is. Only its own
289
- * system.yaml is read.
290
- */
291
- export function findSystem(folders, name, data) {
300
+ /** The installed system with this name, ignoring case, from the nearest folder that has it; undefined when none is. Only its own system.yaml is read. */
301
+ export function findSystem(folders, name) {
292
302
  const found = systemFolders(folders).find((candidate) => comparableText(candidate.name) === comparableText(name.trim()));
293
- return found === undefined ? undefined : readSystem(found.folder, found.name, data);
303
+ return found === undefined ? undefined : readSystem(found.folder, found.name);
294
304
  }
295
- function readSystem(folder, name, additions) {
305
+ function readSystem(folder, name, layers = []) {
296
306
  const file = join(folder, systemFileName);
297
- const path = additions === undefined ? file : `${file} with the additions of campaign.yaml`;
307
+ const path = layers.length === 0 ? file : `${file} with the additions of ${layers.map((layer) => layer.from).join(", ")}`;
298
308
  const raw = readYamlValues(file, 'what the system is, such as "title: ..."');
299
309
  let merged = raw;
300
310
  try {
301
- merged = additions === undefined ? raw : withCampaignData(raw, additions);
311
+ merged = layers.reduce((below, layer) => withCampaignData(below, layer.data), raw);
302
312
  }
303
313
  catch (error) {
304
314
  throw new Error(`The game system ${name} cannot be read, because ${path} is not valid: ${error instanceof Error ? error.message : String(error)}`);