@wildshard/sdk 0.2.3 → 0.2.5

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 (43) hide show
  1. package/GUIDE.md +178 -18
  2. package/bin/wildshard.mjs +1 -1
  3. package/codemods/0.2.5.mjs +12 -0
  4. package/lint/ratchet.json +1 -9
  5. package/lint/sdk-plugin.mjs +24 -2
  6. package/package.json +4 -3
  7. package/scripts/gen-format-schema.mjs +1 -1
  8. package/scripts/wildshard.mjs +8 -2
  9. package/skills/wildshard-upgrade/SKILL.md +15 -22
  10. package/src/cli/audio/audio.ts +17 -2
  11. package/src/cli/help.ts +11 -0
  12. package/src/cli/main.ts +1 -2
  13. package/src/cli/report.ts +8 -4
  14. package/src/cli/shardfile/command.ts +1 -2
  15. package/src/sharddev/agentFiles.ts +127 -0
  16. package/src/sharddev/author.ts +16 -3
  17. package/src/sharddev/bake/authoredWorld.ts +1 -1
  18. package/src/sharddev/bake/specimenCatalogue.ts +1 -1
  19. package/src/sharddev/bake/staticMaterials.ts +1 -1
  20. package/src/sharddev/check.ts +7 -6
  21. package/src/sharddev/checkProject.ts +4 -3
  22. package/src/sharddev/cli.ts +18 -5
  23. package/src/sharddev/formatJsonSchema.ts +1117 -3
  24. package/src/sharddev/kit/bakedGeometry.ts +58 -12
  25. package/src/sharddev/nativePopulationRows.ts +1 -1
  26. package/src/sharddev/newProject.ts +4 -25
  27. package/src/sharddev/performancePolicy.ts +16 -5
  28. package/src/sharddev/phasedBoss.ts +212 -34
  29. package/src/sharddev/project.ts +1 -1
  30. package/src/sharddev/projectEntryProof.ts +1 -1
  31. package/src/sharddev/projectGeneration.ts +1 -1
  32. package/src/sharddev/projectOutput.ts +1 -1
  33. package/src/sharddev/projectSections.ts +1 -1
  34. package/src/sharddev/refusals.ts +92 -18
  35. package/src/sharddev/reportCard.ts +1 -1
  36. package/src/sharddev/sections.ts +1 -1
  37. package/src/sharddev/species/clips.ts +64 -24
  38. package/src/sharddev/speciesBrains.ts +98 -15
  39. package/src/sharddev/updatePins.ts +254 -0
  40. package/src/sharddev/weapons/bowProfile.ts +3 -3
  41. package/src/sharddev/weapons/meleeProfile.ts +48 -4
  42. package/src/sharddev/worldScenes.ts +1 -1
  43. package/tsconfig.author.json +1 -0
@@ -3,21 +3,32 @@
3
3
  // local checks) names a stable rule id, a one-line fix and a
4
4
  // GUIDE.md section. This file is the one table. GUIDE.md (SA13) writes one heading per anchor below, so
5
5
  // `GUIDE.md#<anchor>` lands on it; refusals.test.ts fails a row with no fix or anchor and a wildshard lint rule with no
6
- // row. Rule ids are stable: rename one only together with its GUIDE.md heading. A message takes the first row (in table
7
- // order) for its step whose pattern matches, else its step's catch-all (the row with no pattern), wherever that sits.
6
+ // row. Rule ids are stable: rename one only together with its GUIDE.md heading.
7
+ //
8
+ // SA41: shard-format's refusals carry a stable code (its `issue-codes.ts`, docs/VALIDATION-CODES.md): a validator's
9
+ // `error.code`, `PerformanceIssue.code`, `AudioFinding.code`. A coded refusal takes the row that lists its code, from any
10
+ // step; every one of shard-format's codes has a row (refusals.test.ts fails a new code with none). Words are the fallback
11
+ // for refusals with no code (sharddev's own, and shard-format's admitted-with-warning lines): a message takes the first
12
+ // row (in table order) for its step whose pattern matches, else its step's catch-all (the row with neither pattern nor
13
+ // codes), wherever that sits.
8
14
  //
9
15
  // Messages stay as the refusing code (and shard-format) words them: a row matches them, it never rewrites them.
16
+ import type { IssueCode } from '@wildshard/format/issue-codes';
10
17
 
11
18
  /** Where a refusal came from: `check`'s five steps, then the other verbs. `shardfile` is the shard file build writes (SA3). */
