feat: spring bones

[RocioCM]

Add Spring Bones Editor for Wearables

Related PRs:

• UI2: feat: spring bones ui2#404
• Wearable Preview: feat: babylon spring bones wearable-preview#168
• Wearable Preview: feat: spring bones wearable-preview#166
• Schemas: feat: spring bones schemas#416

Context and Problem Statement

Wearable creators need the ability to configure spring bone physics parameters (stiffness, gravity, drag force, etc.) directly within the Builder's item editor. Currently, there is no UI to parse, view, or edit spring bone data embedded in GLB/glTF wearable files, requiring creators to use raw blender custom properties.

Solution

Implement a full spring bones editing workflow: parsing spring bone data from GLB files, providing an interactive UI to tweak physics parameters, live-previewing changes in the wearable preview, and patching the GLB binary on save.

• Figma mockups: https://www.figma.com/design/nE4bBBz7vTdNwbgE0kSpCI/Decentralnad-Builder?node-id=3959-3620&t=9FA5vqTxhKyWuZfe-4
• Shape document: https://www.notion.so/decentraland/Jiggle-Bones-2c25f41146a5800b8db1d653f0566c21

Key changes:

• GLB parsing layer (glbUtils.ts, parseSpringBones.ts): Extracts and parses spring bone nodes and their extras parameters from GLB/glTF JSON chunks, supporting both binary GLB and plain glTF formats
• GLB patching layer (patchGltfSpringBones.ts): Re-serializes modified spring bone parameters back into the GLB binary (JSON chunk replacement with proper 4-byte alignment), preserving the BIN chunk verbatim
• Redux state management: New editor state (bones, springBoneParams, originalSpringBoneParams) with actions for set/add/delete/reset params and selectors for dirty-checking
• Spring Bones UI (SpringBonesSection): Collapsible bone cards with sliders for stiffness/gravity/drag, vec3 input for gravity direction, bone hierarchy picker popover for center node selection, and copy/paste params between bones
• Live preview integration (editor sagas): Debounced (1s) push of params to the wearable preview controller via controller.physics.setSpringBonesParams, with immediate push on preview load and emote play
• Save flow (item sagas): On save, patches the GLB for the active body shape representation (or all representations if they share the same model), re-hashes the patched file, and uploads the updated contents
• ItemProvider integration: Parses spring bones on item load and body shape change, clearing/resetting state appropriately

Testing

Spring Bones Section:

• Load a wearable with existing spring bone nodes — verify the "Spring Bones" section appears on the bottom of right panel.
• Load a wearable with no spring bones — verify the "Spring Bones" section does not appear
• Load an emote — verify the "Spring Bones" section does not appear
• Add a new spring bone via "Add a Bone" button and bone hierarchy picker (only spring bones should be selectable on the bone hierarchy)
• Remove a spring bone via the card menu — verify it disappears from the list
• Copy/paste parameters between spring bone cards. Once copied, you should be able to paste params multiple times.
• Click Reset — verify spring bones parameters revert to the last saved state
• Save the item — verify the spring bones parameters are saved correctly (reload the page or re-download the model and inspect to confirm params persisted)

Preview:

• Adjust stiffness, gravity power, drag force sliders — verify live preview updates after around 1 second
• Edit stiffness, gravity power, drag force sliders or gravity direction values using the inputs (not the sliders) — verify the values commit on blur. Ensure min-max range from sliders is enforced. verify live preview updates after around 1 second
• Use the center node dropdown to assign/clear a center bone from the hierarchy picker

Body shapes:

• On a wearable with the same model for both body shapes (male & female), switch body shapes — verify spring bones settings share the same values for both representations
• Test with separate male/female GLB models — verify only the active body shape's GLB spring bones params are persisted on save (spring bones settings for the other representation should be untouched)

Screenshots

Screen.Recording.2026-04-07.at.10.43.01.AM.mp4

Pending tasks

• When schemas PR is merged & released, install the new @dcl/schemas version.
• When UI2 PR is merged & released, install the new decentraland-ui2 version.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
builder	Ready	Preview, Comment	Apr 10, 2026 1:21pm