@bluemoonfoundry/daz-ts 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +377 -2
  3. package/dist/animation.d.ts +129 -0
  4. package/dist/animation.js +276 -0
  5. package/dist/batch.d.ts +118 -0
  6. package/dist/batch.js +186 -0
  7. package/dist/bone.d.ts +50 -0
  8. package/dist/bone.js +66 -0
  9. package/dist/camera.d.ts +61 -0
  10. package/dist/camera.js +120 -0
  11. package/dist/cinematics.d.ts +188 -0
  12. package/dist/cinematics.js +165 -0
  13. package/dist/client.d.ts +399 -0
  14. package/dist/client.js +769 -0
  15. package/dist/dforce.d.ts +15 -0
  16. package/dist/dforce.js +36 -0
  17. package/dist/element.d.ts +51 -0
  18. package/dist/element.js +141 -0
  19. package/dist/exceptions.d.ts +124 -0
  20. package/dist/exceptions.js +173 -0
  21. package/dist/geometry.d.ts +81 -0
  22. package/dist/geometry.js +433 -0
  23. package/dist/index.d.ts +50 -0
  24. package/dist/index.js +36 -0
  25. package/dist/light.d.ts +24 -0
  26. package/dist/light.js +40 -0
  27. package/dist/lighting.d.ts +120 -0
  28. package/dist/lighting.js +107 -0
  29. package/dist/material.d.ts +27 -0
  30. package/dist/material.js +63 -0
  31. package/dist/materials.d.ts +107 -0
  32. package/dist/materials.js +165 -0
  33. package/dist/math3.d.ts +204 -0
  34. package/dist/math3.js +502 -0
  35. package/dist/modifier.d.ts +14 -0
  36. package/dist/modifier.js +24 -0
  37. package/dist/morph.d.ts +11 -0
  38. package/dist/morph.js +24 -0
  39. package/dist/node.d.ts +196 -0
  40. package/dist/node.js +447 -0
  41. package/dist/polling.d.ts +24 -0
  42. package/dist/polling.js +50 -0
  43. package/dist/pose.d.ts +82 -0
  44. package/dist/pose.js +295 -0
  45. package/dist/poses.d.ts +54 -0
  46. package/dist/poses.js +40 -0
  47. package/dist/property.d.ts +64 -0
  48. package/dist/property.js +125 -0
  49. package/dist/render.d.ts +242 -0
  50. package/dist/render.js +811 -0
  51. package/dist/renderApi.d.ts +124 -0
  52. package/dist/renderApi.js +235 -0
  53. package/dist/result.d.ts +15 -0
  54. package/dist/result.js +1 -0
  55. package/dist/scene.d.ts +154 -0
  56. package/dist/scene.js +584 -0
  57. package/dist/sceneEvents.d.ts +63 -0
  58. package/dist/sceneEvents.js +102 -0
  59. package/dist/sceneState.d.ts +167 -0
  60. package/dist/sceneState.js +430 -0
  61. package/dist/scriptBuilder.d.ts +41 -0
  62. package/dist/scriptBuilder.js +72 -0
  63. package/dist/shotGeometry.d.ts +49 -0
  64. package/dist/shotGeometry.js +76 -0
  65. package/dist/skeleton.d.ts +120 -0
  66. package/dist/skeleton.js +561 -0
  67. package/dist/timeline.d.ts +24 -0
  68. package/dist/timeline.js +39 -0
  69. package/dist/undo.d.ts +24 -0
  70. package/dist/undo.js +45 -0
  71. package/dist/version.d.ts +31 -0
  72. package/dist/version.js +36 -0
  73. package/dist/viewport.d.ts +58 -0
  74. package/dist/viewport.js +239 -0
  75. package/package.json +52 -4
