> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-pt/wearables-e-emotes/wearables/spring-bones.md).

# Spring Bones

### O que são Spring Bones?

Spring bones (também conhecidos como jiggle bones ou physics bones) são bones extras adicionados a um wearable que se movem dinamicamente em resposta ao movimento do avatar e à gravidade, em vez de serem guiados por animation clips. Eles dão vida a elementos como hair, earrings, capes, belts, ponytails e outros acessórios pendentes, fazendo-os balançar, quicar e assentar naturalmente conforme o avatar anda, corre ou gira.

Os spring bones são **não** parte da armature base do avatar. Eles são bones adicionais que você adiciona ao esqueleto base do avatar no Blender (ou em qualquer software 3D), e o comportamento físico deles é configurado no Builder após o upload.

Esta implementação segue o [padrão VRM Spring Bone](https://vrm.dev/en/vrm1/springbone/), uma convenção amplamente adotada para physics de avatar em formatos como VRM e MMD.

![](/files/9eeb5171dea1d3834ae025b2438f229048347005)

### Como os Spring Bones Funcionam

Uma **spring chain** é uma sequência de bones que simula física em conjunto e deve ter pelo menos dois bones: o spring bone real e um end bone. Um único spring bone sozinho não produzirá nenhum movimento — a simulação precisa da cabeça do spring bone para acionar a física e a cabeça do end bone definirá o endpoint geométrico. Chains mais longas (3+ bones) terão movimento mais suave e natural, ideal para cabelos longos ou capes.

1. **Spring bone pai** — O primeiro bone na chain. Ele possui a configuração de física (stiffness, gravity, drag, etc.). Identificado por ter `springbone` em qualquer parte do nome do bone (case-insensitive).
2. **Spring bone filho** — Ele é o child do bone anterior na hierarchy. Ele herda os parâmetros de física do parent e forma a chain.
3. **Spring bone final** — O último bone na chain. Ele define o endpoint geométrico da chain, mas não é afetado pela simulação e não deforma nenhuma mesh.

A chain, ou hierarchy, para spring bones deve ser **linear**, o que significa que cada bone pode ter apenas um child. Bones com dois ou mais children podem apresentar um comportamento inesperado.

![Uma spring chain bonita e linear.](/files/f7dfe25e2b368b92ce77922344e2eb8318d6811f)

![Bones com 2 ou mais children terão um comportamento inesperado.](/files/994c03ab36d2e17a9e7514252ae1b0fd728421ca)

### A Hierarchy

Para que os spring bones funcionem bem, eles precisam ser parented a um dos bones originais do avatar. Para hairs e earrings, por exemplo, o bone no topo da hierarchy deve ser parented a ***Avatar\_Head***. Para scarves, parentar a chain para o ***Avatar\_Neck*** é uma boa ideia. Para skirts, talvez ***Avatar\_Hips*** ou ***Avatar\_LeftUpLeg/Avatar\_RightUpLeg*** possa funcionar.

É importante notar como a estrutura desta hierarchy funciona.

* *Hair\_springBone\_1* (spring bone parent): este é o bone no topo da chain, ele possui a configuração de física
* *Hair\_springBone\_2* (child spring bone): este é o child do bone anterior na hierarchy e herda a configuração.
* *Hair\_springBone\_end* (spring bone end): é o último bone da chain e serve apenas como endpoint.

### Convenção de nomenclatura

Todos os spring bones **devem** conter a substring `springbone` (case-insensitive) no nome. A substring pode aparecer em qualquer posição:

* *SpringBone\_hair\_left*
* *hair\_springbone\_l*
* *springbone\_earring.R*

Para manter seu fluxo de trabalho organizado, é sugerido usar este formato: **BodyPart/WearableName\_springBone**

Exemplos: *Hair\_springBone\_1*, *Earring\_springBone.L* etc… Sinta-se à vontade para usar o formato que melhor se adequar a você, desde que siga a convenção de nomenclatura do Blender (ou do seu software preferido) para left e right.

{% hint style="warning" %}
Atenção!

Spring bones não funcionarão sem `springbone` no nome do bone. Isso precisa ser usado, inclusive no end bone.
{% endhint %}

### Limites

Cada wearable deve permanecer dentro dos seguintes limites de spring bone:

* Máximo **6** spring chains por wearable
* Máximo **12** total de spring bones (soma de todos os bones em todas as chains)
* Profundidade máxima de chain de **6** bones

## Criando Spring Bones no Blender

Spring bones são bones adicionais que você cria no Blender para a armature base do avatar. Os parâmetros de física são configurados depois no Builder — você só precisa configurar a hierarchy dos bones agora.

Para criar um novo bone, selecione a Armature do avatar e, em **Edit Mode**, certifique-se de estar com o cursor onde deseja que o bone seja criado e pressione **Shift+A**. Outra forma de fazer isso seria duplicando um bone existente pressionando **Shift+D**. Depois de ter o primeiro bone da chain, pressione **E** para extrudi-lo e criar o restante da chain.

![Pressione Shift+A para criar um bone onde o cursor estiver.](/files/87ea5e25fb10a5d3c7abf3b5eca8a38c006ab436)

É importante notar que uma spring chain não precisa estar conectada ao skeleton parent, então você pode colocá-la em qualquer lugar na mesh. No entanto, a spring chain **tem** de estar conectada, você não pode deslocar nenhum dos spring bones.

Depois de criar os bones, renomeie-os seguindo a convenção de nomenclatura mencionada acima e certifique-se de parentar a chain ao bone correto. Linhas pontilhadas mostrarão o parent da chain. Se não houver nenhuma, significa que a chain não tem parent. Em **Edit Mode**, selecione primeiro o child, depois selecione o parent e pressione **Ctrl+P** > **Keep Offset**.

![Parent os bones selecionando primeiro o child, depois o parent e pressione Ctrl+P.](/files/53e6c036722340be159b39e2bdaa9883dfd43580)

Para renomear um bone, selecione-o em Edit Mode ou Pose Mode, vá para a aba Bone Properties e renomeie-o de acordo com a convenção de nomenclatura. Faça isso para todos os bones da chain.

![](/files/c1941adc8c3cce98838b912940e660a53814af4c)

{% hint style="info" %}
Dica!

Para garantir que o bone esteja posicionado corretamente, selecione a mesh em **Object Mode** e, em **Edit Mode**, selecione os vertices na área onde você quer posicionar o bone (pode ser um loop ou um grupo de vertices) > pressione **Shift+S** > **Cursor to Selected.**

Volte para **Object Mode**, selecione a armature > vá para **Edit Mode** > selecione o bone desejado > **Shift+S** > **Selection to cursor**.
{% endhint %}

![Use Shift+S para posicionar o bone no lugar certo na mesh.](/files/988956ad3497af5d5e2f0c8545f9ad816bad0080)

### Skinning da Mesh

Skinning é o processo de vincular a mesh à armature, para que elas se movam juntas. Para isso, definimos quanta influência (weight) cada bone terá sobre os vertices. Quanto mais weight, mais o bone deformará a mesh. Para fazer isso, vá para **Object Mode**, selecione a mesh primeiro, pressione **Shift** e selecione a armature, pressione **Ctrl+P**. Há duas formas de fazer isso, selecione **Com grupos vazios** ou **Com pesos automáticos**.

![](/files/acefcec746e60350316625aba2d0453c85324708)

#### Com pesos automáticos

Como o nome indica, com este método, o Blender tentará definir os skin weights automaticamente criando vertex groups para cada bone na armature e dando a cada um deles weights automáticos. Isso pode funcionar em alguns casos, mas também pode exigir alguns ajustes. Você pode verificar os groups criados clicando na **Data** aba.

Se você souber com certeza que não precisará que certos bones afetem a mesh, basta clicar no **ícone de cadeado** para bloquear os groups que você deseja, clique no menu suspenso e **Delete All Unlocked Groups** para removê-los do objeto. Por exemplo, se você estiver trabalhando em hair, ter groups para feet e hands não faz sentido. Nesse caso, delete tudo que não for a head ou os spring bones, como no exemplo abaixo. Certifique-se também de deletar o group para o end bone da spring chain.

![Excluindo vertex groups.](/files/5e1270f986a6ee2803119ed0f7d1cdc7dfca7e81)

#### Com grupos vazios

Neste método, o Blender criará todos os vertex groups para cada bone na armature, mas eles terão weight zero por padrão. Você terá que atribuir os weights manualmente em Edit Mode ou pintá-los no modo Weight Paint. Isso lhe dá mais controle sobre o que está sendo afetado por cada group e pode ser especialmente útil para superfícies rígidas ou objetos que precisam ser completamente atribuídos a um determinado group. Em qualquer caso, depois de atribuir os weights, eles precisarão ser testados em Pose Mode e depois ajustados em Weight Paint.

![Parenting com grupos vazios.](/files/e11ab139a3e3ec12643ffffc58d7c6d1719ba518)

#### Pintando weights

Para testar a mesh skinada, selecione a armature e vá para **Pose Mode**, defina um keyframe, depois gire os bones para criar outra pose e defina outro keyframe. Assim, você pode verificar como a mesh está deformando com o movimento. Depois de definir as poses, volte para **Object Mode**, selecione a mesh e vá para **Weight Paint**.

![](/files/9b431804a8fc0db596662d9967b8ba448b1f2cd4)

Em **Weight Paint**, na aba Tools você encontrará diferentes brushes para ajustar os skin weights. Selecione o Vertex Group que deseja editar (se estiverem bloqueados, basta desbloqueá-los para poder editar a influência) e use o brush para adicionar ou remover influência. Preto significa zero influência, enquanto vermelho significa que aquele group influencia totalmente a mesh. Ativar o wireframe em **Overlays** facilitará ver o que você está pintando.

![](/files/a76136154670b3f93389c35cd38fecdac881dc53)

Use os brushes de add, subtract ou smooth para obter o resultado desejado. Teste também diferentes poses extremas para ver como a mesh está deformando e se não há vertices sem weights. Se você estiver satisfeito com o resultado, é hora de exportá-lo!

### Exportando

Antes de exportar, certifique-se de apagar qualquer animation clip criado ao testar as poses. Vá para Pose Mode, selecione todos os bones pressionando **Uma** e pressione **Ctrl+R**, depois **Ctrl+S** e finalmente **Ctrl+G** para apagar qualquer transform na sua armature. Depois volte para o object mode, altere o Display Mode de View Layer para Blender File, expanda Actions e clique com o botão direito e delete o animation file.

![](/files/b3c4af61203667e4d93ec6078d5a2ade957a1680)

Se você tiver outros objects na sua scene, como avatar mesh, desative a visibilidade clicando no ícone de olho no Outliner. Depois, vá para **File** > **Export** > **gltf 2.0 (.glb, .gltf)**. Para as export settings, expanda Include e, em **Limit to** ative **Visible Objects**. Clique em Export e você estará pronto para enviar seu arquivo para o Builder!

![](/files/76c197c4cbdc6ccd57cfb6cd38c7c06e846f3ccf)

## Configurando Spring Bones no Builder

Depois de fazer upload de um wearable que contém `springbone`-named bones, o Builder os detecta automaticamente e mostra o **Spring Bones** painel de configuração.

![](/files/114950882584962dd7f59036402750e9a8746d68)

Neste painel, você pode configurar os parâmetros de física para cada spring root bone. A prévia do avatar no Builder refletirá suas alterações imediatamente, então você pode ajustar o comportamento em tempo real.

{% hint style="info" %}
Você não pode adicionar novos spring bones pelo Builder. Os bones já devem existir no arquivo `.glb` enviado com a convenção de nomenclatura correta. O Builder apenas permite configurar os parâmetros de física para spring bones detectados.
{% endhint %}

### Referência de Parâmetros

#### Stiffness Force

|             |       |
| ----------- | ----- |
| **Range**   | 0 a 4 |
| **Default** | `2.0` |

Controla o quão fortemente o bone tenta retornar à sua pose de repouso. Esta é a força de restauração — pense nela como a "rigidez" da spring.

* **0**: O bone não retornará ao repouso de forma alguma — ele apenas ficará caído sob a gravidade.
* **Valores baixos** (ex.: 0–1): O bone fica solto e mole, balançando livremente. Bom para cabelos longos e fluidos ou acessórios pendentes leves.
* **Valores altos** (ex.: 3–4): O bone fica rígido, permanecendo próximo de sua posição original e voltando rapidamente. Bom para cabelos curtos ou acessórios rígidos.

#### Gravity Power

|             |       |
| ----------- | ----- |
| **Range**   | 0 a 2 |
| **Default** | `0`   |

Controla a magnitude da força da gravidade que puxa o bone a cada frame.

* **0**: Sem efeito de gravidade — o bone é afetado apenas pela inércia do movimento e pela stiffness.
* **Valores baixos** (ex.: 0.3–0.8): Puxão gravitacional sutil, bom para a maioria dos acessórios.
* **Valores altos** (ex.: 1.5–2.0): Puxão gravitacional forte, fazendo o bone pender bastante.

#### Gravity Direction

|             |                                  |
| ----------- | -------------------------------- |
| **Format**  | X, Y, Z vector                   |
| **Default** | `X: 0, Y: -1, Z: 0` (para baixo) |

Define a direção da força da gravidade no espaço global. Por padrão, a gravidade puxa para baixo (Y = -1), simulando a gravidade natural.

| X  | Y  | Z  | Effect                                       |
| -- | -- | -- | -------------------------------------------- |
| 0  | -1 | 0  | Para baixo (gravidade natural, padrão)       |
| 0  | 1  | 0  | Para cima (efeito de flutuação/sobrenatural) |
| 1  | 0  | 0  | Para a esquerda                              |
| -1 | 0  | 0  | Para a direita                               |
| 0  | 0  | 1  | Para frente                                  |
| 0  | 0  | -1 | Para trás                                    |

Você pode combinar eixos (ex.: `X: 0.5, Y: -0.5, Z: 0`) para direções diagonais. Isso é útil para simular efeitos semelhantes ao vento ou criar uma aparência flutuante para personagens sobrenaturais.

#### Drag Force

|             |       |
| ----------- | ----- |
| **Range**   | 0 – 1 |
| **Default** | `0.5` |

Controla quão rapidamente o bone perde momentum e se estabiliza. Pense nisso como resistência do ar ou amortecimento.

* **Valores baixos** (ex.: 0–0.2): O bone balança livremente por um longo tempo antes de se estabilizar, como um pêndulo com pouca fricção.
* **Valores altos** (ex.: 0.7–1.0): O bone se estabiliza quase instantaneamente após o movimento, dando uma sensação pesada ou amortecida.
* **1**: O bone mal se move — desaceleração máxima.

#### Center (Optional)

|             |                      |
| ----------- | -------------------- |
| **Format**  | Bone name (dropdown) |
| **Default** | None                 |

Um bone de referência opcional usado para calcular o movimento do spring bone em relação a um ponto do avatar, em vez de em relação ao espaço global. Isso evita que a spring chain balance excessivamente quando o avatar se movimenta (andando, correndo).

**Sem um center bone**, os springs calculam a inércia no espaço global — cada passo que o avatar dá faz os bones reagirem como se o mundo inteiro se movesse, resultando em balanço exagerado durante a locomoção.

**Com um center bone**, a simulação usa o espaço desse bone como frame de referência, então apenas os movimentos do avatar *locais* (virar a cabeça, curvar o corpo) disparam a reação da spring.

Escolha o center bone com base em onde o wearable está localizado no corpo:

| Wearable location                     | Recommended center bone |
| ------------------------------------- | ----------------------- |
| Head (hair, earrings, tiaras)         | `Avatar_Head`           |
| Upper body (capes, necklaces)         | `Avatar_Spine`          |
| Lower body (belts, skirt accessories) | `Avatar_Hips`           |

{% hint style="warning" %}
O center bone **não deve** fazer parte de nenhuma spring chain. Ele deve ser um bone da armature base do avatar.
{% endhint %}

## Casos de uso comuns e valores recomendados

Estes são pontos de partida sugeridos. Ajuste ao seu gosto usando a prévia em tempo real do Builder.

| Use case                | Stiffness | Gravity Power | Gravity Dir | Drag      | Center         | Notes                                                        |
| ----------------------- | --------- | ------------- | ----------- | --------- | -------------- | ------------------------------------------------------------ |
| Long hair / ponytail    | 1.0 – 2.0 | 0.3 – 0.8     | 0, -1, 0    | 0.3 – 0.5 | `Avatar_Head`  | Mais bones na chain = movimento mais suave                   |
| Short hair              | 3.0 – 4.0 | 0 – 0.3       | 0, -1, 0    | 0.4 – 0.6 | `Avatar_Head`  | Maior stiffness mantém o cabelo próximo à cabeça             |
| Earrings                | 0.5 – 1.5 | 0.5 – 1.0     | 0, -1, 0    | 0.4 – 0.6 | `Avatar_Head`  | Chain curta (2–3 bones), menor stiffness para ficar pendente |
| Cape / cloak            | 1.0 – 2.0 | 0.5 – 1.0     | 0, -1, 0    | 0.3 – 0.5 | `Avatar_Spine` | Múltiplas chains paralelas para dar largura                  |
| Belt / hanging ornament | 1.5 – 2.5 | 0.3 – 0.8     | 0, -1, 0    | 0.5 – 0.7 | `Avatar_Hips`  | Maior drag para itens mais pesados                           |
| Floating / ghost effect | 1.0 – 2.0 | 0.5 – 1.0     | 0, 1, 0     | 0.3 – 0.5 | `Avatar_Spine` | Gravidade para cima para um visual sobrenatural              |

## Limitações

Tenha em mente as seguintes limitações ao trabalhar com spring bones:

* **No colliders**: Spring bones não colidem com o corpo do avatar nem com outros bones. As chains podem atravessar a mesh do corpo em poses extremas. Versões futuras podem adicionar suporte a colliders.
* **No cross-wearable interactions**: As spring chains de cada wearable são independentes. Chains de wearables diferentes não afetam umas às outras.
* **No global wind**: Não há uma força de vento em nível de scene. Você pode aproximar um efeito de vento por wearable ajustando o `gravityDir` para uma direção diagonal.
* **Performance on remote avatars**: A simulação de spring bone é desativada para avatars que estão longe do local player para economizar desempenho. Avatars próximos exibirão a física de spring bone normalmente.
* **Alternative clients compatibility**: Wearables com spring bones são retrocompatíveis com clientes alternativos e versões mais antigas do Explorer, mas os elementos de spring bone permanecerão estáticos. Em alguns casos, pode haver pequenos problemas visuais.

## Referência Técnica

A física de spring bone usa dois artefatos separados que trabalham juntos:

1. **O `.glb` file** contém apenas os nomes dos bones (com o `springbone` token) e sua hierarchy. Nenhum parâmetro de física é armazenado no model file.
2. **Os metadados do wearable** (`wearable.data.springBones`) armazena todos os parâmetros de física como JSON.

Quando você configura parâmetros no Builder, eles são salvos nos metadados do wearable — o `.glb` file nunca é modificado pelas edições de parâmetros.

Você não precisa interagir diretamente com este formato — o Builder cuida da leitura e gravação. Esta seção é fornecida para referência.

### `.glb` Hierarquia de Nós (exemplo)

O arquivo de modelo contém apenas os nomes dos bones e as relações parent-child:

```json
{
  "asset": {"version": "2.0"},
  "nodes": [
    {"name": "Avatar_Head", "children": [1, 2]},
    {"name": "SpringBone_earring_r", "children": [3]},
    {"name": "SpringBone_hair_left", "children": [4]},
    {"name": "springbone_earring_r_tip"},
    {"name": "SpringBone_hair_left_tip"}
  ]
}
```

### Metadados do Item (`wearable.data.springBones`)

Os parâmetros de física são armazenados nos metadados do wearable, indexados pelo hash de conteúdo do GLB:

```json
{
  "version": 1,
  "models": {
    "bafkreialsvt77jvpy673cnugp5ggnxfaalfncufweayuk3jbxskh3pelkm": {
      "SpringBone_earring_r": {
        "stiffness": 0.5,
        "gravityPower": 1.0,
        "gravityDir": [0, -1, 0],
        "drag": 0.6,
        "isRoot": true,
        "center": "Avatar_Hips"
      },
      "SpringBone_hair_left": {
        "stiffness": 2.0,
        "gravityPower": 0.8,
        "gravityDir": [0, -1, 0],
        "drag": 0.4,
        "isRoot": true
      }
    }
  }
}
```

* `models` é indexado pelo hash de conteúdo do GLB. Wearables cujas representações masculina e feminina compartilham o mesmo `.glb` têm uma única entrada.
* Cada entrada de osso usa o nome exato do nó do `.glb` (diferencia maiúsculas de minúsculas).
* Os ossos da ponta (por exemplo, `springbone_earring_r_tip`) não precisam de uma entrada de metadata — servem apenas como pontos finais geométricos.

### Parâmetros de metadata

| Parâmetro      | Tipo    | Default      | Descrição                                                                             |
| -------------- | ------- | ------------ | ------------------------------------------------------------------------------------- |
| `stiffness`    | float   | `2.0`        | Força de restauração em direção à pose de repouso. Intervalo: 0–4.                    |
| `gravityPower` | float   | `0`          | Magnitude da força da gravidade. Intervalo: 0–2.                                      |
| `gravityDir`   | vec3    | `[0, -1, 0]` | Direção da gravidade no espaço mundial.                                               |
| `drag`         | float   | `0.5`        | Fator de amortecimento / desaceleração. Intervalo: 0–1.                               |
| `isRoot`       | boolean | —            | Se este nó é a raiz de uma cadeia de spring. É necessário ser `true` para ossos raiz. |
| `center`       | string  | —            | Opcional. Nome de um osso de referência para o cálculo de inércia relativa.           |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.decentraland.org/creator/content-creator-pt/wearables-e-emotes/wearables/spring-bones.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.