3D characters

Build an editable 3D character

Open a 3D project and choose Character authoring. Human controls and agent tools use the same validated geometry, skeleton and animation data.

1. Shape. Remesh unparented sphere primitives or closed document meshes into a continuous surface. Preview first; applying keeps source objects hidden. Use joint-ring lofts for controlled limb topology. Imported asset nodes need editable document geometry first.
2. Rig. Create a quadruped or winged quadruped skeleton from explicit landmarks. For wings, mark shoulder, elbow, wrist and 3–5 finger base/tip pairs on each side, plus jaw and jaw tip. The tool does not infer anatomy. Auto-bind the continuous mesh, inspect the heatmap and smooth or mirror weights. Attach eyes and accessories to a named bone.
3. Animate. Pose with FK or bounded IK, then add idle, wag, walk, wing-flap or roar clips. Wing-flap includes adjustable wrist lag; roar animates the skeleton and needs a separate sound cue. Presets reject missing native bones rather than retargeting arbitrary imported rigs. Inspect contact and deformation across the timeline. Morph targets add editable expressions.
4. Finish. Cut and pack UV islands, paint layered color, normal and roughness maps at 256–2048px and inspect topology/weights. Export GLB/glTF and reopen the file to verify meshes, skeletons, morph targets, textures and clips.

Import a rigged model

Upload a GLB in Assets, then explicitly insert it. Upload only adds the file to the library. Imported model & animation shows mesh, bone, morph and clip inventory. Add an observed clip name and set start/end, speed, weight and loop; placements persist in scene.importedClips and use the same sampled playback in the editor and exports.

Preview editable conversion reports what can become native meshes, PBR maps, skinning, position morphs and sampled animation; Apply retains the original GLB asset in a hidden, locked source checkpoint. Conversion rejects nonunit rest or animated bone scale, unsupported physical material extensions such as clearcoat/transmission, authored morph normals/tangents, instancing and unsupported UV channels. Geometry, texture and animation budgets also apply. Keep complex source work in Blender or another authoring tool and retain imported playback when conversion is rejected.

Saved-state export editable-scene requires pageIndex and the imported model's nodeId. It returns canonical document JSON without saving it; review and write it through the existing revision-checked document API. This JSON keeps project asset references, including the source GLB, rather than packaging portable asset bytes. CLI: dsa projects export PROJECT --format editable-scene --node NODE --page 0 --revision N --output editable.json. Assets Replace uses and the shared replace-asset operation update references to an existing asset of the same media kind while retaining placements/timing and both library assets; check clip names and duration afterward.

Materials

Select a 3D object to open Material in the inspector. The values persist on the object as scene.material, so the viewport, the raster exports and GLB read the same record.

• Presets are starting points: Matte (metalness 0, roughness 0.85), Ceramic (0, 0.2), Metal (1, 0.25) and Polished (0.9, 0.08).
• Material color takes a hex value or a theme token such as $accent. Metalness and roughness run from 0 to 1; the object's own data supplies the starting value, so the built-in 3D template begins at 0.25 and 0.25.
• Wireframe draws edges instead of surfaces. Double sided also renders back faces; keep it for open or imported single-surface meshes, since closed solids do not need it.
• Stored vertex colors multiply the material color, and a painted base-color map replaces it.

Edit these in the inspector or with update-node. A scene object is replaced rather than merged, so read it first and send the fields you are not changing back unchanged.

Emissive color and Emissive intensity control the material's glow contribution. Select owned images for normal, roughness, metalness, emissive and occlusion maps alongside the color texture. These are material maps; bloom remains a page rendering setting.

Textures and UV paint

Textures are owned project assets. Importing a PNG, JPEG or WebP in Color texture uploads it to the project and references it as scene.material.textureAssetId; previews and exports read that asset. An imported model that still carries its own texture offers its original model texture, and external media must be imported before cloud rendering.

1. Unwrap. Add seam edges and unwrap the islands, or use a mesh that already has UVs. Painting is rejected without them.
2. Layer. Create a layer with a name and one map type — color, normal or roughness — plus opacity and visibility. A layer keeps its map type; edit the name, opacity or visibility instead. Up to eight layers persist per object.
3. Paint. A stroke stores a UV point, a radius and a hex color, and a layer keeps at most 256. Strokes stay vector data in the document and are rasterized into the maps whenever the scene is built or exported.
4. Resolution. Choose 256, 512, 1024 or 2048px. One resolution applies to every map on that object.
5. Clear before changing UVs. Strokes are stored in UV space, so unwrapping refuses to run while any layer still holds strokes; clear the layers you no longer need first.

The UV view draws the islands with an optional distortion tint. Red marks area stretch; it is not proof that islands do not overlap. A stroke sent without a layer writes to the legacy single color map, which has the same 256-stroke budget. GLB/glTF embeds the rasterized maps.

Lighting, camera and effects

Deselect every object to edit the page's Camera and Lighting in page.scene. Change them in the inspector or with update-page, preserving the nested fields already present.