12
- export type RefusalStep = 'lint' | 'build' | 'validate' | 'prove' | 'report' | 'new' | 'shardfile' | 'pack' | 'upload' | 'account' | 'delete';
13
- /** One rule: its id, its GUIDE.md anchor, the fix, and the refusal messages it names (none: the step's catch-all). */
19
+ export type RefusalStep = 'lint' | 'build' | 'validate' | 'prove' | 'report' | 'new' | 'update' | 'shardfile' | 'pack' | 'upload' | 'account' | 'delete';
20
+ /** One rule: its id, its GUIDE.md anchor, the fix, the shard-format codes it names (from any step) and the refusal
21
+ * messages it names in `steps` (neither: the step's catch-all). */
14
22
  export interface RefusalRule {
15
23
  readonly id: string;
16
24
  readonly anchor: string;
17
25
  readonly fix: string;
18
26
  readonly steps: readonly RefusalStep[] | 'any';
27
+ readonly codes?: readonly IssueCode[];
19
28
  readonly match?: RegExp;
20
29
  }
30
+ /** What a refusal carries besides its words: oxlint's code and help, or shard-format's issue code. */
31
+ export interface RefusalSource { readonly lint?: { readonly code: string | null; readonly help: string | null } | undefined; readonly code?: string | undefined }
21
32
  /** What a printed refusal carries besides its message. `guide` is `GUIDE.md#<anchor>`. */
22
33
  export interface RefusalNote { readonly rule: string; readonly fix: string; readonly guide: string }
23
34
 
@@ -35,6 +46,17 @@ export const REFUSAL_RULES: readonly RefusalRule[] = [
35
46
  fix: 'Leave out --template, or pass `--template sdk` (the reference world) or `--template blender` (the hand-written Blender template).' },
36
47
  { id: 'new-refused', anchor: 'new-refused', steps: ['new'],
37
48
  fix: 'Reinstall @wildshard/sdk (`pnpm install`); `new` copies the reference world shipped with it.' },
49
+ // update (SA28)
50
+ { id: 'update-target', anchor: 'update-target', steps: ['update'], match: /^update: .* is not a shard repo/u,
51
+ fix: 'Run `wildshard update` in the repo `wildshard new` made, or name it: `wildshard update my-isle`.' },
52
+ { id: 'update-pins-no-git', anchor: 'update-pins-no-git', steps: ['update'], match: /^update --pins: .* is not in a git repo with its package\.json committed/u,
53
+ fix: 'Put the shard repo in git and commit it (`git init`, `git add .`, `git commit`), then run `wildshard update --pins` again.' },
54
+ { id: 'update-pins-dirty', anchor: 'update-pins-dirty', steps: ['update'], match: /^update --pins: .* has uncommitted changes/u,
55
+ fix: 'Commit or stash your changes, then run `wildshard update --pins` again.' },
56
+ { id: 'update-pins', anchor: 'update-pins', steps: ['update'], match: /^update --pins: /u,
57
+ fix: 'Read the line above and the GUIDE.md heading for its case, fix that, then run `wildshard update --pins` again.' },
58
+ { id: 'update-refused', anchor: 'update-refused', steps: ['update'],
59
+ fix: 'Reinstall @wildshard/sdk (`pnpm install`); `update` copies GUIDE.md and the skills shipped with it.' },
38
60
  // build
39
61
  { id: 'source-file-missing', anchor: 'source-file-missing', steps: ['build', 'validate', 'prove'], match: /ENOENT: no such file or directory|Cannot resolve entry module/u,
40
62
  fix: 'Check the path shown: the shard source or shard file folder, or a file it names, is not there.' },
@@ -62,24 +84,27 @@ export const REFUSAL_RULES: readonly RefusalRule[] = [
62
84
  fix: 'Fix the proof tape (proof.json) where the message says; its shape is the author proof plan.' },
63
85
  { id: 'proof-failed', anchor: 'proof-failed', steps: ['prove'],
64
86
  fix: 'Walk the quest in `wildshard dev`, then fix the data or the tape step that did not happen.' },
