@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
@@ -0,0 +1,254 @@
1
+ // oxlint-disable-next-line import/no-nodejs-modules -- `update --pins` asks pnpm for a release, installs it and runs its CLI.
2
+ import { execFileSync } from 'node:child_process';
3
+ // oxlint-disable-next-line import/no-nodejs-modules -- It edits the shard repo's package.json and reads the installed sdk.
4
+ import { existsSync, readFileSync, readdirSync, realpathSync, writeFileSync } from 'node:fs';
5
+ // oxlint-disable-next-line import/no-nodejs-modules -- Resolve files beneath the shard repo and the installed sdk.
6
+ import { basename, resolve } from 'node:path';
7
+ // oxlint-disable-next-line import/no-nodejs-modules -- A codemod is a module the installed sdk ships; it loads by file URL.
8
+ import { pathToFileURL } from 'node:url';
9
+ // oxlint-disable-next-line import/no-nodejs-modules -- The new sdk's CLI runs under this same Node.
10
+ import process from 'node:process';
11
+ import { assertShardRepo } from './agentFiles';
12
+
13
+ // SHARD-AUTHORING SA18 (J314 Q7, Q27; J317 Q16): `wildshard update --pins[=<version>] [dir]`. Move the repo's pins to one
14
+ // sdk release (the sdk, and the shard-format, engine and three specs that release pins), install with pnpm, apply the
15
+ // release's codemods, rewrite GUIDE.md and the skills with the new sdk's own `update` (SA28), then run its `check`. It
16
+ // starts only from a committed git tree (assertCommitted), so the author can tell its edits from their own.
17
+
18
+ /** The pins a shard repo may list; each moves to what the release names. `@wildshard/sdk` moves to the release itself. */
19
+ export const PINNED = ['@wildshard/sdk', '@wildshard/engine', '@wildshard/format', 'three'] as const;
20
+ const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies'] as const;
21
+
22
+ /** One sdk release, as the registry describes it: its version, the exact specs it pins (dependencies win over peers)
23
+ * and the Node it needs (`engines.node`, which `new` copies into a repo). */
24
+ export interface SdkRelease { readonly version: string; readonly pins: Readonly<Record<string, string>>; readonly node?: string }
25
+
26
+ /** How `update --pins` reaches the world, so a test can stand in for pnpm and the network. */
27
+ export interface PinsRunner {
28
+ /** The release `@wildshard/sdk@<spec>` names (`latest`, or a version). */
29
+ readonly view: (spec: string, cwd: string) => SdkRelease;
30
+ /** Run a command in `cwd` with its output shown; throw when it exits non-zero. */
31
+ readonly run: (command: string, args: readonly string[], cwd: string) => void;
32
+ readonly log: (line: string) => void;
33
+ }
34
+
35
+ const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/u;
36
+ /** Compare two versions `x.y.z[-pre]`: negative, zero or positive. A prerelease sorts before its release. */
37
+ export function compareVersions(a: string, b: string): number {
38
+ const left = SEMVER.exec(a), right = SEMVER.exec(b);
39
+ if (left === null || right === null) throw new Error(`update --pins: ${left === null ? a : b} is not a version`);
40
+ for (let part = 1; part <= 3; part += 1) {
41
+ const difference = Number(left[part]) - Number(right[part]);
42
+ if (difference !== 0) return difference;
43
+ }
44
+ const [preLeft, preRight] = [left[4], right[4]];
45
+ if (preLeft === preRight) return 0;
46
+ if (preLeft === undefined) return 1;
47
+ if (preRight === undefined) return -1;
48
+ // semver: dot-separated identifiers, numbers numerically and below words; fewer identifiers sort first.
49
+ const [partsLeft, partsRight] = [preLeft.split('.'), preRight.split('.')];
50
+ for (let index = 0; index < Math.min(partsLeft.length, partsRight.length); index += 1) {
51
+ const [l, r] = [partsLeft[index] ?? '', partsRight[index] ?? ''];
52
+ if (l === r) continue;
53
+ const [ln, rn] = [/^\d+$/u.test(l), /^\d+$/u.test(r)];
54
+ if (ln && rn) return Number(l) - Number(r);
55
+ if (ln !== rn) return ln ? -1 : 1;
56
+ return l < r ? -1 : 1;
57
+ }
58
+ return partsLeft.length - partsRight.length;
59
+ }
60
+
61
+ type Json = Record<string, unknown>;
62
+ const isRecord = (value: unknown): value is Json => typeof value === 'object' && value !== null && !Array.isArray(value);
63
+ const readJson = (file: string): Json => {
64
+ const parsed: unknown = JSON.parse(readFileSync(file, 'utf8'));
65
+ if (!isRecord(parsed)) throw new Error(`update --pins: ${file} is not a JSON object`);
66
+ return parsed;
67
+ };
68
+ const stringAt = (record: Json, key: string): string | undefined => typeof record[key] === 'string' ? record[key] : undefined;
69
+
70
+ /** One pin `movePins` changed (or left: the release no longer pins a package the repo lists). */
71
+ export interface PinMove { readonly name: string; readonly field: string; readonly from: string; readonly to: string | undefined }
72
+
73
+ /** The repo's package.json text with every listed pin moved to `release`; each pin keeps its field (a blender repo's
74
+ * sdk stays a dev dependency). `engines.node` moves too, when the repo lists it, since `new` writes it and `.npmrc`
75
+ * makes it strict. Nothing else in the file changes, and its indent is kept. */
76
+ export function movePins(text: string, release: SdkRelease): { readonly text: string; readonly moves: readonly PinMove[] } {
77
+ const parsed: unknown = JSON.parse(text);
78
+ if (!isRecord(parsed)) throw new Error('update --pins: package.json is not a JSON object');
79
+ const moves: PinMove[] = [];
80
+ for (const field of DEPENDENCY_FIELDS) {
81
+ const listed = parsed[field];
82
+ if (!isRecord(listed)) continue;
83
+ for (const name of PINNED) {
84
+ const from = stringAt(listed, name);
85
+ if (from === undefined) continue;
86
+ const to = name === '@wildshard/sdk' ? release.version : release.pins[name];
87
+ if (to === from) continue;
88
+ moves.push({ name, field, from, to });
89
+ if (to !== undefined) listed[name] = to;
90
+ }
91
+ }
92
+ const engines = parsed['engines'], node = isRecord(engines) ? stringAt(engines, 'node') : undefined;
93
+ if (isRecord(engines) && node !== undefined && release.node !== undefined && node !== release.node) {
94
+ moves.push({ name: 'engines.node', field: 'engines', from: node, to: release.node });
95
+ engines['node'] = release.node;
96
+ }
97
+ const indent = /^\{\r?\n([ \t]+)"/u.exec(text)?.[1] ?? 2;
98
+ return { text: moves.some(move => move.to !== undefined) ? `${JSON.stringify(parsed, null, indent)}\n` : text, moves };
99
+ }
100
+
101
+ /** Whether package.json lists `three` itself (a `--template sdk` repo does; a blender one does not). */
102
+ const listsThree = (listed: Json): boolean => DEPENDENCY_FIELDS.some(field => { const pins = listed[field]; return isRecord(pins) && stringAt(pins, 'three') !== undefined; });
103
+
104
+ /** The version of the package installed at `<project>/node_modules/<name>`, if any. */
105
+ function installedVersion(project: string, name: string): string | undefined {
106
+ const file = resolve(project, 'node_modules', name, 'package.json');
107
+ return existsSync(file) ? stringAt(readJson(file), 'version') : undefined;
108
+ }
109
+
110
+ /** The sdk version the repo is on now: its exact `@wildshard/sdk` pin, which must match what is installed. */
111
+ function currentSdk(project: string, listed: Json): string {
112
+ const pin = DEPENDENCY_FIELDS.map(field => listed[field]).map(pins => isRecord(pins) ? stringAt(pins, '@wildshard/sdk') : undefined)
113
+ .find(found => found !== undefined);
114
+ if (pin === undefined || !SEMVER.test(pin)) throw new Error(`update --pins: cannot tell which sdk ${project} is on: pin @wildshard/sdk to a version (not ${pin ?? 'nothing'})`);
115
+ const installed = installedVersion(project, '@wildshard/sdk');
116
+ if (installed !== undefined && installed !== pin) throw new Error(`update --pins: ${project} pins @wildshard/sdk ${pin} but has ${installed} installed: run pnpm install, then wildshard check ., then update --pins again`);
117
+ return pin;
118
+ }
119
+
120
+ /** A release's codemods: `codemods/<version>.mjs` in the installed sdk, each default-exporting
121
+ * `({ project, from, to }) => void | string[] | Promise<…>` that edits the shard repo for that release. */
122
+ export const CODEMODS_FOLDER = 'codemods';
123
+
124
+ /** The codemods for a move `from` → `to`: every `<v>.mjs` with from < v <= to, oldest first. */
125
+ export function codemodsBetween(sdkRoot: string, from: string, to: string): string[] {
126
+ const folder = resolve(sdkRoot, CODEMODS_FOLDER);
127
+ if (!existsSync(folder)) return [];
128
+ return readdirSync(folder)
129
+ .map(file => /^(.+)\.mjs$/u.exec(file)?.[1])
130
+ .filter((version): version is string => version !== undefined && SEMVER.test(version)
131
+ && compareVersions(version, from) > 0 && compareVersions(version, to) <= 0)
132
+ .sort(compareVersions)
133
+ .map(version => resolve(folder, `${version}.mjs`));
134
+ }
135
+
136
+ /** Apply each codemod from `codemodsBetween` to `project`, in order; returns what each says it changed. */
137
+ export async function applyCodemods(project: string, sdkRoot: string, from: string, to: string): Promise<string[]> {
138
+ const lines: string[] = [];
139
+ for (const file of codemodsBetween(sdkRoot, from, to)) {
140
+ const name = basename(file);
141
+ let said: unknown;
142
+ try {
143
+ const loaded: unknown = await import(pathToFileURL(file).href);
144
+ const codemod: unknown = isRecord(loaded) ? loaded['default'] : undefined;
145
+ if (typeof codemod !== 'function') throw new Error('it has no default export function');
146
+ said = await Reflect.apply(codemod, undefined, [{ project, from, to }]);
147
+ } catch (error) { throw new Error(`update --pins: codemod ${name} failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error }); }
148
+ lines.push(` codemod ${name}`);
149
+ if (Array.isArray(said)) for (const line of said) if (typeof line === 'string') lines.push(` ${line}`);
150
+ }
151
+ return lines;
152
+ }
153
+
154
+ /** `update --pins` edits package.json, the lock file and (by its codemods) the shard source, so it needs a repo whose
155
+ * every change is committed: then `git diff` shows only what the move made. It refuses a repo git does not track
156
+ * (no repo, or package.json not committed, as in a folder another repo ignores) and one with uncommitted or untracked
157
+ * changes. Ignored files (node_modules, build output) are not dirt. There is no flag to skip this. */
158
+ export function assertCommitted(project: string): void {
159
+ const git = (args: readonly string[]): string | undefined => {
160
+ try { return execFileSync('git', [...args], { cwd: project, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }); }
161
+ catch (error) {
162
+ if (isRecord(error) && error['code'] === 'ENOENT') throw new Error('update --pins: git not found: install git, then run update --pins again', { cause: error });
163
+ return undefined;
164
+ }
165
+ };
166
+ // Untracked files count whatever the author's status.showUntrackedFiles says.
167
+ const status = git(['ls-files', '--error-unmatch', '--', 'package.json']) === undefined ? undefined : git(['status', '--porcelain', '--untracked-files=normal', '--', '.']);
168
+ if (status === undefined) throw new Error(`update --pins: ${project} is not in a git repo with its package.json committed; update --pins edits your files, and git diff is how you see what it changed`);
169
+ const changed = status.split('\n').filter(line => line.trim() !== '');
170
+ if (changed.length > 0) {
171
+ const shown = changed.slice(0, 3).map(line => line.slice(3)).join(', ') + (changed.length > 3 ? ` and ${String(changed.length - 3)} more` : '');
172
+ throw new Error(`update --pins: ${project} has uncommitted changes (${shown}); commit or stash them first, so git diff shows only what update --pins changes`);
173
+ }
174
+ }
175
+
176
+ /** pnpm view: the release a spec names, with the specs it pins. */
177
+ function pnpmView(spec: string, cwd: string): SdkRelease {
178
+ let out: string;
179
+ try { out = execFileSync('pnpm', ['view', `@wildshard/sdk@${spec}`, 'version', 'dependencies', 'peerDependencies', 'engines', '--json'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }); }
180
+ catch (error) { throw new Error(`update --pins: pnpm view @wildshard/sdk@${spec} failed: ${error instanceof Error ? error.message.split('\n')[0] ?? '' : String(error)}`, { cause: error }); }
181
+ if (out.trim() === '') throw new Error(`update --pins: npm has no @wildshard/sdk@${spec}`);
182
+ const parsed: unknown = JSON.parse(out);
183
+ // A range matching several versions lists each; take the newest.
184
+ const found: unknown = Array.isArray(parsed) ? parsed.at(-1) : parsed;
185
+ const record = isRecord(found) ? found : {}, version = stringAt(record, 'version');
186
+ if (version === undefined || !SEMVER.test(version)) throw new Error(`update --pins: npm gave no version for @wildshard/sdk@${spec}`);
187
+ const pins: Record<string, string> = {};
188
+ for (const key of ['peerDependencies', 'dependencies']) {
189
+ const listed = record[key];
190
+ if (isRecord(listed)) for (const [name, value] of Object.entries(listed)) if (typeof value === 'string') pins[name] = value;
191
+ }
192
+ const engines = record['engines'], node = isRecord(engines) ? stringAt(engines, 'node') : undefined;
193
+ return { version, pins, ...(node === undefined ? {} : { node }) };
194
+ }
195
+
196
+ function runInherited(command: string, args: readonly string[], cwd: string): void {
197
+ execFileSync(command, args, { cwd, stdio: 'inherit' });
198
+ }
199
+
200
+ export const PNPM_RUNNER: PinsRunner = { view: pnpmView, run: runInherited, log: line => { console.info(line); } };
201
+
202
+ /** `wildshard update --pins[=<version>] [dir]`: move the repo at `project` to the sdk release `spec` names. */
203
+ export async function updatePins(project: string, spec = 'latest', runner: PinsRunner = PNPM_RUNNER): Promise<void> {
204
+ assertShardRepo(project);
205
+ const packageFile = resolve(project, 'package.json'), listed = readJson(packageFile);
206
+ const manager = stringAt(listed, 'packageManager');
207
+ if (manager !== undefined && !manager.startsWith('pnpm@')) throw new Error(`update --pins: ${project} names ${manager} as its package manager; update --pins installs with pnpm`);
208
+ const from = currentSdk(project, listed);
209
+ assertCommitted(project);
210
+ const release = runner.view(spec, project);
211
+ if (compareVersions(release.version, from) < 0) throw new Error(`update --pins: ${project} is on @wildshard/sdk ${from}, newer than ${release.version}; update --pins moves forward only`);
212
+ runner.log(`wildshard update --pins: @wildshard/sdk ${from} -> ${release.version}`);
213
+
214
+ // 1. Move the pins. Until the codemods are done, a failure puts package.json and the lock file back and installs the
215
+ // old sdk again, so a second run starts from the same sdk and applies every codemod.
216
+ const lockFile = resolve(project, 'pnpm-lock.yaml'), oldText = readFileSync(packageFile, 'utf8');
217
+ const oldLock = existsSync(lockFile) ? readFileSync(lockFile) : undefined;
218
+ const moved = movePins(oldText, release);
219
+ for (const move of moved.moves) runner.log(move.to === undefined
220
+ ? ` left ${move.name} ${move.from}: sdk ${release.version} no longer pins it`
221
+ : ` ${move.name} ${move.from} -> ${move.to}`);
222
+ if (moved.moves.length === 0) runner.log(' pins already match');
223
+ writeFileSync(packageFile, moved.text);
224
+ let sdkRoot: string;
225
+ try {
226
+ // 2. Install, then confirm pnpm installed what the pins say.
227
+ try { runner.run('pnpm', ['install'], project); }
228
+ catch (error) { throw new Error(`update --pins: pnpm install failed on @wildshard/sdk ${release.version}`, { cause: error }); }
229
+ const installed = installedVersion(project, '@wildshard/sdk');
230
+ if (installed !== release.version) throw new Error(`update --pins: pnpm installed @wildshard/sdk ${installed ?? 'nothing'}, not ${release.version}`);
231
+ // A repo that lists three (not a blender one) must get the exact three the release pins.
232
+ const threePin = release.pins['three'], three = installedVersion(project, 'three');
233
+ if (threePin !== undefined && SEMVER.test(threePin) && listsThree(listed) && three !== threePin) throw new Error(`update --pins: sdk ${release.version} pins three ${threePin}, but ${three ?? 'none'} is installed`);
234
+ sdkRoot = realpathSync(resolve(project, 'node_modules/@wildshard/sdk'));
235
+ // 3. The release's codemods, read from the installed sdk.
236
+ const codemods = await applyCodemods(project, sdkRoot, from, release.version);
237
+ runner.log(codemods.length === 0 ? ` no codemods between ${from} and ${release.version}` : codemods.join('\n'));
238
+ } catch (error) {
239
+ writeFileSync(packageFile, oldText);
240
+ if (oldLock !== undefined) writeFileSync(lockFile, oldLock);
241
+ let back = `package.json and pnpm-lock.yaml are back on @wildshard/sdk ${from}`;
242
+ try { runner.run('pnpm', ['install'], project); } catch { back += ', but pnpm install failed: run it again'; }
243
+ const message = error instanceof Error ? error.message : String(error);
244
+ throw new Error(`${message}\n ${back}; a codemod may have edited src/ before it failed: git diff shows it`, { cause: error });
245
+ }
246
+
247
+ // 4. GUIDE.md and the skills, by the new sdk's own `update` (SA28); 5. its `check`.
248
+ const cli = resolve(sdkRoot, 'bin/wildshard.mjs');
249
+ try { runner.run(process.execPath, [cli, 'update', project], project); }
250
+ catch (error) { throw new Error(`update --pins: the pins moved to @wildshard/sdk ${release.version}, but its wildshard update failed: run pnpm exec wildshard update`, { cause: error }); }
251
+ try { runner.run(process.execPath, [cli, 'check', '.'], project); }
252
+ catch (error) { throw new Error(`update --pins: the pins moved to @wildshard/sdk ${release.version}, but check failed: fix each refusal above, then run wildshard check .`, { cause: error }); }
253
+ runner.log(`wildshard update --pins: on @wildshard/sdk ${release.version}, check pass`);
254
+ }
@@ -1,10 +1,10 @@
1
1
  import { parse, type InferOutput } from 'valibot';
2
2
  import { BowWeaponProfileSchema, HeldBowFileSchema, type HeldBowFileRows } from '@wildshard/format/weaponProfiles';
3
3
  import STARTER_BOW from '@wildshard/engine/game/weapons/starterBow.json' with { type: 'json' };
4
- import type { BowStyle as PlatformBowStyle } from '@wildshard/engine/combat/view/bowProfile';
5
4
 
6
- /** Named transitional bow view strategy styles. */
7
- export type BowStyle = PlatformBowStyle;
5
+ /** Named transitional bow view strategy styles: any name the shard's bow view repaints by (`test/sdk-engine-types.test.ts`
6
+ * keeps it equal to the engine's `combat/view/bowProfile` `BowStyle`). */
7
+ export type BowStyle = string;
8
8
 
9
9
  /** Admit a complete authored bow file before its pool or display strategy is borrowed. */
10
10
  export function parseHeldBowFile(input: unknown): HeldBowFileRows { return parse(HeldBowFileSchema, input); }
@@ -1,13 +1,57 @@
1
1
  import { SWORD_WOOD } from '@wildshard/engine/game/weapons/starterMeleeProfile';
2
- import type { MeleeProfile as PlatformMeleeProfile, ViewmodelFeel as PlatformViewmodelFeel } from '@wildshard/engine/combat/meleeProfile';
2
+ import type { EquipmentIcon, EquipmentTouchMap, WeaponId } from '@wildshard/engine/combat/Equipment';
3
3
  import * as THREE from 'three';
4
4
  import { parse } from 'valibot';
5
5
  import { MeleeWeaponProfileSchema, type MeleeWeaponProfileRows } from '@wildshard/format/weaponProfiles';
6
6
 
7
- /** Authored swept combo and view parameters; ordered contact rows are defined by the format's weaponProfiles module. */
8
- export type MeleeProfile = PlatformMeleeProfile;
9
7
  /** Numeric camera lag, bob and sway parameters, independent of a particular weapon model. */
10
- export type ViewmodelFeel = PlatformViewmodelFeel;
8
+ export interface ViewmodelFeel {
9
+ lag: { gain: number; clampYaw: number; clampPitch: number; k: number; c: number; posYaw: number; posPitch: number };
10
+ bob: { x: number; y: number; rz: number; rx: number };
11
+ sway: { ax: number; fx: number; ay: number; fy: number };
12
+ fovHip: number; portraitFov?: number;
13
+ }
14
+ /** How the held melee model sits in the view: shrink, offset, tilt and yaw. */
15
+ export interface MeleeFraming { shrink: number; dx: number; dy: number; tilt: number; yaw: number }
16
+ /** A held item's menu and HUD presentation. `icon`, `touch` and the slot are the host's declared vocabularies (the engine's
17
+ * `EquipmentIconMap`, `EquipmentTouchMap` and `EquipmentSlotMap`, filled by declaration merging). */
18
+ export interface EquipmentUi {
19
+ name: string; icon: EquipmentIcon;
20
+ /** Magazine readouts offer touch reload; quivers keep their passive ammo chip. */
21
+ ammo?: { label: string; segments: number; magazine?: boolean; bagLabel?: string; bagLabelFor?: string };
22
+ inputContext?: string;
23
+ touch: keyof EquipmentTouchMap;
24
+ lockOn: boolean; melee: boolean; tracers: boolean;
25
+ /** The existing 24px swap glyph and short label; menu icons use the shared 64px icon library. */
26
+ swapIcon: string; swapName?: string;
27
+ huntersEye?: boolean;
28
+ }
29
+ /**
30
+ * Authored swept combo and view parameters; ordered contact rows are defined by the format's weaponProfiles module.
31
+ * These are the authored fields of the engine's `combat/meleeProfile` `MeleeProfile`; its `pickup` factory is lent by
32
+ * the runtime host and is not author data. `test/sdk-engine-types.test.ts` keeps the two assignable both ways.
33
+ */
34
+ export interface MeleeProfile {
35
+ id: `weapon.${string}` | `tool.${string}`; legacySlot?: WeaponId;
36
+ ui: EquipmentUi; meta: { name: string; icon: EquipmentIcon; blurb: string; category: string };
37
+ /** Sound cues: fire, reload, impact, and the optional dry, hit, heavy and charge cues. */
38
+ cues?: { fire: `cue.${string}`; reload: `cue.${string}`; impact: `cue.${string}`; dry?: `cue.${string}`; hit?: `cue.${string}`; heavy?: `cue.${string}`; charge?: Readonly<Record<string, `cue.${string}`>> };
39
+ rangedFeel?: {
40
+ kick: { body: number; head: number; kill: number; side: number; killSide: number };
41
+ trauma: { kill: number; head: number; killKinds: readonly string[]; headKinds: readonly string[] };
42
+ };
43
+ hitStop?: { body: number; head: number; kill: number };
44
+ tags?: readonly `${string}.${string}`[];
45
+ family: 'melee'; parent?: string;
46
+ damage: number; reach: number; swingScale: number;
47
+ portraitPullX: number; framing: MeleeFraming; feel: ViewmodelFeel;
48
+ moves?: MeleeMoveSet;
49
+ cooldown: number; comboGap: number; chainLag: number; heavyCharge: number; chargeBlend: number;
50
+ lunge: { range: number; heavyRange: number; cone: number; stop: number; speed: number; minTime: number; maxTime: number };
51
+ sweep: { rays: number; extensions: readonly number[]; step: number; maxSamples: number; maxHits: number };
52
+ trail: { samples: number; subdivisions: number };
53
+ dodgeKick: { kick: number; k: number; c: number }; armFollow: number;
54
+ }
11
55
 
12
56
  /** An authored hand pose, independent of a live weapon controller. */
13
57
  export interface MeleeKey { t: number; pos: THREE.Vector3; q: THREE.Quaternion }
@@ -2,7 +2,7 @@ import { parseWorldScenePage } from '@wildshard/format/worldScenePages';
2
2
  import { SceneModelSourceSchema, SceneBakeSourceSchema } from '@wildshard/format/sceneSources';
3
3
  import type { BakedPlacementPlan } from '@wildshard/format/bakedTiles';
4
4
  import { isJsonData } from '@wildshard/format/json';
5
- import { namedJsonSchema, registeredJsonSchema } from '@wildshard/engine/host/formatJsonSchema';
5
+ import { namedJsonSchema, registeredJsonSchema } from './formatJsonSchema';
6
6
  import type { RegisteredScenePageJsonName, RegisteredPlacementPageJsonName } from '@wildshard/format/registeredJson';
7
7
  import { parseWorldScene, parseWorldSceneBindings, parsePrivateScene, type WorldSceneRecipe } from '@wildshard/format/clientChannels';
8
8
  import { CaveInteriorSchema, type CaveInteriorRows } from '@wildshard/format/caveInterior';
@@ -12,6 +12,7 @@
12
12
  "src/sharddev/**/*.mts",
13
13
  "src/commons/**/*.ts",
14
14
  "test/graph-scene-author-types.test.ts",
15
+ "test/sdk-engine-types.test.ts",
15
16
  "node_modules/@wildshard/engine/src/*/engine/**/*.d.ts",
16
17
  "node_modules/@wildshard/engine/src/*/game/**/*.merge.d.ts"
17
18
  ],