Replace a component

Use component replacement when an option swaps a substantial piece of geometry, such as a four-leg base for a five-star base. The root model provides a stable placement target; each alternative is a linked object asset.

Current Editor status

REPLACE_COMPONENT is activated by resolve and reconciled in the Editor preview runtime (structure before root surfaces). The mappings panel still focuses on material/visibility bindings; replacement bindings are authored via Backoffice / API and hydrate into the visual document for replay.

Where your authoring workflow creates the binding through another supported surface or the GraphQL API, it must identify:

• the triggering choice value;
• the scene target where the part attaches;
• the linked asset key for the replacement;
• an object asset revision registered on the same product model.

SET_MATERIAL targets must not live inside a replaceable structural subtree (rejected at authoring/publish).

Runtime behavior

For a valid matching selection, resolution adds the replacement object revision to activeObjectAssetRevisionIds / structure and returns a replacement action with its linked asset key and document URL. The Editor reconciler instantiates an independent object instance into the structural slot and restores the original root GLB subtree when the replacement is inactive.

Common mistakes

• The linked asset key does not match a registered object asset.
• Alternatives use different origins, scale, or orientation.
• The renderer adds the new part without removing the old one.
• Authors assume registration alone activates the component.

Verify

1. Resolve every replacement value against the draft revision.
2. Confirm the expected object revision ID and linked key are returned.
3. Check alignment, shadows, and rapid switching in the consuming renderer.
4. Publish only after the same checks pass against the published revision.