65
- // the report card (budgets, J303); a metric is shard-format's name for it
66
- { id: 'budget-unmeasured', anchor: 'budget-unmeasured', steps: ['report'], match: /measurement required|missing execution samples|^invalid measured/u,
87
+ // the report card (budgets, J303): shard-format's PerformanceIssue codes
88
+ { id: 'budget-unmeasured', anchor: 'budget-unmeasured', steps: 'any',
89
+ codes: ['perf-native-view-unmeasured', 'perf-native-resident-unmeasured', 'perf-script-sample-invalid', 'perf-script-samples-missing'],
67
90
  fix: 'Run the shard long enough to measure: `wildshard check` measures it headlessly; native gameplay needs a browser proof.' },
68
- { id: 'budget-download', anchor: 'budget-download', steps: ['report'], match: /download (?:budget )?bytes/u,
91
+ { id: 'budget-download', anchor: 'budget-download', steps: 'any',
92
+ codes: ['perf-library-download-budget', 'perf-critical-download-budget', 'perf-library-download', 'perf-critical-download', 'perf-tile-download', 'perf-far-download'],
69
93
  fix: 'Shrink or drop assets on the named download tier, or move them to a later tier.' },
70
- { id: 'budget-draws', anchor: 'budget-draws', steps: ['report'], match: /\bdraws\b/u,
94
+ { id: 'budget-draws', anchor: 'budget-draws', steps: 'any', codes: ['perf-tile-draws', 'perf-far-draws'],
71
95
  fix: 'Merge meshes that share a material, or cut objects from the named view.' },
72
- { id: 'budget-triangles', anchor: 'budget-triangles', steps: ['report'], match: /\btriangles\b/u,
96
+ { id: 'budget-triangles', anchor: 'budget-triangles', steps: 'any', codes: ['perf-tile-triangles', 'perf-far-triangles'],
73
97
  fix: 'Lower the mesh detail (LODs, fewer props) in the named view.' },
74
- { id: 'budget-memory', anchor: 'budget-memory', steps: ['report'], match: /resident target|loading total bytes|playing total bytes/u,
98
+ { id: 'budget-memory', anchor: 'budget-memory', steps: 'any', codes: ['perf-memory-target', 'perf-playing-memory', 'perf-loading-memory'],
75
99
  fix: 'Cut texture size or count and mesh bytes until the named total fits.' },
76
- { id: 'budget-script-cpu', anchor: 'budget-script-cpu', steps: ['report'], match: /^script CPU/u,
100
+ { id: 'budget-script-cpu', anchor: 'budget-script-cpu', steps: 'any', codes: ['perf-script-cpu'],
77
101
  fix: 'Do less work per tick in behaviour scripts: spread it over ticks or run it on events.' },
78
- { id: 'budget-script-fuel', anchor: 'budget-script-fuel', steps: ['report'], match: /^script fuel/u,
102
+ { id: 'budget-script-fuel', anchor: 'budget-script-fuel', steps: 'any', codes: ['perf-script-fuel'],
79
103
  fix: 'Shorten the hottest behaviour script loops; fuel counts instructions per tick.' },
80
104
  { id: 'budget-over', anchor: 'budget-over', steps: ['report'],
81
105
  fix: 'Run `wildshard check`: its report step names each budget over its limit and the row here for each.' },
82
- { id: 'budget-refused', anchor: 'budget-refused', steps: ['build', 'validate'], match: /Performance report refused/u,
106
+ // `Performance report refused` is sharddev's own words (cli.ts); the two codes are shard-format's preflight of the same.
107
+ { id: 'budget-refused', anchor: 'budget-refused', steps: ['build', 'validate'], codes: ['declared-costs', 'performance-targets'], match: /Performance report refused/u,
83
108
  fix: 'Run `wildshard check`: its report step names each budget over its limit and the row here for each.' },
84
109
  // the shard file build writes (SA3; `pack` is its deprecated alias) and upload, before a byte is sent. `shardfile-draft` is
85
110
  // a warning from build and check and a refusal from upload (draft.ts).
@@ -89,16 +114,48 @@ export const REFUSAL_RULES: readonly RefusalRule[] = [
89
114
  fix: 'Build again after the hero capture: `wildshard build` writes a shard file that carries it.' },
90
115
  { id: 'hero-unchanged', anchor: 'hero-unchanged', steps: ['upload'], match: /the hero is unchanged since/u,
91
116
  fix: 'Capture a new hero (`wildshard hero`), then build and upload again.' },
92
- { id: 'audio-refused', anchor: 'audio-refused', steps: ['pack', 'upload'], match: /^Audio rules \(AU5\) refuse/u,
117
+ // the audio rules (AU5): `audio-refused` is upload's refusal of a red report; the rest are its findings, which build
118
+ // prints with their rows (red or amber, a build never refuses on them)
119
+ { id: 'audio-refused', anchor: 'audio-refused', steps: 'any', codes: ['audio-refused'],
93
120
  fix: 'Fix each red audio finding listed, or waive it in the shard\'s audio-waiver.json.' },
121
+ { id: 'audio-unreadable', anchor: 'audio-unreadable', steps: 'any', codes: ['audio-unreadable'],
122
+ fix: 'Export the recording again as AAC-LC 48 kHz, mono or stereo, in an .m4a file: this one does not read as that.' },
123
+ { id: 'audio-container', anchor: 'audio-container', steps: 'any', codes: ['audio-container'],
124
+ fix: 'Export the recording again as AAC-LC 48 kHz in an .m4a file, not WAV: its bytes are FLAC, AIFF, Ogg, MP3, WebM, CAF or unknown.' },
125
+ { id: 'audio-encoding', anchor: 'audio-encoding', steps: 'any', codes: ['audio-strict-index', 'audio-wav', 'audio-sample-rate'],
126
+ fix: 'Encode the recording as AAC-LC at 48 kHz in an .m4a file; it plays as it is, but ships larger or less safely.' },
127
+ { id: 'audio-duration', anchor: 'audio-duration', steps: 'any', codes: ['audio-duration'],
128
+ fix: 'Cut the recording under the maximum length the message gives, or split it in two.' },
129
+ { id: 'audio-bitrate', anchor: 'audio-bitrate', steps: 'any', codes: ['audio-bitrate'],
130
+ fix: 'Encode the recording at a lower bitrate: the message gives the cap for its role and channels.' },
131
+ { id: 'audio-budget', anchor: 'audio-budget', steps: 'any', codes: ['audio-budget-amber', 'audio-budget-red', 'audio-budget-waived'],
132
+ fix: 'Cut, shorten or re-encode recordings until the shard\'s own audio fits, or add a dated audio-waiver.json.' },
133
+ { id: 'audio-waiver', anchor: 'audio-waiver', steps: 'any', codes: ['audio-waiver-invalid'],
134
+ fix: 'Fix audio-waiver.json: this shard\'s slug, a date not yet past, and at least the bytes its audio holds.' },
94
135
  { id: 'shardfile-draft', anchor: 'shardfile-draft', steps: ['shardfile', 'upload'], match: /is an unprepared draft \(sdk 0\.2\)/u,
95
136
  fix: 'Run `wildshard prepare <folder> --base <url>`, then `wildshard build <folder>`; a shard repo\'s `pack:shards` does both (WILDSHARD_PREPARATION_URL).' },
96
137
  { id: 'shardfile-link', anchor: 'shardfile-link', steps: ['shardfile', 'pack'], match: /not a regular file|link is refused/u,
97
138
  fix: 'Replace links in the shard file folder with real files, then build again.' },
98
139
  { id: 'shardfile-folder-missing', anchor: 'shardfile-folder-missing', steps: ['shardfile', 'pack'], match: /(?:build|pack) needs a shard file folder|ENOENT/u,
99
140
  fix: 'Build the shard source: `wildshard build <source>` writes public/shardfiles/<slug>.shardfile.' },
100
- { id: 'shardfile-invalid', anchor: 'shardfile-invalid', steps: ['shardfile', 'pack', 'upload'], match: /^no \S+ in the shard ?file|is larger than \d+ bytes|Invalid [a-z]+: /u,
141
+ // shard-format's validator refusals (SA41's validate and stream codes), from validate, the shard file step or upload
142
+ { id: 'shardfile-invalid', anchor: 'shardfile-invalid', steps: 'any', codes: ['archive-invalid'],
101
143
  fix: 'Upload the shard file `wildshard build` wrote, unedited: the format checks refuse this one.' },
144
+ { id: 'shardfile-index', anchor: 'shardfile-index', steps: 'any', codes: ['index-invalid'],
145
+ fix: 'Build again so shard.json is written for you; a hand-written shard.json must parse and fit the index schema.' },
146
+ { id: 'shardfile-files', anchor: 'shardfile-files', steps: 'any', codes: ['file-mismatch', 'unlisted-file', 'source-hash', 'pack-invalid'],
147
+ fix: 'Build again: the folder\'s files differ from the ones shard.json lists, so never edit a built folder by hand.' },
148
+ { id: 'shardfile-section', anchor: 'shardfile-section', steps: 'any', codes: ['section-invalid', 'shard-schema'],
149
+ fix: 'Give the field at the path shown the value it expects; `wildshard schema shardfile <pointer>` prints its shape.' },
150
+ { id: 'shardfile-assets', anchor: 'shardfile-assets', steps: 'any',
151
+ codes: ['blob-invalid', 'server-file-invalid', 'ktx2-costs', 'asset-admission', 'cook-invalid', 'runtime-files'],
152
+ fix: 'Export the asset the message names again and build: its bytes do not match what the shard file declares.' },
153
+ { id: 'shardfile-scripts', anchor: 'shardfile-scripts', steps: 'any', codes: ['script-side', 'script-admission'],
154
+ fix: 'Run each behaviour script only on the side its declaration allows, then build again.' },
155
+ { id: 'shardfile-targets', anchor: 'shardfile-targets', steps: 'any', codes: ['world-targets'],
156
+ fix: 'Declare the item or quest the message names, or take it out of the world targets.' },
157
+ { id: 'shardfile-stream', anchor: 'shardfile-stream', steps: 'any', codes: ['stream-cap', 'stream-miss', 'stream-changed'],
158
+ fix: 'Shrink the file or pack the message names under the streaming cap; if the file changed mid-read, upload again.' },
102
159
  { id: 'shardfile-refused', anchor: 'shardfile-refused', steps: ['shardfile', 'pack'],
103
160
  fix: 'Build the shard source again with `wildshard build`: it writes and checks the shard file.' },
104
161
  { id: 'upload-shardfile-missing', anchor: 'upload-shardfile-missing', steps: ['upload'], match: /upload needs a shard ?file|ENOENT/u,
@@ -215,15 +272,32 @@ export function lintRuleId(code: string): string {
215
272
  return match === null ? code : `${match[1] ?? ''}/${match[2] ?? ''}`;
216
273
  }
217
274
 
218
- /** The rule, fix and guide link for a refusal message from `step`. A known lint rule's code wins over the message. */
219
- export function refusalNote(step: RefusalStep, message: string, lint?: { readonly code: string | null; readonly help: string | null }): RefusalNote {
275
+ /** shard-format's codes, each to the row that names it. */
276
+ const RULE_BY_CODE: ReadonlyMap<string, RefusalRule> = new Map(REFUSAL_RULES.flatMap(row => (row.codes ?? []).map(code => [code, row] as const)));
277
+
278
+ /** The shard-format code a refusal carries (SA41): on the error or, when sharddev wrapped it, on a cause beneath it. */
279
+ export function refusalCode(error: unknown): string | undefined {
280
+ for (let at = error, depth = 0; typeof at === 'object' && at !== null && depth < 8; depth += 1) {
281
+ const code: unknown = 'code' in at ? at.code : undefined;
282
+ if (typeof code === 'string' && RULE_BY_CODE.has(code)) return code;
283
+ at = 'cause' in at ? at.cause : undefined;
284
+ }
285
+ return undefined;
286
+ }
287
+
288
+ /** The rule, fix and guide link for a refusal message from `step`. A known lint rule's code wins over the message, and
289
+ * so does a shard-format code (SA41); the message's words are the fallback. */
290
+ export function refusalNote(step: RefusalStep, message: string, source: RefusalSource = {}): RefusalNote {
291
+ const { lint, code } = source;
220
292
  if (lint?.code !== undefined && lint.code !== null) {
221
293
  const id = lintRuleId(lint.code), known = LINT_BY_ID.get(id);
222
294
  const help = lint.help?.split('\n')[0]?.trim() ?? '';
223
295
  return known === undefined ? note(LINT_OTHER, id, help === '' ? LINT_OTHER.fix : help) : note(known);
224
296
  }
297
+ const coded = code === undefined ? undefined : RULE_BY_CODE.get(code);
298
+ if (coded !== undefined) return note(coded);
225
299
  const rule = REFUSAL_RULES.find(row => appliesTo(row, step) && row.match?.test(message) === true)
226
- ?? REFUSAL_RULES.find(row => appliesTo(row, step) && row.match === undefined);
300
+ ?? REFUSAL_RULES.find(row => appliesTo(row, step) && row.match === undefined && row.codes === undefined);
227
301
  if (rule === undefined) throw new Error(`no refusal rule for step ${step}`);
228
302
  return note(rule);
229
303
  }
@@ -1,5 +1,5 @@
1
1
  import { performanceReport as report, performanceReportLines as lines, performanceTargetIssues as targets, type PerformanceReport as GameReport, type PerformanceObservations as GameObservations } from '@wildshard/format/product';
2
- import type { Shardfile } from '@wildshard/engine/host/shardfile';
2
+ import type { Shardfile } from '@wildshard/format/shardSchema';
3
3
 
4
4
  /** Author-facing report: declared bounds, measured scripts and explicit cold-network assumptions. */
5
5
  export type PerformanceReport = GameReport;
@@ -2,7 +2,7 @@ import * as v from 'valibot';
2
2
  import Ajv from 'ajv';
3
3
  import { registeredJsonContract, validateRegisteredJson } from '@wildshard/format/registeredJson';
4
4
  import { encodeCanonicalJson } from './immutable';
5
- import { registeredJsonSchema } from '@wildshard/engine/host/formatJsonSchema';
5
+ import { registeredJsonSchema } from './formatJsonSchema';
6
6
  import { validateNamedJson } from './schemaValidation';
7
7
 
8
8
  /** A platform section entry with its defining schema identity. */
@@ -1,24 +1,64 @@
1
- import { clipAnimate as platformClipAnimate, playClips as platformPlayClips, type ClipCase as PlatformClipCase, type ClipChannel as PlatformClipChannel, type ClipClock as PlatformClipClock, type ClipCtx as PlatformClipCtx, type ClipFactor as PlatformClipFactor, type ClipRow as PlatformClipRow, type ClipTerm as PlatformClipTerm, type ClipWhen as PlatformClipWhen, type SpeciesClips as PlatformSpeciesClips } from '@wildshard/engine/game/plugin/animation';
2
-
3
- /** The clocks a clip factor reads: the animal's time or its gait phase. */
4
- export type ClipClock = PlatformClipClock;
5
- /** When a clip case or term applies. */
6
- export type ClipWhen = PlatformClipWhen;
7
- /** One factor of a clip term (a bare number is a constant). */
8
- export type ClipFactor = PlatformClipFactor;
9
- /** One term of a clip sum: a constant or a product of factors. */
10
- export type ClipTerm = PlatformClipTerm;
11
- /** One case of a clip row. */
12
- export type ClipCase = PlatformClipCase;
13
- /** The bone channels a clip row drives. */
14
- export type ClipChannel = PlatformClipChannel;
15
- /** One clip row: a bone's channel and its cases. */
16
- export type ClipRow = PlatformClipRow;
17
- /** A species' declarative clips (SHARD-PLATFORM M3). */
18
- export type SpeciesClips = PlatformSpeciesClips;
19
- /** What a clip reads from the frame. */
20
- export type ClipCtx = PlatformClipCtx;
21
- /** Plays one frame of a species' clips on its bones. */
22
- export const playClips: typeof platformPlayClips = platformPlayClips;
23
- /** A species' `animate` from its clip rows. */
24
- export const clipAnimate: typeof platformClipAnimate = platformClipAnimate;
1
+ // A species' declarative clip rows, as the SDK defines them (SHARD-AUTHORING SA12). They are data: the engine plays them
2
+ // (game/plugin/animation `playClips`); `test/sdk-engine-types.test.ts` keeps each type equal to the engine's.
3
+
4
+ /** The clocks a clip factor reads: the animal's time (s) or its gait phase (0..1, advanced from the ground speed). */
5
+ export type ClipClock = 't' | 'phase';
6
+
7
+ /** When a clip case or term applies. Every key present must hold. */
8
+ export interface ClipWhen {
9
+ /** true: only while alive; false: only once dead. */
10
+ readonly alive?: boolean;
11
+ /** Only while an attack plays (`attack ≥ 0`). */
12
+ readonly attacking?: boolean;
13
+ /** Only while `deathT` is above this (the collapse has begun). */
14
+ readonly deathAbove?: number;
15
+ /** A `mem` number (absent reads 0) compared with `above` (>) and / or `atLeast` (≥). */
16
+ readonly mem?: { readonly key: string; readonly above?: number; readonly atLeast?: number };
17
+ }
18
+
19
+ /** One factor of a clip term. A bare number is a constant. */
20
+ export type ClipFactor =
21
+ | number
22
+ /** `sin(clock × rate + offset)`, or its magnitude with `abs`. */
23
+ | { readonly wave: ClipClock; readonly rate: number; readonly offset?: number; readonly abs?: boolean }
24
+ /** The clock itself (a spin: `t` × a rate factor). */
25
+ | { readonly clock: ClipClock }
26
+ /** A number the species' brain keeps in `mem` (absent reads 0). */
27
+ | { readonly mem: string }
28
+ /** Sum in authored order, cap with max then min, then divide (never multiply by a reciprocal). */
29
+ | { readonly bounded: readonly ClipTerm[]; readonly min?: number; readonly max?: number; readonly divide?: number }
30
+ /** The attack's progress 0..1, × `rate` and capped at `max` when given (pair it with a term `when: { attacking: true }`). */
31
+ | { readonly attack: true; readonly rate?: number; readonly max?: number }
32
+ /** A gait weight: `min(1, |speed| / full)`, × (`speed > run` ? `fast` : `slow`) when `run` is given. One value. */
33
+ | { readonly gait: number; readonly run?: number; readonly fast?: number; readonly slow?: number }
34
+ /** The death collapse, `deathT` clamped to 0..1. */
35
+ | { readonly death: true }
36
+ /** 1 while alive, 0 once dead. */
37
+ | { readonly living: true };
38
+
39
+ /** One term of a clip sum: a constant, or the product of its factors (only when `when` holds; else +0). */
40
+ export type ClipTerm = number | { readonly when?: ClipWhen; readonly of: readonly ClipFactor[] };
41
+
42
+ /** One case of a clip row: the first whose `when` holds sets the channel to the sum of `sum` (an empty sum is 0). */
43
+ export interface ClipCase { readonly when?: ClipWhen; readonly sum: readonly ClipTerm[] }
44
+
45
+ /** The bone channels a clip row drives. `scale` sets all three axes. */
46
+ export type ClipChannel = 'rotation.x' | 'rotation.y' | 'rotation.z' | 'position.x' | 'position.y' | 'position.z' | 'scale';
47
+
48
+ /** One clip row: a bone's channel and its cases in priority order, or an eased `mem` scratch channel. */
49
+ export type ClipRow = {
50
+ readonly bone: string;
51
+ readonly channel: ClipChannel;
52
+ /** The `mem` key that keeps the bone's bind value; the sum then starts from it. */
53
+ readonly bind?: string;
54
+ readonly cases: readonly ClipCase[];
55
+ } | {
56
+ /** Ordered scratch channel; later rows observe its newly eased value even when a rig bone is absent. */
57
+ readonly mem: string;
58
+ /** old + (target - old) * min(1, dt * ease), with an absent old value read as zero. */
59
+ readonly ease: number;
60
+ readonly cases: readonly ClipCase[];
61
+ };
62
+
63
+ /** A species' declarative clips (SHARD-PLATFORM M3): its rows, played in order every frame. */
64
+ export type SpeciesClips = readonly ClipRow[];
@@ -1,19 +1,102 @@
1
- import { admitSpeciesProgram, type BrainedSpecies as PlatformBrainedSpecies, type SpeciesBrain as PlatformSpeciesBrain, type SpeciesBrains as PlatformSpeciesBrains } from "@wildshard/engine/game/plugin/brain";
1
+ // A species row and its declared brain, as the SDK defines them (SHARD-AUTHORING SA12). The row is gameplay data and the
2
+ // brain one platform archetype with its shard-format data; `test/sdk-engine-types.test.ts` keeps both equal to the engine's
3
+ // (game/plugin/brain), so a drift in either fails the test. The engine admits them (game/plugin/brain
4
+ // `admitSpeciesProgram`; SA26 took that runtime call off the SDK).
5
+ import type * as v from 'valibot';
6
+ import type { BorrowedDecision } from '@wildshard/format/decisionScripts';
7
+ import type { ScriptSpeciesSchema } from '@wildshard/format/speciesScripts';
8
+ import type { CreatureBodyRecipe } from '@wildshard/format/creatures';
9
+ import type { GrazerSchema, ChallengeGrazerSchema } from '@wildshard/format/grazers';
10
+ import type { DiverSchema, PatrolDiverSchema } from '@wildshard/format/flyers';
11
+ import type { StalkerSchema, GuardianPatternsSchema, SkirmisherSchema, GuardianSchema, PerchHunterSchema } from '@wildshard/format/brains';
2
12
 
3
- import type { StrikeData } from './species';
4
-
5
- /** A species row's declared brain (SHARD-PLATFORM SF27): `{ archetype, data }`, one platform archetype and its data. */
6
- export type SpeciesBrain = PlatformSpeciesBrain;
7
- /** Species gameplay data with an optional `brain`; a row without one keeps its runtime's own policy. */
8
- export type BrainedSpecies = PlatformBrainedSpecies;
9
- /** A catalogue's admitted brains: browser callbacks (`bind`), the live witness and the headless home policies. */
10
- export type SpeciesBrains = PlatformSpeciesBrains;
11
13
  /**
12
- * Admit a shard's species catalogue and its strike rows (SF27): each strike passes the SDK's strict strike schema, each
13
- * declared brain its archetype's schema, and every strike a brain names resolves, before any row or policy is built; a
14
- * `script` brain's module comes in `modules` (a plain row: its SHA-256 → the base64 its bake wrote) and is admitted on its own
15
- * ScriptHost.
14
+ * A species row's declared brain (SHARD-PLATFORM SF27): `{ archetype, data }`, one platform archetype and its data. A
15
+ * challenge grazer's circling phase is the actor seed's slot in `[0, phaseSlots)`, so a pack spreads round its home. A
16
+ * `decision` brain lends its body to an admitted guest while the existing encounter owns its memory marks.
16
17
  */
17
- export function speciesBrains(species: readonly BrainedSpecies[], strikes: readonly StrikeData[], modules: Readonly<Record<string, string>> = {}): SpeciesBrains {
18
- return admitSpeciesProgram({ species, strikes, modules });
18
+ export type SpeciesBrain =
19
+ | { readonly archetype: 'grazer'; readonly data: Extract<v.InferInput<typeof GrazerSchema>, { pattern: 'wander-ram' }> }
20
+ | { readonly archetype: 'grazer'; readonly data: Extract<v.InferInput<typeof GrazerSchema>, { pattern: 'circle-challenge' }>; readonly phaseSlots: number }
21
+ | { readonly archetype: 'diver'; readonly data: v.InferInput<typeof DiverSchema> }
22
+ | { readonly archetype: 'decision'; readonly data: BorrowedDecision }
23
+ | { readonly archetype: 'challenge-grazer'; readonly data: v.InferInput<typeof ChallengeGrazerSchema>; readonly phaseSlots: number }
24
+ | { readonly archetype: 'patrol-diver'; readonly data: v.InferInput<typeof PatrolDiverSchema> }
25
+ | { readonly archetype: 'script'; readonly data: v.InferInput<typeof ScriptSpeciesSchema> }
26
+ | { readonly archetype: 'stalker'; readonly data: v.InferInput<typeof StalkerSchema> }
27
+ | { readonly archetype: 'skirmisher'; readonly data: v.InferInput<typeof SkirmisherSchema> }
28
+ | { readonly archetype: 'guardian'; readonly data: v.InferInput<typeof GuardianSchema> | v.InferInput<typeof GuardianPatternsSchema> }
29
+ | { readonly archetype: 'perch-hunter'; readonly data: v.InferInput<typeof PerchHunterSchema> };
30
+
31
+ /** A variant's rarity. */
32
+ export type Rarity = 'common' | 'uncommon' | 'rare' | 'legendary';
33
+
34
+ /** Per-variant gameplay multipliers, applied at spawn on top of the species' hunt tuning. */
35
+ export interface VariantMods {
36
+ /** × runSpeed / trotSpeed / charge speed (1 = species baseline) */
37
+ speed: number;
38
+ /** × panicDist (the charge trigger) and the "turns on you when hit" distance */
39
+ chargeDist: number;
40
+ /** × damage taken by BODY hits (headshots always land in full) */
41
+ damageTaken: number;
42
+ /** damage dealt to the player by one charge contact (species default 25) */
43
+ chargeDamage: number;
44
+ /** charges last 3× longer, cool down in 1/3 the time, and a hit always provokes one */
45
+ relentless: boolean;
46
+ }
47
+
48
+ /** One variant of a species: gameplay data only, never a builder, palette or hull. */
49
+ export interface SpeciesVariant {
50
+ id: string; label: string; weight: number; rarity: Rarity; scale: [number, number];
51
+ hp?: number; mods?: Partial<VariantMods>;
52
+ }
53
+
54
+ /** One animal kind's hunting-loop numbers (m, s, rad, awareness/s). Player speeds: crouch 2.2, walk 4.3, sprint 7.2 m/s. */
55
+ export interface HuntTuning {
56
+ hp: number;
57
+ sightRange: number; sightRangeGraze: number; sightCone: number;
58
+ hearStill: number; hearCrouch: number; hearWalk: number; hearSprint: number;
59
+ noticeRate: number; forgetRate: number; alertAt: number; boltAt: number;
60
+ freezeMin: number; freezeMax: number; relaxAfter: number; panicDist: number;
61
+ runSpeed: number; trotSpeed: number; fleeMinTime: number; fleeUntil: number; fleeUntilMax: number; fleeMaxTime: number;
62
+ lookBack: number; waryTime: number; waryBoost: number;
63
+ herdAlertRadius: number; herdBoltDelayMin: number; herdBoltDelayMax: number;
64
+ impactSpook: number; impactAlert: number;
65
+ /** Hunters: the alert turns into a pursuit ('stalk') instead of a bolt. */
66
+ stalk?: {
67
+ detect: number; speed: number; giveUp: number; rechargeCd: number; huffMin: number; huffMax: number;
68
+ /** sound played at the start of a charge */
69
+ roar: string;
70
+ fleeBelowHp: number; fleeChance: number;
71
+ } | undefined;
72
+ }
73
+
74
+ /** A flying species' altitude and climb, dive and bank limits. */
75
+ export interface SpeciesFlight {
76
+ altitude: number;
77
+ /** Ground-relative by default; a missing/distant floor falls back to world altitude. */
78
+ above?: 'ground' | 'world';
79
+ climbRate: number; diveRate: number;
80
+ /** Lock acquire distance in metres (eye → body edge); default 24 m, release at 1.5×. */
81
+ lockRange?: number;
82
+ /** The largest roll into a turn, radians (0 < bank < π/2); omitted, the body flies level. */
83
+ bank?: number;
84
+ }
85
+
86
+ /** Species gameplay data with an optional `brain`; a row without one keeps its runtime's own policy. */
87
+ export interface BrainedSpecies {
88
+ id: string; kind: string; label: string;
89
+ variants: SpeciesVariant[]; spawnOnly?: SpeciesVariant[];
90
+ aggressive?: boolean; walkSpeed?: number; chargeSpeed?: number; chargeDamage?: number;
91
+ /** s / m / m: the charge's wind-up, the ring a charger circles on, the grass track it flattens */
92
+ chargeWindup?: number; ringRadius?: number; trampleRadius?: number;
93
+ tuning?: HuntTuning;
94
+ sounds?: { call: string; hurt: string; callVariants?: string[]; callEvery?: [number, number] };
95
+ tick?: 'ai' | 'always';
96
+ corpseFade?: number; blood?: boolean;
97
+ flight?: SpeciesFlight;
98
+ /** LOCK / target taps: omitted ground species are not lockable; omitted flight species are. */
99
+ lockable?: boolean;
100
+ readonly brain?: SpeciesBrain;
101
+ readonly body?: CreatureBodyRecipe;
19
102
  }