@@ -0,0 +1,276 @@
1
+ /**
2
+ * A captured animation clip: bone rotations (and optionally morphs) for
3
+ * every frame in the play range. Mirrors dazpy's `_animation.py`.
4
+ */
5
+ import * as fs from "node:fs";
6
+ import { NodeNotFoundError } from "./exceptions.js";
7
+ import { DazPose } from "./pose.js";
8
+ import { ScriptBuilder } from "./scriptBuilder.js";
9
+ /**
10
+ * A captured animation clip: bone rotations (and optionally morphs) for
11
+ * every frame in the play range.
12
+ *
13
+ * Created with {@link capture}; saved/loaded with {@link save}/{@link load}.
14
+ *
15
+ * Bones are stored as a parallel-list encoding -- a single ordered `bones`
16
+ * list of names, and per-frame `rotations` arrays aligned to that index --
17
+ * so payload size grows with bones x frames rather than with a full dict
18
+ * per frame.
19
+ *
20
+ * Typical workflow:
21
+ * ```ts
22
+ * const scene = new DazScene();
23
+ * const figure = await scene.findSkeletonByLabel("Genesis 9");
24
+ *
25
+ * const anim = await DazAnimation.capture(figure, true);
26
+ * anim.save("walk.json");
27
+ * ```
28
+ */
29
+ export class DazAnimation {
30
+ figure;
31
+ frameRange;
32
+ bones;
33
+ frames;
34
+ constructor(figure, frameRange, bones, frames) {
35
+ this.figure = figure;
36
+ this.frameRange = frameRange;
37
+ this.bones = bones;
38
+ this.frames = frames;
39
+ }
40
+ // ── construction ──────────────────────────────────────────────────────
41
+ /**
42
+ * Capture the full animation of `skeleton` in a single HTTP call.
43
+ *
44
+ * Scrubs every frame in the scene's play range server-side (no round-trip
45
+ * per frame). The timeline is restored to its original frame before the
46
+ * call returns.
47
+ *
48
+ * When `includeMorphs` is `true`, the script first identifies which
49
+ * geometry morphs and node-level properties actually vary across the
50
+ * timeline (channels that are keyed but static are excluded), then
51
+ * records their values per frame.
52
+ *
53
+ * @throws NodeNotFoundError If the skeleton is not found.
54
+ */
55
+ static async capture(skeleton, includeMorphs = false) {
56
+ const lookup = ScriptBuilder.skeletonLookup(skeleton.identifier);
57
+ const includeMorphsJs = includeMorphs ? "true" : "false";
58
+ const script = ScriptBuilder.iife(`
59
+ ${lookup}
60
+ if (!_skel) return null;
61
+
62
+ var _origFrame = Scene.getFrame();
63
+
64
+ var allBones = _skel.getAllBones();
65
+ var boneNames = [];
66
+ for (var i = 0; i < allBones.length; i++) boneNames.push(allBones[i].getName());
67
+
68
+ // Detect channels whose values actually vary across the timeline.
69
+ // Channels that are keyed but hold a constant value are excluded --
70
+ // they add payload without contributing animation data.
71
+ function isVaryingMorph(ch) {
72
+ var n = ch.getNumKeys();
73
+ if (n < 2) return false;
74
+ var first = ch.getKeyValue(0);
75
+ for (var k = 1; k < n; k++) {
76
+ if (Math.abs(ch.getKeyValue(k) - first) > 0.0001) return true;
77
+ }
78
+ return false;
79
+ }
80
+
81
+ var animatedChannels = [];
82
+ if (${includeMorphsJs}) {
83
+ var obj = _skel.getObject();
84
+ if (obj) {
85
+ for (var i = 0; i < obj.getNumModifiers(); i++) {
86
+ var m = obj.getModifier(i);
87
+ if (m.className() === "DzMorph" && isVaryingMorph(m.getValueChannel()))
88
+ animatedChannels.push([m.getName(), m.getValueChannel()]);
89
+ }
90
+ }
91
+ for (var i = 0; i < _skel.getNumProperties(); i++) {
92
+ var p = _skel.getProperty(i);
93
+ if (p && p.getNumKeys && isVaryingMorph(p))
94
+ animatedChannels.push([p.getName(), p]);
95
+ }
96
+ }
97
+
98
+ var step = Scene.getTimeStep();
99
+ var range = Scene.getPlayRange();
100
+ var start = Math.round(range.start / step);
101
+ var end = Math.round(range.end / step);
102
+
103
+ var frames = [];
104
+ for (var f = start; f <= end; f++) {
105
+ Scene.setFrame(f);
106
+
107
+ var rotations = [];
108
+ for (var i = 0; i < allBones.length; i++) {
109
+ var b = allBones[i];
110
+ rotations.push([
111
+ b.getXRotControl().getValue(),
112
+ b.getYRotControl().getValue(),
113
+ b.getZRotControl().getValue()
114
+ ]);
115
+ }
116
+
117
+ var morphs = {};
118
+ for (var i = 0; i < animatedChannels.length; i++) {
119
+ var v = animatedChannels[i][1].getValue();
120
+ if (Math.abs(v) > 0.0001) morphs[animatedChannels[i][0]] = v;
121
+ }
122
+
123
+ frames.push({frame: f, rotations: rotations, morphs: morphs});
124
+ }
125
+
126
+ Scene.setFrame(_origFrame);
127
+
128
+ return {
129
+ figure: _skel.getLabel(),
130
+ frame_range: {start: start, end: end},
131
+ bones: boneNames,
132
+ frames: frames
133
+ };
134
+ `);
135
+ const result = (await skeleton.getClient().execute(script)).value;
136
+ if (result === null) {
137
+ throw new NodeNotFoundError(`Skeleton not found: ${JSON.stringify(skeleton.identifier.value)}`);
138
+ }
139
+ return new DazAnimation(result.figure, result.frame_range, result.bones, result.frames);
140
+ }
141
+ /** Load an animation from a JSON file. Accepts files produced by {@link save}. */
142
+ static load(path) {
143
+ const data = JSON.parse(fs.readFileSync(path, "utf-8"));
144
+ return new DazAnimation(data.figure ?? "", data.frame_range ?? { start: 0, end: 0 }, data.bones ?? [], data.frames ?? []);
145
+ }
146
+ // ── serialisation ─────────────────────────────────────────────────────
147
+ /** Write this animation to a JSON file. Parent directories must exist. */
148
+ save(path) {
149
+ fs.writeFileSync(path, JSON.stringify(this.toDict(), null, 2), "utf-8");
150
+ }
151
+ /** Return the animation as a plain dict (same schema as the JSON file). */
152
+ toDict() {
153
+ return { figure: this.figure, frame_range: this.frameRange, bones: this.bones, frames: this.frames };
154
+ }
155
+ // ── clip operations ───────────────────────────────────────────────────
156
+ /**
157
+ * Return a new animation containing only frames in [start, end].
158
+ *
159
+ * `start` and `end` are scene frame numbers (the `frame` value stored in
160
+ * each frame, not array indices). Both endpoints are inclusive.
161
+ */
162
+ clip(start, end) {
163
+ const frames = this.frames.filter((f) => start <= f.frame && f.frame <= end);
164
+ const newStart = frames.length > 0 ? frames[0].frame : start;
165
+ const newEnd = frames.length > 0 ? frames[frames.length - 1].frame : end;
166
+ return new DazAnimation(this.figure, { start: newStart, end: newEnd }, this.bones, frames);
167
+ }
168
+ /**
169
+ * Blend this animation with `other` frame by frame.
170
+ *
171
+ * Each frame's bone rotations and morph values are linearly interpolated
172
+ * between `this` (`t=0`) and `other` (`t=1`). Pure -- no HTTP round-trip.
173
+ *
174
+ * If the two clips have different frame counts, the result is truncated
175
+ * to the shorter clip. Frame numbers are taken from `this`.
176
+ *
177
+ * @throws Error If `this` and `other` have different bone lists.
178
+ */
179
+ blend(other, t) {
180
+ if (JSON.stringify(this.bones) !== JSON.stringify(other.bones)) {
181
+ throw new Error(`Cannot blend animations with different bone lists (${this.bones.length} vs ${other.bones.length} bones)`);
182
+ }
183
+ const s = 1.0 - t;
184
+ const frames = [];
185
+ const n = Math.min(this.frames.length, other.frames.length);
186
+ for (let i = 0; i < n; i++) {
187
+ const fa = this.frames[i];
188
+ const fb = other.frames[i];
189
+ const rotations = this.bones.map((_, bi) => [
190
+ fa.rotations[bi][0] * s + fb.rotations[bi][0] * t,
191
+ fa.rotations[bi][1] * s + fb.rotations[bi][1] * t,
192
+ fa.rotations[bi][2] * s + fb.rotations[bi][2] * t,
193
+ ]);
194
+ const morphs = {};
195
+ for (const k of new Set([...Object.keys(fa.morphs), ...Object.keys(fb.morphs)])) {
196
+ const v = (fa.morphs[k] ?? 0.0) * s + (fb.morphs[k] ?? 0.0) * t;
197
+ if (Math.abs(v) > 1e-9)
198
+ morphs[k] = v;
199
+ }
200
+ frames.push({ frame: fa.frame, rotations, morphs });
201
+ }
202
+ const newEnd = frames.length > 0 ? frames[frames.length - 1].frame : this.frameRange.start;
203
+ return new DazAnimation(this.figure, { start: this.frameRange.start, end: newEnd }, this.bones, frames);
204
+ }
205
+ /**
206
+ * Extract a single frame as a {@link DazPose}.
207
+ *
208
+ * Bone rotations are stored sparsely -- only bones with at least one
209
+ * non-zero component are included. Morph values are copied as-is. Pure --
210
+ * no HTTP round-trip.
211
+ *
212
+ * @param frameIndex 0-based index into {@link frames}.
213
+ */
214
+ asPose(frameIndex = 0) {
215
+ const frame = this.frames[frameIndex];
216
+ const bones = {};
217
+ this.bones.forEach((name, i) => {
218
+ const rot = frame.rotations[i];
219
+ if (rot.some((v) => Math.abs(v) > 1e-9)) {
220
+ bones[name] = rot;
221
+ }
222
+ });
223
+ return new DazPose(this.figure, bones, { ...frame.morphs }, {});
224
+ }
225
+ /**
226
+ * Apply a single frame of this animation to `skeleton`.
227
+ *
228
+ * Equivalent to `(await anim.asPose(frameIndex)).apply(skeleton)` -- one
229
+ * HTTP call that sets only the channels present in the frame.
230
+ *
231
+ * @param frameIndex 0-based index into {@link frames}. Defaults to 0.
232
+ */
233
+ async apply(skeleton, frameIndex = 0) {
234
+ await this.asPose(frameIndex).apply(skeleton);
235
+ }
236
+ /**
237
+ * Concatenate `other` immediately after this animation.
238
+ *
239
+ * The other clip's frame numbers are shifted so it starts on the frame
240
+ * following this animation's last frame. The figure label and bone list
241
+ * are taken from `this`. Pure -- no HTTP round-trip.
242
+ *
243
+ * @throws Error If `this` and `other` have different bone lists.
244
+ */
245
+ append(other) {
246
+ if (JSON.stringify(this.bones) !== JSON.stringify(other.bones)) {
247
+ throw new Error(`Cannot append animations with different bone lists (${this.bones.length} vs ${other.bones.length} bones)`);
248
+ }
249
+ if (this.frames.length === 0) {
250
+ return new DazAnimation(this.figure, { ...other.frameRange }, [...other.bones], [...other.frames]);
251
+ }
252
+ const offset = this.frameRange.end + 1 - other.frameRange.start;
253
+ const otherFrames = other.frames.map((f) => ({
254
+ frame: f.frame + offset,
255
+ rotations: f.rotations,
256
+ morphs: f.morphs,
257
+ }));
258
+ const frames = [...this.frames, ...otherFrames];
259
+ return new DazAnimation(this.figure, { start: this.frameRange.start, end: frames[frames.length - 1].frame }, this.bones, frames);
260
+ }
261
+ // ── convenience ───────────────────────────────────────────────────────
262
+ /** Number of captured frames. */
263
+ get frameCount() {
264
+ return this.frames.length;
265
+ }
266
+ /** Number of bones in the skeleton at capture time. */
267
+ get boneCount() {
268
+ return this.bones.length;
269
+ }
270
+ // ── dunder ────────────────────────────────────────────────────────────
271
+ toString() {
272
+ return (`DazAnimation(figure=${JSON.stringify(this.figure)}, ` +
273
+ `frames=${this.frameCount}, bones=${this.boneCount}, ` +
274
+ `range=${this.frameRange.start}–${this.frameRange.end})`);
275
+ }
276
+ }
@@ -0,0 +1,118 @@
1
+ import type { DazClient } from "./client.js";
2
+ export declare const DEFAULT_MAX_OPERATIONS = 500;
3
+ export declare const DEFAULT_MAX_SCRIPT_LENGTH = 900000;
4
+ /**
5
+ * Build one IIFE script from a list of `[bodyLines, resultExpression]` pairs.
6
+ *
7
+ * Shared by {@link Batch}'s internal script builder and
8
+ * {@link DazClient.executeBatchAsync} so both produce scripts with an
9
+ * identical shape (keyed return object over `_r0`, `_r1`, ...).
10
+ *
11
+ * @param operations - `[bodyLines, resultExpression]` pairs, in submission order.
12
+ * @param preludeLines - Optional shared setup lines emitted once, before any
13
+ * operation's lines. Used by {@link Batch}, which deduplicates its preludes
14
+ * before passing them here; `executeBatchAsync` has no preludes and omits this.
15
+ */
16
+ export declare function buildOperationsScript(operations: Array<[string[], string]>, preludeLines?: string[]): string;
17
+ /**
18
+ * Placeholder for a single result within a {@link Batch} execution.
19
+ *
20
+ * Created by {@link Batch.add} or {@link Batch.addOperation}; the `value`
21
+ * getter throws until the batch has been executed.
22
+ */
23
+ export declare class BatchFuture {
24
+ private readonly key;
25
+ private resolved;
26
+ private resultValue;
27
+ constructor(key: string);
28
+ /** The result value. Throws if {@link Batch.execute} has not been called yet. */
29
+ get value(): unknown;
30
+ /** @internal */
31
+ _resolve(value: unknown): void;
32
+ /** @internal */
33
+ get _key(): string;
34
+ }
35
+ /** Options accepted by the {@link Batch} constructor. */
36
+ export interface BatchOptions {
37
+ /** Max queued operations before {@link Batch.add}/{@link Batch.addOperation} throw {@link BatchLimitExceededError}. */
38
+ maxOperations?: number;
39
+ /** Max generated script length (characters) before {@link Batch.execute} throws {@link BatchLimitExceededError}. */
40
+ maxScriptLength?: number;
41
+ }
42
+ /**
43
+ * Collect multiple DazScript operations and execute them in a single HTTP round-trip.
44
+ *
45
+ * Semantics (preserved exactly from dazpy, do not "improve" silently):
46
+ * execution is **serial**, there is **no parallelism**, and the batch is
47
+ * **not transactional** — if any operation throws, the whole call fails
48
+ * the same way a single failing `execute()` call would, and earlier
49
+ * mutations already applied to the live scene are **not** rolled back.
50
+ * Order destructive/hard-to-recover operations last.
51
+ *
52
+ * @example
53
+ * ```ts
54
+ * const batch = new Batch(client);
55
+ * const posFuture = batch.addOperation(
56
+ * ["var n = Scene.findNode('Figure');", "var p = [n.getWSPos().x, n.getWSPos().y, n.getWSPos().z];"],
57
+ * "p",
58
+ * );
59
+ * await batch.execute();
60
+ * console.log(posFuture.value);
61
+ * ```
62
+ */
63
+ export declare class Batch {
64
+ private readonly client;
65
+ private readonly ops;
66
+ private readonly preludes;
67
+ private readonly preludeOrder;
68
+ private counter;
69
+ private readonly maxOperations;
70
+ private readonly maxScriptLength;
71
+ constructor(client: DazClient, options?: BatchOptions);
72
+ /**
73
+ * Queue DazScript lines to be included in the batch.
74
+ *
75
+ * The last line in `lines` should assign the desired result to a
76
+ * variable named after the internally generated key (`_r0`, `_r1`, ...
77
+ * in call order). Prefer {@link addOperation}, which does not require
78
+ * guessing the key name.
79
+ *
80
+ * @throws {BatchLimitExceededError} If this call would exceed `maxOperations`.
81
+ */
82
+ add(lines: string[]): BatchFuture;
83
+ /**
84
+ * Register a shared setup block, emitted once per unique `preludeKey`.
85
+ *
86
+ * Call this before {@link addOperation} calls whose bodies depend on the
87
+ * prelude's bound variable(s). Repeated calls with the same `preludeKey`
88
+ * are no-ops after the first.
89
+ */
90
+ addPrelude(preludeKey: string, lines: string[]): void;
91
+ /**
92
+ * Queue an operation whose result the builder assigns internally.
93
+ *
94
+ * @param bodyLines - DazScript source lines with no trailing result assignment.
95
+ * @param resultExpression - A JS expression evaluated once after `bodyLines`
96
+ * run, used as this operation's result. Mutation-only operations should pass `"null"`.
97
+ * @throws {BatchLimitExceededError} If this call would exceed `maxOperations`.
98
+ */
99
+ addOperation(bodyLines: string[], resultExpression: string): BatchFuture;
100
+ private checkOperationLimit;
101
+ /**
102
+ * Build the combined script for this batch: shared preludes followed by
103
+ * every operation, via the same "operations → keyed return object → IIFE"
104
+ * builder used by {@link buildOperationsScript} (and, in turn,
105
+ * `DazClient.executeBatchAsync`). `this.ops` is always appended to in
106
+ * counter order, so array index `i` and each op's own `_r${i}` key line up
107
+ * exactly with the `_r${i}` keys `buildOperationsScript` generates from
108
+ * the array position.
109
+ */
110
+ private buildScript;
111
+ /**
112
+ * Execute all queued operations in a single HTTP request and resolve every future.
113
+ *
114
+ * @throws {BatchLimitExceededError} If the generated script exceeds
115
+ * `maxScriptLength`. Raised before any HTTP call.
116
+ */
117
+ execute(): Promise<void>;
118
+ }
package/dist/batch.js ADDED
@@ -0,0 +1,186 @@
1
+ import { BatchLimitExceededError } from "./exceptions.js";
2
+ export const DEFAULT_MAX_OPERATIONS = 500;
3
+ export const DEFAULT_MAX_SCRIPT_LENGTH = 900_000; // stays under the server's default 1MB script cap
4
+ /**
5
+ * Build one IIFE script from a list of `[bodyLines, resultExpression]` pairs.
6
+ *
7
+ * Shared by {@link Batch}'s internal script builder and
8
+ * {@link DazClient.executeBatchAsync} so both produce scripts with an
9
+ * identical shape (keyed return object over `_r0`, `_r1`, ...).
10
+ *
11
+ * @param operations - `[bodyLines, resultExpression]` pairs, in submission order.
12
+ * @param preludeLines - Optional shared setup lines emitted once, before any
13
+ * operation's lines. Used by {@link Batch}, which deduplicates its preludes
14
+ * before passing them here; `executeBatchAsync` has no preludes and omits this.
15
+ */
16
+ export function buildOperationsScript(operations, preludeLines = []) {
17
+ const bodyLines = [...preludeLines];
18
+ const returnParts = [];
19
+ operations.forEach(([lines, resultExpression], i) => {
20
+ const key = `_r${i}`;
21
+ bodyLines.push(...lines);
22
+ bodyLines.push(`var ${key} = ${resultExpression};`);
23
+ returnParts.push(`"${key}": ${key}`);
24
+ });
25
+ const returnObj = `{${returnParts.join(", ")}}`;
26
+ bodyLines.push(`return ${returnObj};`);
27
+ const body = bodyLines.join("\n");
28
+ return `(function(){\n${body}\n})()`;
29
+ }
30
+ /**
31
+ * Placeholder for a single result within a {@link Batch} execution.
32
+ *
33
+ * Created by {@link Batch.add} or {@link Batch.addOperation}; the `value`
34
+ * getter throws until the batch has been executed.
35
+ */
36
+ export class BatchFuture {
37
+ key;
38
+ resolved = false;
39
+ resultValue = undefined;
40
+ constructor(key) {
41
+ this.key = key;
42
+ }
43
+ /** The result value. Throws if {@link Batch.execute} has not been called yet. */
44
+ get value() {
45
+ if (!this.resolved) {
46
+ throw new Error("Batch has not been executed yet");
47
+ }
48
+ return this.resultValue;
49
+ }
50
+ /** @internal */
51
+ _resolve(value) {
52
+ this.resultValue = value;
53
+ this.resolved = true;
54
+ }
55
+ /** @internal */
56
+ get _key() {
57
+ return this.key;
58
+ }
59
+ }
60
+ /**
61
+ * Collect multiple DazScript operations and execute them in a single HTTP round-trip.
62
+ *
63
+ * Semantics (preserved exactly from dazpy, do not "improve" silently):
64
+ * execution is **serial**, there is **no parallelism**, and the batch is
65
+ * **not transactional** — if any operation throws, the whole call fails
66
+ * the same way a single failing `execute()` call would, and earlier
67
+ * mutations already applied to the live scene are **not** rolled back.
68
+ * Order destructive/hard-to-recover operations last.
69
+ *
70
+ * @example
71
+ * ```ts
72
+ * const batch = new Batch(client);
73
+ * const posFuture = batch.addOperation(
74
+ * ["var n = Scene.findNode('Figure');", "var p = [n.getWSPos().x, n.getWSPos().y, n.getWSPos().z];"],
75
+ * "p",
76
+ * );
77
+ * await batch.execute();
78
+ * console.log(posFuture.value);
79
+ * ```
80
+ */
81
+ export class Batch {
82
+ client;
83
+ ops = [];
84
+ preludes = new Map();
85
+ preludeOrder = [];
86
+ counter = 0;
87
+ maxOperations;
88
+ maxScriptLength;
89
+ constructor(client, options = {}) {
90
+ this.client = client;
91
+ this.maxOperations = options.maxOperations ?? DEFAULT_MAX_OPERATIONS;
92
+ this.maxScriptLength = options.maxScriptLength ?? DEFAULT_MAX_SCRIPT_LENGTH;
93
+ }
94
+ /**
95
+ * Queue DazScript lines to be included in the batch.
96
+ *
97
+ * The last line in `lines` should assign the desired result to a
98
+ * variable named after the internally generated key (`_r0`, `_r1`, ...
99
+ * in call order). Prefer {@link addOperation}, which does not require
100
+ * guessing the key name.
101
+ *
102
+ * @throws {BatchLimitExceededError} If this call would exceed `maxOperations`.
103
+ */
104
+ add(lines) {
105
+ this.checkOperationLimit();
106
+ const key = `_r${this.counter++}`;
107
+ const future = new BatchFuture(key);
108
+ // `lines` is expected to already assign `key` itself, so the result
109
+ // "expression" fed to the shared builder is just the key it already holds.
110
+ this.ops.push({ key, lines: [...lines], resultExpression: key, future });
111
+ return future;
112
+ }
113
+ /**
114
+ * Register a shared setup block, emitted once per unique `preludeKey`.
115
+ *
116
+ * Call this before {@link addOperation} calls whose bodies depend on the
117
+ * prelude's bound variable(s). Repeated calls with the same `preludeKey`
118
+ * are no-ops after the first.
119
+ */
120
+ addPrelude(preludeKey, lines) {
121
+ if (!this.preludes.has(preludeKey)) {
122
+ this.preludes.set(preludeKey, [...lines]);
123
+ this.preludeOrder.push(preludeKey);
124
+ }
125
+ }
126
+ /**
127
+ * Queue an operation whose result the builder assigns internally.
128
+ *
129
+ * @param bodyLines - DazScript source lines with no trailing result assignment.
130
+ * @param resultExpression - A JS expression evaluated once after `bodyLines`
131
+ * run, used as this operation's result. Mutation-only operations should pass `"null"`.
132
+ * @throws {BatchLimitExceededError} If this call would exceed `maxOperations`.
133
+ */
134
+ addOperation(bodyLines, resultExpression) {
135
+ this.checkOperationLimit();
136
+ const key = `_r${this.counter++}`;
137
+ const future = new BatchFuture(key);
138
+ this.ops.push({ key, lines: [...bodyLines], resultExpression, future });
139
+ return future;
140
+ }
141
+ checkOperationLimit() {
142
+ if (this.ops.length >= this.maxOperations) {
143
+ throw new BatchLimitExceededError(`Batch already has ${this.ops.length} operations (maxOperations=${this.maxOperations})`);
144
+ }
145
+ }
146
+ /**
147
+ * Build the combined script for this batch: shared preludes followed by
148
+ * every operation, via the same "operations → keyed return object → IIFE"
149
+ * builder used by {@link buildOperationsScript} (and, in turn,
150
+ * `DazClient.executeBatchAsync`). `this.ops` is always appended to in
151
+ * counter order, so array index `i` and each op's own `_r${i}` key line up
152
+ * exactly with the `_r${i}` keys `buildOperationsScript` generates from
153
+ * the array position.
154
+ */
155
+ buildScript() {
156
+ const preludeLines = [];
157
+ for (const preludeKey of this.preludeOrder) {
158
+ preludeLines.push(...(this.preludes.get(preludeKey) ?? []));
159
+ }
160
+ const operations = this.ops.map(({ lines, resultExpression }) => [
161
+ lines,
162
+ resultExpression,
163
+ ]);
164
+ return buildOperationsScript(operations, preludeLines);
165
+ }
166
+ /**
167
+ * Execute all queued operations in a single HTTP request and resolve every future.
168
+ *
169
+ * @throws {BatchLimitExceededError} If the generated script exceeds
170
+ * `maxScriptLength`. Raised before any HTTP call.
171
+ */
172
+ async execute() {
173
+ if (this.ops.length === 0) {
174
+ return;
175
+ }
176
+ const script = this.buildScript();
177
+ if (script.length > this.maxScriptLength) {
178
+ throw new BatchLimitExceededError(`Generated batch script is ${script.length} characters (maxScriptLength=${this.maxScriptLength})`);
179
+ }
180
+ const result = await this.client.execute(script);
181
+ const data = result.value ?? {};
182
+ for (const { key, future } of this.ops) {
183
+ future._resolve(data[key]);
184
+ }
185
+ }
186
+ }
package/dist/bone.d.ts ADDED
@@ -0,0 +1,50 @@
1
+ import type { DazClient } from "./client.js";
2
+ import { DazNode, type NodeIdentifier } from "./node.js";
3
+ /**
4
+ * Proxy for a `DzBone` (a single joint within a {@link DazSkeleton}).
5
+ * Extends `DazNode` with bone-specific rotation helpers.
6
+ *
7
+ * Resolution note: only this class's own overrides — `localEuler`,
8
+ * `localRotation`, `setLocalRotation`, `localPosition`, `rotationOrder`, and
9
+ * `getSkeleton` (all routed through the private `nb()` helper) — resolve via
10
+ * the skeleton-relative `locator` passed to {@link fromLocator}. Every method
11
+ * `DazBone` inherits from `DazNode` without overriding (e.g. `position`,
12
+ * `setPosition`, `setRotation`, `label`, `select`, `parent`, `children`,
13
+ * `modifiers`, `materials`, ...) resolves via `this.identifier` instead — a
14
+ * scene-wide `Scene.findNode()`-style lookup that ignores the locator. See
15
+ * the constructor overload doc on `DazNode` for details.
16
+ */
17
+ export declare class DazBone extends DazNode {
18
+ /**
19
+ * Construct from a standard scene node lookup by identifier.
20
+ */
21
+ constructor(client: DazClient, identifier: NodeIdentifier);
22
+ /**
23
+ * Construct from a pre-built skeleton-relative locator (used by {@link fromLocator}).
24
+ * The identifier's value provides the bone's name.
25
+ */
26
+ constructor(client: DazClient, identifier: NodeIdentifier, locator: string);
27
+ /** Construct a `DazBone` from a pre-built skeleton-relative locator (see `DazSkeleton`'s bone lookup). */
28
+ static fromLocator(client: DazClient, locator: string, name: string): DazBone;
29
+ private nb;
30
+ /** Local-space rotation as `(x, y, z)` Euler degrees; exact inverse of {@link setLocalRotation}. */
31
+ localEuler(): Promise<[number, number, number] | null>;
32
+ /** Local-space rotation as `{x, y, z, w}` quaternion (read-only). */
33
+ localRotation(): Promise<{
34
+ x: number;
35
+ y: number;
36
+ z: number;
37
+ w: number;
38
+ } | null>;
39
+ setLocalRotation(x: number, y: number, z: number): Promise<void>;
40
+ /** Local-space position as `{x, y, z}` (read-only). */
41
+ localPosition(): Promise<{
42
+ x: number;
43
+ y: number;
44
+ z: number;
45
+ } | null>;
46
+ /** Rotation order string (e.g. `"XYZ"`), or `null`. */
47
+ rotationOrder(): Promise<string | null>;
48
+ /** The parent skeleton, or `null`. */
49
+ getSkeleton(): Promise<import("./skeleton.js").DazSkeleton | null>;
50
+ }