@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.
- package/GUIDE.md +178 -18
- package/bin/wildshard.mjs +1 -1
- package/codemods/0.2.5.mjs +12 -0
- package/lint/ratchet.json +1 -9
- package/lint/sdk-plugin.mjs +24 -2
- package/package.json +4 -3
- package/scripts/gen-format-schema.mjs +1 -1
- package/scripts/wildshard.mjs +8 -2
- package/skills/wildshard-upgrade/SKILL.md +15 -22
- package/src/cli/audio/audio.ts +17 -2
- package/src/cli/help.ts +11 -0
- package/src/cli/main.ts +1 -2
- package/src/cli/report.ts +8 -4
- package/src/cli/shardfile/command.ts +1 -2
- package/src/sharddev/agentFiles.ts +127 -0
- package/src/sharddev/author.ts +16 -3
- package/src/sharddev/bake/authoredWorld.ts +1 -1
- package/src/sharddev/bake/specimenCatalogue.ts +1 -1
- package/src/sharddev/bake/staticMaterials.ts +1 -1
- package/src/sharddev/check.ts +7 -6
- package/src/sharddev/checkProject.ts +4 -3
- package/src/sharddev/cli.ts +18 -5
- package/src/sharddev/formatJsonSchema.ts +1117 -3
- package/src/sharddev/kit/bakedGeometry.ts +58 -12
- package/src/sharddev/nativePopulationRows.ts +1 -1
- package/src/sharddev/newProject.ts +4 -25
- package/src/sharddev/performancePolicy.ts +16 -5
- package/src/sharddev/phasedBoss.ts +212 -34
- package/src/sharddev/project.ts +1 -1
- package/src/sharddev/projectEntryProof.ts +1 -1
- package/src/sharddev/projectGeneration.ts +1 -1
- package/src/sharddev/projectOutput.ts +1 -1
- package/src/sharddev/projectSections.ts +1 -1
- package/src/sharddev/refusals.ts +92 -18
- package/src/sharddev/reportCard.ts +1 -1
- package/src/sharddev/sections.ts +1 -1
- package/src/sharddev/species/clips.ts +64 -24
- package/src/sharddev/speciesBrains.ts +98 -15
- package/src/sharddev/updatePins.ts +254 -0
- package/src/sharddev/weapons/bowProfile.ts +3 -3
- package/src/sharddev/weapons/meleeProfile.ts +48 -4
- package/src/sharddev/worldScenes.ts +1 -1
- package/tsconfig.author.json +1 -0
package/src/sharddev/refusals.ts
CHANGED
|
@@ -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.
|
|
7
|
-
//
|
|
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,
|
|
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)
|
|
66
|
-
{ id: 'budget-unmeasured', anchor: 'budget-unmeasured', steps:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
/**
|
|
219
|
-
|
|
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/
|
|
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;
|
package/src/sharddev/sections.ts
CHANGED
|
@@ -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 '
|
|
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
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
/**
|
|
8
|
-
export
|
|
9
|
-
/**
|
|
10
|
-
|
|
11
|
-
/**
|
|
12
|
-
|
|
13
|
-
/**
|
|
14
|
-
|
|
15
|
-
/**
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
/**
|
|
20
|
-
export type
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
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
|
-
|
|
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
|
-
*
|
|
13
|
-
*
|
|
14
|
-
* `
|
|
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
|
|
18
|
-
|
|
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
|
}
|