@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
package/dist/pose.js ADDED
@@ -0,0 +1,295 @@
1
+ /**
2
+ * A snapshot of a figure's complete pose state. Mirrors dazpy's `_pose.py`.
3
+ */
4
+ import * as fs from "node:fs";
5
+ import { NodeNotFoundError } from "./exceptions.js";
6
+ import { ScriptBuilder } from "./scriptBuilder.js";
7
+ const ZERO3 = [0, 0, 0];
8
+ function round6(v) {
9
+ return Math.round(v * 1e6) / 1e6;
10
+ }
11
+ /**
12
+ * A snapshot of a figure's complete pose state.
13
+ *
14
+ * Stores bone rotations (Euler XYZ degrees), geometry morph values, and
15
+ * node-level numeric properties. Sparse by default -- zero values are
16
+ * omitted so the object stays compact for morph-heavy figures.
17
+ *
18
+ * Typical workflow:
19
+ * ```ts
20
+ * const scene = new DazScene();
21
+ * const figure = await scene.findSkeletonByLabel("Genesis 9");
22
+ *
23
+ * const neutral = await DazPose.capture(figure);
24
+ * neutral.save("neutral.json");
25
+ *
26
+ * const smile = DazPose.load("smile.json");
27
+ * await neutral.lerp(smile, 0.5).apply(figure);
28
+ * ```
29
+ */
30
+ export class DazPose {
31
+ figure;
32
+ bones;
33
+ morphs;
34
+ props;
35
+ constructor(figure, bones, morphs, props) {
36
+ this.figure = figure;
37
+ this.bones = bones;
38
+ this.morphs = morphs;
39
+ this.props = props;
40
+ }
41
+ // ── construction ──────────────────────────────────────────────────────
42
+ /**
43
+ * Capture the current pose of `skeleton` in a single HTTP call.
44
+ *
45
+ * Records all non-zero bone rotations, morph values, and node-level
46
+ * numeric properties. Zero values are omitted (sparse storage); they are
47
+ * implied as 0.0 during {@link lerp} and {@link applyFull}.
48
+ *
49
+ * @throws NodeNotFoundError If the skeleton is not found.
50
+ */
51
+ static async capture(skeleton) {
52
+ const lookup = ScriptBuilder.skeletonLookup(skeleton.identifier);
53
+ const script = ScriptBuilder.iife(`
54
+ ${lookup}
55
+ if (!_skel) return null;
56
+
57
+ // Bone rotation controls can themselves be ERC targets (e.g.
58
+ // auto-follow bend/twist ratios common on Genesis figures, where
59
+ // one bone's rotation is driven off another's), so read raw
60
+ // values here for the same reason as morphs/props below.
61
+ var bones = {};
62
+ var all = _skel.getAllBones();
63
+ for (var i = 0; i < all.length; i++) {
64
+ var b = all[i];
65
+ var xc = b.getXRotControl(), yc = b.getYRotControl(), zc = b.getZRotControl();
66
+ var x = (typeof xc.getRawValue === "function") ? xc.getRawValue() : xc.getValue();
67
+ var y = (typeof yc.getRawValue === "function") ? yc.getRawValue() : yc.getValue();
68
+ var z = (typeof zc.getRawValue === "function") ? zc.getRawValue() : zc.getValue();
69
+ if (Math.abs(x) > 0.0001 || Math.abs(y) > 0.0001 || Math.abs(z) > 0.0001)
70
+ bones[b.getName()] = [x, y, z];
71
+ }
72
+
73
+ // Morphs can themselves be ERC targets (e.g. a master "Character"
74
+ // dial that fans out to dozens of shape morphs via DzERCLink),
75
+ // so read raw values here for the same reason as props below.
76
+ var morphs = {};
77
+ var obj = _skel.getObject();
78
+ if (obj) {
79
+ for (var i = 0; i < obj.getNumModifiers(); i++) {
80
+ var m = obj.getModifier(i);
81
+ if (m.className() === "DzMorph") {
82
+ var ch = m.getValueChannel();
83
+ var v = (typeof ch.getRawValue === "function") ? ch.getRawValue() : ch.getValue();
84
+ if (Math.abs(v) > 0.0001) morphs[m.getName()] = v;
85
+ }
86
+ }
87
+ }
88
+
89
+ // Read the property's own dial setting rather than getValue()'s
90
+ // post-ERC computed total. Properties driven by DzERCLink
91
+ // controllers (e.g. a "Scale" dial fed by dozens of linked
92
+ // morphs) return a getValue() that already includes every
93
+ // controller's contribution; capturing that and writing it back
94
+ // via setValue() on apply() would re-add the same contributions
95
+ // on top, inflating the property a little more on every
96
+ // capture/apply cycle. getRawValue() reads only the property's
97
+ // own baseline and round-trips correctly regardless of ERC links.
98
+ var props = {};
99
+ for (var i = 0; i < _skel.getNumProperties(); i++) {
100
+ var p = _skel.getProperty(i);
101
+ if (p && p.getValue) {
102
+ var v = (typeof p.getRawValue === "function") ? p.getRawValue() : p.getValue();
103
+ if (typeof v === "number" && Math.abs(v) > 0.0001)
104
+ props[p.getName()] = v;
105
+ }
106
+ }
107
+
108
+ return {bones: bones, morphs: morphs, props: props};
109
+ `);
110
+ const result = (await skeleton.getClient().execute(script)).value;
111
+ if (result === null) {
112
+ throw new NodeNotFoundError(`Skeleton not found: ${JSON.stringify(skeleton.identifier.value)}`);
113
+ }
114
+ return new DazPose(skeleton.identifier.value, result.bones, result.morphs, result.props);
115
+ }
116
+ /** Load a pose from a JSON file. Accepts files produced by {@link save}. */
117
+ static load(path) {
118
+ const data = JSON.parse(fs.readFileSync(path, "utf-8"));
119
+ return new DazPose(data.figure ?? "", data.bones ?? {}, data.morphs ?? {}, data.props ?? {});
120
+ }
121
+ // ── serialisation ─────────────────────────────────────────────────────
122
+ /** Write this pose to a JSON file. Parent directories must exist. */
123
+ save(path) {
124
+ fs.writeFileSync(path, JSON.stringify(this.toDict(), null, 2), "utf-8");
125
+ }
126
+ /** Return the pose as a plain dict (same schema as the JSON file). */
127
+ toDict() {
128
+ return { figure: this.figure, bones: this.bones, morphs: this.morphs, props: this.props };
129
+ }
130
+ static fromDict(data) {
131
+ return new DazPose(data.figure ?? "", data.bones ?? {}, data.morphs ?? {}, data.props ?? {});
132
+ }
133
+ // ── interpolation ─────────────────────────────────────────────────────
134
+ /**
135
+ * Linearly interpolate between this pose and `other`. Missing keys in
136
+ * either pose are treated as zero. The result uses the figure label from
137
+ * `this`. Pure -- no HTTP round-trip.
138
+ *
139
+ * @param t Blend factor. 0.0 = this pose, 1.0 = `other`. Values outside
140
+ * [0, 1] extrapolate.
141
+ */
142
+ lerp(other, t) {
143
+ const l = (a, b) => a + (b - a) * t;
144
+ const bones = {};
145
+ for (const k of new Set([...Object.keys(this.bones), ...Object.keys(other.bones)])) {
146
+ const a = this.bones[k] ?? ZERO3;
147
+ const b = other.bones[k] ?? ZERO3;
148
+ bones[k] = [l(a[0], b[0]), l(a[1], b[1]), l(a[2], b[2])];
149
+ }
150
+ const morphs = {};
151
+ for (const k of new Set([...Object.keys(this.morphs), ...Object.keys(other.morphs)])) {
152
+ morphs[k] = l(this.morphs[k] ?? 0.0, other.morphs[k] ?? 0.0);
153
+ }
154
+ const props = {};
155
+ for (const k of new Set([...Object.keys(this.props), ...Object.keys(other.props)])) {
156
+ props[k] = l(this.props[k] ?? 0.0, other.props[k] ?? 0.0);
157
+ }
158
+ return new DazPose(this.figure, bones, morphs, props);
159
+ }
160
+ // ── apply ─────────────────────────────────────────────────────────────
161
+ /**
162
+ * Apply this pose to `skeleton` in a single HTTP call.
163
+ *
164
+ * Only channels present in the pose are changed. Bones and morphs not
165
+ * stored in the pose are left at their current values. Use
166
+ * {@link applyFull} when you need a clean, authoritative reset to exactly
167
+ * this pose.
168
+ */
169
+ async apply(skeleton, opts = {}) {
170
+ const { retryOnBusy = true, maxWait = 30.0 } = opts;
171
+ const lookup = ScriptBuilder.skeletonLookup(skeleton.identifier);
172
+ const bonesJson = JSON.stringify(Object.fromEntries(Object.entries(this.bones).map(([k, xyz]) => [k, xyz.map(round6)])));
173
+ const morphsJson = JSON.stringify(Object.fromEntries(Object.entries(this.morphs).map(([k, v]) => [k, round6(v)])));
174
+ const propsJson = JSON.stringify(Object.fromEntries(Object.entries(this.props).map(([k, v]) => [k, round6(v)])));
175
+ const script = ScriptBuilder.iife(`
176
+ ${lookup}
177
+ if (!_skel) return false;
178
+ var _bones = ${bonesJson};
179
+ var _morphs = ${morphsJson};
180
+ var _props = ${propsJson};
181
+
182
+ var all = _skel.getAllBones();
183
+ for (var i = 0; i < all.length; i++) {
184
+ var b = all[i];
185
+ var xyz = _bones[b.getName()];
186
+ if (xyz !== undefined) {
187
+ var xc = b.getXRotControl(), yc = b.getYRotControl(), zc = b.getZRotControl();
188
+ if (typeof xc.setRawValue === "function") { xc.setRawValue(xyz[0]); } else { xc.setValue(xyz[0]); }
189
+ if (typeof yc.setRawValue === "function") { yc.setRawValue(xyz[1]); } else { yc.setValue(xyz[1]); }
190
+ if (typeof zc.setRawValue === "function") { zc.setRawValue(xyz[2]); } else { zc.setValue(xyz[2]); }
191
+ }
192
+ }
193
+
194
+ // Write back to the raw dial slot, mirroring capture()'s use of
195
+ // getRawValue() -- see the comment there for why setValue()
196
+ // would double-apply ERC-controller contributions on properties
197
+ // like morphs or a "Scale" dial that are DzERCLink targets.
198
+ var obj = _skel.getObject();
199
+ if (obj) {
200
+ for (var i = 0; i < obj.getNumModifiers(); i++) {
201
+ var m = obj.getModifier(i);
202
+ if (m.className() === "DzMorph") {
203
+ var v = _morphs[m.getName()];
204
+ if (v !== undefined) {
205
+ var ch = m.getValueChannel();
206
+ if (typeof ch.setRawValue === "function") { ch.setRawValue(v); }
207
+ else { ch.setValue(v); }
208
+ }
209
+ }
210
+ }
211
+ }
212
+
213
+ for (var i = 0; i < _skel.getNumProperties(); i++) {
214
+ var p = _skel.getProperty(i);
215
+ if (p && p.setValue) {
216
+ var v = _props[p.getName()];
217
+ if (v !== undefined) {
218
+ if (typeof p.setRawValue === "function") { p.setRawValue(v); }
219
+ else { p.setValue(v); }
220
+ }
221
+ }
222
+ }
223
+
224
+ return true;
225
+ `);
226
+ await skeleton.getClient().execute(script, undefined, { retryOnBusy, maxWait });
227
+ }
228
+ /**
229
+ * Apply this pose and zero every channel not present in the pose.
230
+ *
231
+ * Unlike {@link apply}, every bone rotation, morph, and node property on
232
+ * the skeleton is explicitly set -- channels absent from the pose are
233
+ * driven to zero. Use this to restore a known baseline cleanly.
234
+ */
235
+ async applyFull(skeleton, opts = {}) {
236
+ const { retryOnBusy = true, maxWait = 30.0 } = opts;
237
+ const lookup = ScriptBuilder.skeletonLookup(skeleton.identifier);
238
+ const bonesJson = JSON.stringify(Object.fromEntries(Object.entries(this.bones).map(([k, xyz]) => [k, xyz.map(round6)])));
239
+ const morphsJson = JSON.stringify(Object.fromEntries(Object.entries(this.morphs).map(([k, v]) => [k, round6(v)])));
240
+ const propsJson = JSON.stringify(Object.fromEntries(Object.entries(this.props).map(([k, v]) => [k, round6(v)])));
241
+ const script = ScriptBuilder.iife(`
242
+ ${lookup}
243
+ if (!_skel) return false;
244
+ var _bones = ${bonesJson};
245
+ var _morphs = ${morphsJson};
246
+ var _props = ${propsJson};
247
+
248
+ var all = _skel.getAllBones();
249
+ for (var i = 0; i < all.length; i++) {
250
+ var b = all[i];
251
+ var xyz = _bones[b.getName()] || [0, 0, 0];
252
+ var xc = b.getXRotControl(), yc = b.getYRotControl(), zc = b.getZRotControl();
253
+ if (typeof xc.setRawValue === "function") { xc.setRawValue(xyz[0]); } else { xc.setValue(xyz[0]); }
254
+ if (typeof yc.setRawValue === "function") { yc.setRawValue(xyz[1]); } else { yc.setValue(xyz[1]); }
255
+ if (typeof zc.setRawValue === "function") { zc.setRawValue(xyz[2]); } else { zc.setValue(xyz[2]); }
256
+ }
257
+
258
+ // Write back to the raw dial slot -- see the comment in
259
+ // capture() for why setValue() would double-apply ERC-controller
260
+ // contributions on properties like morphs or a "Scale" dial that
261
+ // are DzERCLink targets.
262
+ var obj = _skel.getObject();
263
+ if (obj) {
264
+ for (var i = 0; i < obj.getNumModifiers(); i++) {
265
+ var m = obj.getModifier(i);
266
+ if (m.className() === "DzMorph") {
267
+ var v = _morphs[m.getName()];
268
+ var _v = (v !== undefined) ? v : 0;
269
+ var ch = m.getValueChannel();
270
+ if (typeof ch.setRawValue === "function") { ch.setRawValue(_v); }
271
+ else { ch.setValue(_v); }
272
+ }
273
+ }
274
+ }
275
+
276
+ for (var i = 0; i < _skel.getNumProperties(); i++) {
277
+ var p = _skel.getProperty(i);
278
+ if (p && p.setValue) {
279
+ var v = _props[p.getName()];
280
+ var _v = (v !== undefined) ? v : 0;
281
+ if (typeof p.setRawValue === "function") { p.setRawValue(_v); }
282
+ else { p.setValue(_v); }
283
+ }
284
+ }
285
+
286
+ return true;
287
+ `);
288
+ await skeleton.getClient().execute(script, undefined, { retryOnBusy, maxWait });
289
+ }
290
+ // ── dunder ────────────────────────────────────────────────────────────
291
+ toString() {
292
+ return (`DazPose(figure=${JSON.stringify(this.figure)}, ` +
293
+ `bones=${Object.keys(this.bones).length}, morphs=${Object.keys(this.morphs).length}, props=${Object.keys(this.props).length})`);
294
+ }
295
+ }
@@ -0,0 +1,54 @@
1
+ /**
2
+ * Domain-level pose convenience wrappers built on the DazPose/DazNode/
3
+ * DazSkeleton primitives. Mirrors dazpy's `poses.py`.
4
+ */
5
+ import { DazPose } from "./pose.js";
6
+ import type { DazNode } from "./node.js";
7
+ import type { DazSkeleton } from "./skeleton.js";
8
+ /**
9
+ * Apply `pose` to `skeleton` in a single HTTP call.
10
+ *
11
+ * @param pose A {@link DazPose} instance, or a path to a pose JSON file
12
+ * (loaded via {@link DazPose.load} first).
13
+ */
14
+ export declare function applyPose(skeleton: DazSkeleton, pose: DazPose | string): Promise<void>;
15
+ /**
16
+ * Reset `node`'s local position and rotation to zero, and scale to 1.0.
17
+ *
18
+ * Works on any {@link DazNode} -- camera, prop, or figure root. Uses a
19
+ * single DazScript evaluation via `DazNode.setTransform`.
20
+ */
21
+ export declare function resetTransforms(node: DazNode): Promise<void>;
22
+ /** Options for {@link zeroFigure}. */
23
+ export interface ZeroFigureOptions {
24
+ /**
25
+ * When `true`, node-level numeric properties are also zeroed, via
26
+ * `DazPose.applyFull`. This is **opt-in**, not the default: `applyFull`
27
+ * writes 0 for every property returned by the figure's node-property
28
+ * enumeration that is *absent* from the pose it's given, and every other
29
+ * caller passes a captured pose whose `props` already contains those
30
+ * values. `zeroFigure` instead passes an empty `props`, so with
31
+ * `includeProps: true` that "absent -> 0" fallback can drive built-in
32
+ * transform-adjacent dials -- e.g. the figure's general Scale property
33
+ * (see the DzERCLink comment in `pose.ts`'s `capture()`) -- to 0,
34
+ * contradicting the "does not touch root transform" guarantee. Only pass
35
+ * `true` if you know your rig doesn't route transforms through its
36
+ * node-property list.
37
+ *
38
+ * The two modes also differ in how they write ERC-driven channels: the
39
+ * `true` path goes through `DazPose.applyFull`, which prefers
40
+ * `setRawValue()` writes to avoid double-applying `DzERCLink` controller
41
+ * contributions. The `false` path uses `DazSkeleton.zeroBonesAndMorphs`,
42
+ * which uses plain `setValue()` writes. On ERC-driven channels the two
43
+ * modes can therefore leave the figure in different end states.
44
+ */
45
+ includeProps?: boolean;
46
+ }
47
+ /**
48
+ * Drive every bone rotation and morph on `skeleton` to zero.
49
+ *
50
+ * The default (`includeProps: false`) is what guarantees this function
51
+ * never touches the figure's root position/rotation/scale -- use
52
+ * {@link resetTransforms} for that instead.
53
+ */
54
+ export declare function zeroFigure(skeleton: DazSkeleton, opts?: ZeroFigureOptions): Promise<void>;
package/dist/poses.js ADDED
@@ -0,0 +1,40 @@
1
+ /**
2
+ * Domain-level pose convenience wrappers built on the DazPose/DazNode/
3
+ * DazSkeleton primitives. Mirrors dazpy's `poses.py`.
4
+ */
5
+ import { DazPose } from "./pose.js";
6
+ /**
7
+ * Apply `pose` to `skeleton` in a single HTTP call.
8
+ *
9
+ * @param pose A {@link DazPose} instance, or a path to a pose JSON file
10
+ * (loaded via {@link DazPose.load} first).
11
+ */
12
+ export async function applyPose(skeleton, pose) {
13
+ const resolved = typeof pose === "string" ? DazPose.load(pose) : pose;
14
+ await resolved.apply(skeleton);
15
+ }
16
+ /**
17
+ * Reset `node`'s local position and rotation to zero, and scale to 1.0.
18
+ *
19
+ * Works on any {@link DazNode} -- camera, prop, or figure root. Uses a
20
+ * single DazScript evaluation via `DazNode.setTransform`.
21
+ */
22
+ export async function resetTransforms(node) {
23
+ await node.setTransform({ position: [0.0, 0.0, 0.0], rotation: [0.0, 0.0, 0.0], scale: [1.0, 1.0, 1.0] });
24
+ }
25
+ /**
26
+ * Drive every bone rotation and morph on `skeleton` to zero.
27
+ *
28
+ * The default (`includeProps: false`) is what guarantees this function
29
+ * never touches the figure's root position/rotation/scale -- use
30
+ * {@link resetTransforms} for that instead.
31
+ */
32
+ export async function zeroFigure(skeleton, opts = {}) {
33
+ const { includeProps = false } = opts;
34
+ if (includeProps) {
35
+ const pose = new DazPose(skeleton.identifier.value, {}, {}, {});
36
+ await pose.applyFull(skeleton);
37
+ return;
38
+ }
39
+ await skeleton.zeroBonesAndMorphs();
40
+ }
@@ -0,0 +1,64 @@
1
+ import type { DazClient } from "./client.js";
2
+ import { DazElement } from "./element.js";
3
+ /**
4
+ * Proxy for a `DzProperty` on any `DzElement`. Typed read/write access to a
5
+ * single named property, including keyframe support for animated properties.
6
+ */
7
+ export declare class DazProperty extends DazElement {
8
+ /**
9
+ * Construct from an owner element locator and property label.
10
+ * Builds a `findPropertyByLabel()` locator internally.
11
+ */
12
+ constructor(client: DazClient, ownerLocator: string, propertyLabel: string);
13
+ /**
14
+ * Construct from a pre-built DazScript locator expression.
15
+ * Used by {@link fromLocator} and by parent Tasks (e.g., DazNode.findProperty).
16
+ */
17
+ constructor(client: DazClient, locator: string);
18
+ /** Construct a `DazProperty` from a pre-built DazScript locator expression. */
19
+ static fromLocator(client: DazClient, locator: string): DazProperty;
20
+ /** Current property value (read/write). */
21
+ value(): Promise<unknown>;
22
+ setValue(v: unknown): Promise<void>;
23
+ /**
24
+ * This property's own dial value, excluding any `DzERCLink` contributions.
25
+ *
26
+ * A property driven by one or more `DzERCLink` controllers computes
27
+ * {@link value} as `rawValue` plus every controller's contribution — a
28
+ * `value()`/`setValue()` snapshot/restore round trip is therefore *not*
29
+ * idempotent for such properties (the captured post-ERC total gets
30
+ * written back into the raw slot, then the links add their contribution
31
+ * again on top). Use `rawValue`/`setRawValue` for exact round trips.
32
+ * Falls back to `getValue()`/`setValue()` for property types without a
33
+ * raw accessor.
34
+ */
35
+ rawValue(): Promise<unknown>;
36
+ setRawValue(v: unknown): Promise<void>;
37
+ /** The display label of this property (read-only). */
38
+ label(): Promise<string | null>;
39
+ /** Minimum allowed value (read-only; `null` if not applicable). */
40
+ min(): Promise<number | null>;
41
+ /** Maximum allowed value (read-only; `null` if not applicable). */
42
+ max(): Promise<number | null>;
43
+ /**
44
+ * Set a keyframe for this (numeric) property via `DzNumericProperty.setDoubleValue(tm, val)` —
45
+ * the DazScript keyframe surface confirmed live against a running DAZ Studio instance.
46
+ * `DzProperty.setKey()`/`.addKey()` do not exist on a live property and silently write nothing.
47
+ */
48
+ setKey(time: number, value: number): Promise<void>;
49
+ /**
50
+ * `true` if this property has keyframe animation data (read-only).
51
+ * Implemented as `getNumKeys() > 0` — `DzProperty.isAnimated()` does not
52
+ * exist on a live property and raises `ScriptRuntimeError` on every access.
53
+ */
54
+ isAnimated(): Promise<boolean | null>;
55
+ /** List all keyframes on this property's animation curve, ordered by time. */
56
+ getKeys(): Promise<Array<{
57
+ time: number;
58
+ value: unknown;
59
+ }>>;
60
+ /** Remove a single keyframe at the given time (no-op if no key exists exactly there). */
61
+ removeKey(time: number): Promise<void>;
62
+ /** Remove all keyframes from this property's animation curve. */
63
+ clearKeys(): Promise<void>;
64
+ }
@@ -0,0 +1,125 @@
1
+ import { DazElement } from "./element.js";
2
+ import { ScriptBuilder } from "./scriptBuilder.js";
3
+ /**
4
+ * Proxy for a `DzProperty` on any `DzElement`. Typed read/write access to a
5
+ * single named property, including keyframe support for animated properties.
6
+ */
7
+ export class DazProperty extends DazElement {
8
+ constructor(client, locatorOrOwner, propertyLabel) {
9
+ let locator;
10
+ if (propertyLabel !== undefined) {
11
+ // Two-argument form: build findPropertyByLabel locator
12
+ locator =
13
+ `(function(){` +
14
+ `var obj = ${locatorOrOwner};` +
15
+ `return obj ? obj.findPropertyByLabel(${ScriptBuilder.escapeString(propertyLabel)}) : null;` +
16
+ `})()`;
17
+ }
18
+ else {
19
+ // One-argument form (beyond first param): use locator as-is
20
+ locator = locatorOrOwner;
21
+ }
22
+ super(client, locator);
23
+ }
24
+ /** Construct a `DazProperty` from a pre-built DazScript locator expression. */
25
+ static fromLocator(client, locator) {
26
+ return new DazProperty(client, locator);
27
+ }
28
+ /** Current property value (read/write). */
29
+ async value() {
30
+ const script = ScriptBuilder.iife(`var p = ${this.locator}; return p ? p.getValue() : null;`);
31
+ return (await this.client.execute(script)).value;
32
+ }
33
+ async setValue(v) {
34
+ const script = ScriptBuilder.iife(`var p = ${this.locator}; if (p) p.setValue(${ScriptBuilder.serializeArg(v)});`);
35
+ await this.client.execute(script);
36
+ }
37
+ /**
38
+ * This property's own dial value, excluding any `DzERCLink` contributions.
39
+ *
40
+ * A property driven by one or more `DzERCLink` controllers computes
41
+ * {@link value} as `rawValue` plus every controller's contribution — a
42
+ * `value()`/`setValue()` snapshot/restore round trip is therefore *not*
43
+ * idempotent for such properties (the captured post-ERC total gets
44
+ * written back into the raw slot, then the links add their contribution
45
+ * again on top). Use `rawValue`/`setRawValue` for exact round trips.
46
+ * Falls back to `getValue()`/`setValue()` for property types without a
47
+ * raw accessor.
48
+ */
49
+ async rawValue() {
50
+ const script = ScriptBuilder.iife(" var p = " + this.locator + ";\n" +
51
+ " if (!p) return null;\n" +
52
+ ' return (typeof p.getRawValue === "function") ? p.getRawValue() : p.getValue();');
53
+ return (await this.client.execute(script)).value;
54
+ }
55
+ async setRawValue(v) {
56
+ const serialized = ScriptBuilder.serializeArg(v);
57
+ const script = ScriptBuilder.iife(" var p = " + this.locator + ";\n" +
58
+ " if (!p) return;\n" +
59
+ ' if (typeof p.setRawValue === "function") { p.setRawValue(' + serialized + "); }\n" +
60
+ " else { p.setValue(" + serialized + "); }");
61
+ await this.client.execute(script);
62
+ }
63
+ /** The display label of this property (read-only). */
64
+ async label() {
65
+ const script = ScriptBuilder.iife(`var p = ${this.locator}; return p ? p.getLabel() : null;`);
66
+ return (await this.client.execute(script)).value;
67
+ }
68
+ /** Minimum allowed value (read-only; `null` if not applicable). */
69
+ async min() {
70
+ const script = ScriptBuilder.iife(`var p = ${this.locator}; return (p && p.getMin) ? p.getMin() : null;`);
71
+ return (await this.client.execute(script)).value;
72
+ }
73
+ /** Maximum allowed value (read-only; `null` if not applicable). */
74
+ async max() {
75
+ const script = ScriptBuilder.iife(`var p = ${this.locator}; return (p && p.getMax) ? p.getMax() : null;`);
76
+ return (await this.client.execute(script)).value;
77
+ }
78
+ /**
79
+ * Set a keyframe for this (numeric) property via `DzNumericProperty.setDoubleValue(tm, val)` —
80
+ * the DazScript keyframe surface confirmed live against a running DAZ Studio instance.
81
+ * `DzProperty.setKey()`/`.addKey()` do not exist on a live property and silently write nothing.
82
+ */
83
+ async setKey(time, value) {
84
+ const script = ScriptBuilder.iife(" var p = " + this.locator + ";\n" +
85
+ " if (p && p.setDoubleValue) p.setDoubleValue(" + ScriptBuilder.serializeArg(time) + ", " + ScriptBuilder.serializeArg(value) + ");");
86
+ await this.client.execute(script);
87
+ }
88
+ /**
89
+ * `true` if this property has keyframe animation data (read-only).
90
+ * Implemented as `getNumKeys() > 0` — `DzProperty.isAnimated()` does not
91
+ * exist on a live property and raises `ScriptRuntimeError` on every access.
92
+ */
93
+ async isAnimated() {
94
+ const script = ScriptBuilder.iife(" var p = " + this.locator + ";\n" +
95
+ " if (!p || !p.getNumKeys) return null;\n" +
96
+ " return p.getNumKeys() > 0;");
97
+ return (await this.client.execute(script)).value;
98
+ }
99
+ /** List all keyframes on this property's animation curve, ordered by time. */
100
+ async getKeys() {
101
+ const script = ScriptBuilder.iife(" var p = " + this.locator + ";\n" +
102
+ " if (!p || !p.getNumKeys) return [];\n" +
103
+ " var n = p.getNumKeys();\n" +
104
+ " var keys = [];\n" +
105
+ " for (var i = 0; i < n; i++) {\n" +
106
+ " var t = p.getKeyTime(i);\n" +
107
+ " keys.push({ time: t.valueOf(), value: p.getDoubleValue(t) });\n" +
108
+ " }\n" +
109
+ " return keys;");
110
+ return (await this.client.execute(script)).value ?? [];
111
+ }
112
+ /** Remove a single keyframe at the given time (no-op if no key exists exactly there). */
113
+ async removeKey(time) {
114
+ const serializedTime = ScriptBuilder.serializeArg(time);
115
+ const script = ScriptBuilder.iife(" var p = " + this.locator + ";\n" +
116
+ " if (p && p.deleteKeys) p.deleteKeys(new DzTimeRange(" + serializedTime + ", " + serializedTime + "));");
117
+ await this.client.execute(script);
118
+ }
119
+ /** Remove all keyframes from this property's animation curve. */
120
+ async clearKeys() {
121
+ const script = ScriptBuilder.iife(" var p = " + this.locator + ";\n" +
122
+ " if (p && p.deleteAllKeys) p.deleteAllKeys();");
123
+ await this.client.execute(script);
124
+ }
125
+ }