• Camera: position, target, field of view from 10° to 120°, and safeFrame margin from 0 to 0.3. Fit animated subject samples selected subjects' posed bounds across the timeline. Portrait/square shot duplication creates a page with its own camera and shared asset files. Check intermediate wing/tail extremes and overlays; sampled fitting is not a continuous clipping guarantee.
• Lighting: retain ambient and the original directional light, and add up to eight point, spot or directional lights. Per-light shadow controls and page rendering settings persist with the scene.
• Effects: fog, exposure, generated environment lighting, shadows, bloom and up to eight seeded particle emitters share the editor, published viewer and raster/video renderer. Emitters have explicit position, spread, velocity, lifetime, count and active interval.

GLB/glTF carries supported geometry, PBR materials, embedded maps, skins and sampled animations; punctual lights use KHR_lights_punctual. Ambient/environment lighting, fog, bloom, exposure, cast-shadow settings and timed particle behavior are Studio rendering settings rather than a portable glTF effect stack. Review the file under the destination viewer's lighting.

Timeline sound

Insert an owned audio asset, then use waveform, trim, gain, loop, mute and event controls. Audio/video node data stores audioStart, audioEnd, audioOffset in seconds, audioGain from 0 to 4, audioMuted, audioLoop and audioEvent. Events are labels, not synthesized sounds. Editor/viewer playback and browser/cloud motion exports share cue timing and mixing. Enable audio when browser autoplay is blocked and listen to the actual exported WebM/MP4. Still images and GLB do not carry a soundtrack.

Agent workflow

Discover sceneCommands through studio_capabilities or /api/schema. WebMCP studio_scene_command accepts a page ID and command, previews by default, and applies with preview:false. studio_inspect_scene returns compact diagnostics at a requested time without transferring vertex buffers.

Saved-state equivalents are REST GET/POST /api/projects/:id/scene, MCP inspect_scene/author_scene, and CLI dsa scene inspect/dsa scene command. Writes require the observed revision. CLI commands are available in the current source build; an older release archive may not include them.

WebMCP studio_imported_model accepts pageId and nodeId for inventory; add convert:true to preview conversion and preview:false to apply. studio_frame_scene_shot takes pageId, nodeIds, optional samples (2–61, default 17) and aspect (portrait/square); it previews by default and applies with preview:false. These are open-editor tools. Network clients use existing document/operations and editable-scene export; discover exact schemas at /api/schema.

What the tools check

Reports flag degenerate triangles, boundary or non-manifold edges, inconsistent winding, unnormalized skin weights and severe edge stretching in sampled poses. They do not certify self-intersection freedom or animation quality. UV seams can intentionally split vertices.

Remeshing uses bounded surface sampling rather than semantic quad retopology. Quadruped landmarks and nearest-segment weights are editable starting points. One-shot IK uses mesh-local targets. Persistent two-bone contacts use world targets, bend poles, horizontal ground height, time ranges and rotation limits; inspect measured error for unreachable targets. Explicit UV islands use planar projection and need a distortion/overlap check. Color paint replaces the base-color map. Sculpt, edge splits and plane-cut loops preserve vertex attributes; legacy remesh/relax reject bound geometry. Save a mesh checkpoint before refinement.

Shared rigs, clips and repair

Share skeleton with attachments explicitly converts compatible legacy copies to one rig reference. Named clip controls adjust speed, amplitude, loop count and blend without rewriting source keys. Later tracks blend over earlier tracks; outside clip intervals the stored pose applies. Joint gizmos edit rest or pose. joint-limits saves per-axis named-bone rotation bounds and optional mirror partner; mirror-pose reflects onto that partner. FK and sampled animation respect those limits. Weight brushes support mirrored stamps, locked joints/vertices and heatmaps.

Complete-animation diagnostics return issue IDs, affected vertices/faces and times, plus contact drift and floor penetration. Click a warning to select its region and pose; compare the next scan with the previous count. Informational coincident seam boundaries are distinguished from defects and appear only in the first scan frame; warning locations remain time-indexed.

Review angles across time

Export scene-angles with start alone for front/right/back/left PNGs and views.json. Add end greater than start and reviewSamples (2–25, default 5) for four actual views at each sampled time, contact-sheet.png and camera/node/time diagnostics, including posed bounds, clipping, geometry counts and measured capture costs. Images and the sheet together must fit 64 megapixels. Clipping measurements do not establish absence of occlusion; view the actual images.

REST export and MCP export_project use start, end, reviewSamples, pageIndex and optional expectedRevision. CLI: dsa projects export PROJECT --format scene-angles --start 0 --end 4 --review-samples 5 --page 0 --revision N --output review.zip. This count differs from scan/framing samples and frame-archive fps.

Recover long saves and exports

Use durable operations with a stable ID: POST /api/projects/:id/operations, poll GET /api/projects/:id/operations/:operationId, then download /result. An uncertain response must reuse the same ID and payload. Jobs retain owner authorization and observed revisions; export pins the accepted document snapshot.

WebMCP studio_start_save returns immediately; poll the operation then use studio_reconcile_save. Network MCP exposes start_operation, get_operation and get_operation_result; CLI exposes dsa operations start/status/result. The editor Operations control recalls the latest ID. Save receipts and export artifacts remain private until project deletion. Live collaborative merging retains its separate merge contract.