@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,124 @@
1
+ /** High-level render API -- convenience wrappers over `/render` and `/render/batch`. */
2
+ import { DazClient } from "./client.js";
3
+ /** A figure and the morph values to apply before rendering. */
4
+ export interface FigureMorphs {
5
+ name: string | null;
6
+ morphs?: Record<string, number>;
7
+ }
8
+ /** A single output variant for batch rendering. */
9
+ export interface RenderVariantSpec {
10
+ outputPath: string;
11
+ figure?: string;
12
+ morphs?: Record<string, number>;
13
+ figures?: FigureMorphs[];
14
+ width?: number;
15
+ height?: number;
16
+ camera?: string;
17
+ engine?: string;
18
+ }
19
+ /** Shared defaults applied to all variants in a batch render. */
20
+ export interface RenderBaseSpec {
21
+ figure?: string;
22
+ morphs?: Record<string, number>;
23
+ figures?: FigureMorphs[];
24
+ width?: number;
25
+ height?: number;
26
+ camera?: string;
27
+ engine?: string;
28
+ }
29
+ /** Result of a single render operation. */
30
+ export interface RenderResult {
31
+ success: boolean;
32
+ outputPath: string;
33
+ fileSizeBytes: number;
34
+ durationMs: number;
35
+ error: string;
36
+ requestId: string;
37
+ }
38
+ /** Options for {@link render}. */
39
+ export interface RenderCallOptions {
40
+ /** Label of the figure to configure morphs on. */
41
+ figure?: string;
42
+ /** Morph values to apply `{label: value}`. Only used when `figure` is set. */
43
+ morphs?: Record<string, number>;
44
+ /** List of {@link FigureMorphs} for multi-figure scenes. Mutually exclusive with `figure`. */
45
+ figures?: FigureMorphs[];
46
+ /** Image width in pixels (must be paired with `height`). */
47
+ width?: number;
48
+ /** Image height in pixels (must be paired with `width`). */
49
+ height?: number;
50
+ /** Camera label to render from. Defaults to the active viewport camera. */
51
+ camera?: string;
52
+ /** Render engine (`"iray"`, `"viewport"`, `"filament"`). */
53
+ engine?: string;
54
+ /** Iray sample count (0 = use scene default). */
55
+ iraySamples?: number;
56
+ /** If `true`, reset all figure morph values to defaults before applying `morphs`. */
57
+ resetMorphs?: boolean;
58
+ /**
59
+ * If `true` (default), await until the render completes and return a
60
+ * fully populated {@link RenderResult}. If `false`, return immediately
61
+ * after the job is accepted; the result will have `fileSizeBytes: -1` and
62
+ * `durationMs: 0`.
63
+ */
64
+ wait?: boolean;
65
+ /** Maximum milliseconds to wait when `wait` is `true`. Default `300000` (5 minutes). */
66
+ timeoutMs?: number;
67
+ /** Optional callback invoked with each `"progress"` SSE event's raw payload while waiting. */
68
+ onProgress?: (data: Record<string, unknown>) => void;
69
+ }
70
+ /**
71
+ * Render the DAZ Studio scene to `outputPath`.
72
+ *
73
+ * Uses the SSE progress stream (`GET /render/:id/progress`) when available;
74
+ * falls back to long-poll on `/requests/:id/result` otherwise.
75
+ *
76
+ * @throws RenderError If the render fails.
77
+ * @throws DazTimeoutError If `timeoutMs` is exceeded.
78
+ * @throws ConnectionError If the server cannot be reached.
79
+ * @throws AuthenticationError On HTTP 401/403.
80
+ *
81
+ * @example
82
+ * ```ts
83
+ * const client = new DazClient();
84
+ * const result = await render(client, "C:\\tmp\\out.png", { width: 1920, height: 1080 });
85
+ * console.log(result.outputPath, result.fileSizeBytes);
86
+ * ```
87
+ */
88
+ export declare function render(client: DazClient, outputPath: string, opts?: RenderCallOptions): Promise<RenderResult>;
89
+ /** Options for {@link renderVariants}. */
90
+ export interface RenderVariantsOptions {
91
+ /** Optional callback called with `(completed, total)` after each render finishes. */
92
+ onProgress?: (completed: number, total: number) => void;
93
+ /** Maximum total milliseconds to wait for all renders to finish. Default `300000` (5 minutes). */
94
+ timeoutMs?: number;
95
+ }
96
+ /**
97
+ * Render multiple variants via `POST /render/batch`.
98
+ *
99
+ * Submits all variants in a single batch request, then waits for each
100
+ * render to complete sequentially, calling `onProgress` after each one
101
+ * finishes.
102
+ *
103
+ * @returns A list of {@link RenderResult} in the same order as `variants`.
104
+ * If a variant fails, its result will have `success: false` and `error`
105
+ * set; subsequent variants are still attempted.
106
+ * @throws DazTimeoutError If `timeoutMs` is exceeded.
107
+ * @throws ConnectionError If the server cannot be reached.
108
+ * @throws AuthenticationError On HTTP 401/403.
109
+ *
110
+ * @example
111
+ * ```ts
112
+ * const client = new DazClient();
113
+ * const results = await renderVariants(
114
+ * client,
115
+ * [
116
+ * { outputPath: "C:\\tmp\\smile.png", figure: "Genesis 9", morphs: { Smile: 1.0 } },
117
+ * { outputPath: "C:\\tmp\\neutral.png", figure: "Genesis 9" },
118
+ * ],
119
+ * { width: 1920, height: 1080, engine: "iray" },
120
+ * { onProgress: (done, total) => console.log(`${done}/${total}`) },
121
+ * );
122
+ * ```
123
+ */
124
+ export declare function renderVariants(client: DazClient, variants: RenderVariantSpec[], base?: RenderBaseSpec, opts?: RenderVariantsOptions): Promise<RenderResult[]>;
@@ -0,0 +1,235 @@
1
+ /** High-level render API -- convenience wrappers over `/render` and `/render/batch`. */
2
+ import { parseSseStream } from "./client.js";
3
+ import { AuthenticationError, DazTimeoutError, RenderError } from "./exceptions.js";
4
+ function sleepMs(ms) {
5
+ return new Promise((resolve) => setTimeout(resolve, ms));
6
+ }
7
+ function figuresToPayload(figures) {
8
+ return figures.map((f) => ({ name: f.name, morphs: f.morphs ?? {} }));
9
+ }
10
+ function variantToDict(v) {
11
+ const d = { output_path: v.outputPath };
12
+ if (v.figures && v.figures.length > 0) {
13
+ d.figures = figuresToPayload(v.figures);
14
+ }
15
+ else if (v.figure) {
16
+ d.figure = v.figure;
17
+ if (v.morphs)
18
+ d.morphs = v.morphs;
19
+ }
20
+ if (v.width && v.height) {
21
+ d.width = v.width;
22
+ d.height = v.height;
23
+ }
24
+ if (v.camera)
25
+ d.camera = v.camera;
26
+ if (v.engine)
27
+ d.engine = v.engine;
28
+ return d;
29
+ }
30
+ function baseToDict(b) {
31
+ const d = {};
32
+ if (b.figures && b.figures.length > 0) {
33
+ d.figures = figuresToPayload(b.figures);
34
+ }
35
+ else if (b.figure) {
36
+ d.figure = b.figure;
37
+ if (b.morphs)
38
+ d.morphs = b.morphs;
39
+ }
40
+ if (b.width && b.height) {
41
+ d.width = b.width;
42
+ d.height = b.height;
43
+ }
44
+ if (b.camera)
45
+ d.camera = b.camera;
46
+ if (b.engine)
47
+ d.engine = b.engine;
48
+ return d;
49
+ }
50
+ /**
51
+ * Wait for a render to complete using the SSE progress stream.
52
+ *
53
+ * Falls back to request-result long-polling if the SSE stream cannot be
54
+ * established or ends without a `complete`/`error` event.
55
+ *
56
+ * `onProgress`, if given, is called with the raw `"progress"` event payload
57
+ * (e.g. `{request_id, percent, frame, total_frames}` for animation renders;
58
+ * single-shot renders only get one such event at 0% when the render starts
59
+ * -- the DAZ SDK exposes no intra-frame percent signal).
60
+ */
61
+ async function waitRenderSse(client, requestId, timeoutMs, onProgress) {
62
+ const deadline = Date.now() + timeoutMs;
63
+ try {
64
+ const resp = await client.streamRenderProgress(requestId, { timeoutMs: timeoutMs + 5_000 });
65
+ if (resp !== null) {
66
+ for await (const { event, data } of parseSseStream(resp)) {
67
+ if (Date.now() > deadline)
68
+ break;
69
+ let parsed;
70
+ try {
71
+ parsed = JSON.parse(data);
72
+ }
73
+ catch {
74
+ parsed = { _raw: data };
75
+ }
76
+ if (event === "complete") {
77
+ return {
78
+ success: true,
79
+ outputPath: parsed.output_path ?? "",
80
+ fileSizeBytes: parsed.file_size_bytes !== undefined ? Number(parsed.file_size_bytes) : -1,
81
+ durationMs: parsed.duration_ms !== undefined ? Number(parsed.duration_ms) : 0,
82
+ error: "",
83
+ requestId,
84
+ };
85
+ }
86
+ if (event === "error") {
87
+ throw new RenderError(parsed.error ?? "Render failed", requestId);
88
+ }
89
+ if (event === "progress" && onProgress !== undefined) {
90
+ onProgress(parsed);
91
+ }
92
+ }
93
+ }
94
+ }
95
+ catch (e) {
96
+ if (e instanceof RenderError || e instanceof DazTimeoutError || e instanceof AuthenticationError) {
97
+ throw e;
98
+ }
99
+ // SSE unavailable -- fall through to polling.
100
+ }
101
+ // Polling fallback.
102
+ while (Date.now() < deadline) {
103
+ const remainingSec = Math.max(1, Math.ceil((deadline - Date.now()) / 1000));
104
+ const data = await client.getRequestResult(requestId, true, Math.min(30, remainingSec));
105
+ if (data.success !== undefined && data.success !== null) {
106
+ if (!data.success) {
107
+ throw new RenderError(data.error ?? "Render failed", requestId);
108
+ }
109
+ const resultVal = data.result;
110
+ const outPath = typeof resultVal === "object" && resultVal !== null ? resultVal.output_path ?? "" : "";
111
+ return {
112
+ success: true,
113
+ outputPath: outPath,
114
+ fileSizeBytes: -1,
115
+ durationMs: data.duration_ms !== undefined ? Number(data.duration_ms) : 0,
116
+ error: "",
117
+ requestId,
118
+ };
119
+ }
120
+ const status = data.status;
121
+ if (status === "failed") {
122
+ throw new RenderError(data.error ?? "Render failed", requestId);
123
+ }
124
+ if (status === "cancelled") {
125
+ throw new RenderError("Render was cancelled", requestId);
126
+ }
127
+ await sleepMs(500);
128
+ }
129
+ throw new DazTimeoutError(`Render timed out after ${timeoutMs / 1000}s (requestId=${JSON.stringify(requestId)})`);
130
+ }
131
+ /**
132
+ * Render the DAZ Studio scene to `outputPath`.
133
+ *
134
+ * Uses the SSE progress stream (`GET /render/:id/progress`) when available;
135
+ * falls back to long-poll on `/requests/:id/result` otherwise.
136
+ *
137
+ * @throws RenderError If the render fails.
138
+ * @throws DazTimeoutError If `timeoutMs` is exceeded.
139
+ * @throws ConnectionError If the server cannot be reached.
140
+ * @throws AuthenticationError On HTTP 401/403.
141
+ *
142
+ * @example
143
+ * ```ts
144
+ * const client = new DazClient();
145
+ * const result = await render(client, "C:\\tmp\\out.png", { width: 1920, height: 1080 });
146
+ * console.log(result.outputPath, result.fileSizeBytes);
147
+ * ```
148
+ */
149
+ export async function render(client, outputPath, opts = {}) {
150
+ const { figure, morphs, figures, width = 0, height = 0, camera = "", engine = "", iraySamples = 0, resetMorphs = false, wait = true, timeoutMs = 300_000, onProgress, } = opts;
151
+ const data = await client.renderSubmit(outputPath, {
152
+ figure,
153
+ morphs,
154
+ figures: figures !== undefined ? figuresToPayload(figures) : undefined,
155
+ width,
156
+ height,
157
+ camera,
158
+ engine,
159
+ iraySamples,
160
+ resetMorphs,
161
+ });
162
+ const requestId = data.request_id ?? "";
163
+ if (!wait) {
164
+ return { success: true, outputPath, fileSizeBytes: -1, durationMs: 0, error: "", requestId };
165
+ }
166
+ return waitRenderSse(client, requestId, timeoutMs, onProgress);
167
+ }
168
+ /**
169
+ * Render multiple variants via `POST /render/batch`.
170
+ *
171
+ * Submits all variants in a single batch request, then waits for each
172
+ * render to complete sequentially, calling `onProgress` after each one
173
+ * finishes.
174
+ *
175
+ * @returns A list of {@link RenderResult} in the same order as `variants`.
176
+ * If a variant fails, its result will have `success: false` and `error`
177
+ * set; subsequent variants are still attempted.
178
+ * @throws DazTimeoutError If `timeoutMs` is exceeded.
179
+ * @throws ConnectionError If the server cannot be reached.
180
+ * @throws AuthenticationError On HTTP 401/403.
181
+ *
182
+ * @example
183
+ * ```ts
184
+ * const client = new DazClient();
185
+ * const results = await renderVariants(
186
+ * client,
187
+ * [
188
+ * { outputPath: "C:\\tmp\\smile.png", figure: "Genesis 9", morphs: { Smile: 1.0 } },
189
+ * { outputPath: "C:\\tmp\\neutral.png", figure: "Genesis 9" },
190
+ * ],
191
+ * { width: 1920, height: 1080, engine: "iray" },
192
+ * { onProgress: (done, total) => console.log(`${done}/${total}`) },
193
+ * );
194
+ * ```
195
+ */
196
+ export async function renderVariants(client, variants, base, opts = {}) {
197
+ const { onProgress, timeoutMs = 300_000 } = opts;
198
+ const variantsPayload = variants.map(variantToDict);
199
+ const basePayload = base !== undefined ? baseToDict(base) : undefined;
200
+ const data = await client.renderBatchSubmit(variantsPayload, basePayload);
201
+ const requestIds = data.request_ids ?? [];
202
+ const total = requestIds.length;
203
+ const results = [];
204
+ const deadline = Date.now() + timeoutMs;
205
+ let completed = 0;
206
+ for (let i = 0; i < requestIds.length; i++) {
207
+ const requestId = requestIds[i];
208
+ const remainingMs = Math.max(1_000, deadline - Date.now());
209
+ let result;
210
+ try {
211
+ result = await waitRenderSse(client, requestId, remainingMs);
212
+ }
213
+ catch (e) {
214
+ if (e instanceof RenderError) {
215
+ result = {
216
+ success: false,
217
+ outputPath: i < variants.length ? variants[i].outputPath : "",
218
+ fileSizeBytes: -1,
219
+ durationMs: 0,
220
+ error: e.message,
221
+ requestId,
222
+ };
223
+ }
224
+ else {
225
+ throw e;
226
+ }
227
+ }
228
+ results.push(result);
229
+ completed += 1;
230
+ if (onProgress !== undefined) {
231
+ onProgress(completed, total);
232
+ }
233
+ }
234
+ return results;
235
+ }
@@ -0,0 +1,15 @@
1
+ /** The result of a synchronous or asynchronous DazScript execution. */
2
+ export interface ExecutionResult {
3
+ /** The return value of the script (JSON-decoded). */
4
+ value: unknown;
5
+ /** Lines written to the DAZ Studio message log during execution. */
6
+ output: string[];
7
+ /** The server-assigned request ID (empty for sync executions). */
8
+ requestId: string;
9
+ /** `true` if the script completed without error. */
10
+ success: boolean;
11
+ /** Error message returned by the server (empty when successful). */
12
+ error: string;
13
+ /** Wall-clock execution time in milliseconds as measured by the server. */
14
+ durationMs: number;
15
+ }
package/dist/result.js ADDED
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,154 @@
1
+ import { DazCamera } from "./camera.js";
2
+ import { DazClient } from "./client.js";
3
+ import { DazLight } from "./light.js";
4
+ import { DazNode } from "./node.js";
5
+ import { DazSkeleton } from "./skeleton.js";
6
+ /**
7
+ * High-level proxy for the active DAZ Studio scene (`Scene` global) — the
8
+ * primary entry point for inspecting and manipulating the scene.
9
+ *
10
+ * This file covers node/camera/light/skeleton factories and selection
11
+ * (Phase 2 Task 12); later tasks (13-14) add bulk scene snapshots and
12
+ * I/O/playback/undo/dForce methods to this same class.
13
+ *
14
+ * @remarks
15
+ * `applyInteractionRecipe()` (dazpy's multi-figure IK recipe application) is
16
+ * Phase 5 scope (`daz-script-server-sf7y`), not implemented here.
17
+ */
18
+ export declare class DazScene {
19
+ private readonly client;
20
+ constructor(client?: DazClient);
21
+ /**
22
+ * The underlying {@link DazClient}, for domain-helper modules
23
+ * (`sceneState.ts`, `lighting.ts`, `cinematics.ts`, ...) that need to
24
+ * issue their own custom scripts. Mirrors dazpy's soft-private `_client`
25
+ * attribute, which sibling modules access directly.
26
+ */
27
+ getClient(): DazClient;
28
+ /** All top-level and child nodes in the scene, typed via `inherits()` (DazSkeleton/DazCamera/DazLight/DazNode), scene-panel order. */
29
+ nodes(): Promise<DazNode[]>;
30
+ /** Find a scene node by internal name. */
31
+ findNode(name: string): Promise<DazNode>;
32
+ /** Find a scene node by its user-visible label. Anchored to the internal *name*, so it stays stable if the label later changes. */
33
+ findNodeByLabel(label: string): Promise<DazNode>;
34
+ numNodes(): Promise<number>;
35
+ cameras(): Promise<DazCamera[]>;
36
+ /** Find a camera by its user-visible label (same value accepted by `render()`'s `camera` parameter in Phase 3). */
37
+ findCameraByLabel(label: string): Promise<DazCamera>;
38
+ /** Create a new basic camera node and add it to the scene. `name` omitted → DAZ Studio assigns its default (de-duplicated) name. */
39
+ createCamera(name?: string): Promise<DazCamera>;
40
+ lights(): Promise<DazLight[]>;
41
+ /** Create a new light node (`"spot"`/`"point"`/`"distant"`) and add it to the scene. */
42
+ createLight(lightType: "spot" | "point" | "distant", name?: string): Promise<DazLight>;
43
+ findLightByLabel(label: string): Promise<DazLight>;
44
+ skeletons(): Promise<DazSkeleton[]>;
45
+ /**
46
+ * Find a skeleton by internal name, retrying `Scene.getSkeletonList()` up
47
+ * to `retryAttempts` times (default 3, `retryDelay * attemptNumber`
48
+ * seconds apart, default base 0.15s) — `getSkeletonList()` has been
49
+ * observed to transiently omit a present skeleton under main-thread load
50
+ * (daz-script-server-xtkd); a momentary miss is retried rather than
51
+ * immediately raised. Pass `retryAttempts: 1` to disable retrying.
52
+ */
53
+ findSkeleton(name: string, opts?: {
54
+ retryAttempts?: number;
55
+ retryDelay?: number;
56
+ }): Promise<DazSkeleton>;
57
+ /** Find a skeleton by its user-visible label. Kept as `kind: "label"` — same-asset figures share an internal name, so name-based lookup would collapse distinct figures into one. */
58
+ findSkeletonByLabel(label: string): Promise<DazSkeleton>;
59
+ numSkeletons(): Promise<number>;
60
+ selectedNodes(): Promise<DazNode[]>;
61
+ primarySelection(): Promise<DazNode | null>;
62
+ setPrimarySelection(node: DazNode): Promise<void>;
63
+ selectAll(on?: boolean): Promise<void>;
64
+ /**
65
+ * Full skeleton and bone metadata for the scene in one HTTP call.
66
+ * @param skeletonLabels Optional subset of skeleton names/labels to include; omit to return every skeleton.
67
+ */
68
+ sceneSnapshot(skeletonLabels?: string[]): Promise<Array<Record<string, unknown>>>;
69
+ /** World-space transforms (`name`/`label`/`position`/`rotation`/`visible`) for every node, in one HTTP call. */
70
+ allNodeTransforms(): Promise<Array<Record<string, unknown>>>;
71
+ /** Full scene hierarchy as nested `{name, label, children}` dicts, one entry per root-level node. */
72
+ nodeTree(): Promise<Array<Record<string, unknown>>>;
73
+ /**
74
+ * Descendant tree rooted at a single node (searched by label first, then internal name), with an optional recursion-depth limit.
75
+ * @throws NodeNotFoundError if `root` cannot be found.
76
+ */
77
+ nodeHierarchy(opts?: {
78
+ root?: string;
79
+ maxDepth?: number;
80
+ }): Promise<{
81
+ node: string;
82
+ hierarchy: Record<string, unknown> | null;
83
+ totalDescendants: number;
84
+ }>;
85
+ /** Lightweight top-level snapshot: root-level figures, cameras, lights, scene file, and primary selection. Follower figures (parented under another figure) are excluded from `figures`. */
86
+ overview(): Promise<Record<string, unknown>>;
87
+ private exportViaNativeExporter;
88
+ /** Load a scene file (merge mode — does not clear the existing scene). `path` is an absolute path on the server host. */
89
+ load(path: string): Promise<void>;
90
+ /** Save the scene to `path` (absolute path on the server host). */
91
+ save(path: string): Promise<void>;
92
+ /** Save a copy of the scene without changing its current file or dirty state. See `DazClient.sceneSaveCopy` for the copy-vs-serialize tradeoff. */
93
+ saveCopy(path: string): Promise<Record<string, unknown>>;
94
+ /** Export the scene to FBX via DAZ Studio's built-in `DzFbxExporter` (synchronous — no async job to poll). */
95
+ exportFbx(path: string, opts?: {
96
+ selectedOnly?: boolean;
97
+ includeFigures?: boolean;
98
+ includeProps?: boolean;
99
+ includeLights?: boolean;
100
+ includeCameras?: boolean;
101
+ includeAnimations?: boolean;
102
+ embedTextures?: boolean;
103
+ options?: Record<string, unknown>;
104
+ }): Promise<void>;
105
+ /** Export the scene to OBJ via DAZ Studio's built-in `DzObjExporter` (synchronous, see {@link exportFbx}). */
106
+ exportObj(path: string, opts?: {
107
+ selectedOnly?: boolean;
108
+ ignoreInvisible?: boolean;
109
+ includeNormals?: boolean;
110
+ collectMaps?: boolean;
111
+ options?: Record<string, unknown>;
112
+ }): Promise<void>;
113
+ filename(): Promise<string>;
114
+ needsSave(): Promise<boolean>;
115
+ /** Playback range as `{start, end}` in frames. */
116
+ playRange(): Promise<{
117
+ start: number;
118
+ end: number;
119
+ }>;
120
+ setPlayRange(start: number, end: number): Promise<void>;
121
+ /** Animation range as `{start, end}` in frames. */
122
+ animRange(): Promise<{
123
+ start: number;
124
+ end: number;
125
+ }>;
126
+ setAnimRange(start: number, end: number): Promise<void>;
127
+ isPlaying(): Promise<boolean>;
128
+ loopPlayback(on: boolean): Promise<void>;
129
+ /** Step back one level in DAZ Studio's undo stack (the *global* stack — use {@link undo} to group a series of changes instead). */
130
+ undoLast(): Promise<void>;
131
+ redoLast(): Promise<void>;
132
+ isSimulating(): Promise<boolean>;
133
+ clearDforceSimulation(): Promise<void>;
134
+ /**
135
+ * Run a dForce simulation. `nodes` omitted simulates the whole scene via
136
+ * `DzSimulationMgr.simulate()` (follows the configured Simulation
137
+ * Settings frame range); `nodes` provided runs `customSimulate()` on
138
+ * that subset via the active engine.
139
+ * @param wait When `true` (default), block (via the async execute-and-poll endpoint, since dForce runs can take minutes) until finished, returning `null`. When `false`, submit and return the `requestId` immediately.
140
+ * @throws ScriptRuntimeError if the simulation engine reports an error (only when `wait` is `true`).
141
+ */
142
+ runDforceSimulation(nodes?: DazNode[], opts?: {
143
+ wait?: boolean;
144
+ timeout?: number;
145
+ }): Promise<string | null>;
146
+ frame(): Promise<number>;
147
+ setFrame(frame: number): Promise<void>;
148
+ /**
149
+ * Run `fn` with all its changes grouped into a single undo step labeled
150
+ * `label` (see {@link withUndo}). TS equivalent of dazpy's
151
+ * `with scene.undo(label): ...` context manager.
152
+ */
153
+ undo<T>(label: string, fn: () => Promise<T>): Promise<T>;
154
+ }