# Bone hierarchy in vehicle models

## Basis bone

The `basis` bone serves as the **root bone** in the skeletal hierarchy of any vehicle model. \
It functions as a **dummy helper** that defines critical properties of the model, including:

* model type;
* export path for the model to the game;
* wheel rotation speed and size (applied if all wheels are uniformly sized; otherwise, sizes are set in individual wheel bones);
* inverse kinematics (IK) parameter `IKType=revolute` with rotation constraints, if the vehicle supports body rotation.
* animation type and duration for key sequences;

<figure><img src="/files/5GWHcqAtrkjbcsdDFWG0" alt="Object properties of basis bone" width="563"><figcaption><p>Example Object Properties  window of the <code>basis</code> bone</p></figcaption></figure>

### Placement and orientation of the basis bone

* The `basis` bone is positioned at the **origin point** `(X=0, Y=0, Z=0)` in world space, ensuring the model aligns correctly within the game.
* In the **"Front" orthographic view**, the vehicle is displayed from the **right side**, which must be accounted for during configuration.
* The **forward movement vector** of the `basis` bone—and consequently the entire model—is aligned with the **positive X-axis**.

<figure><img src="/files/z01R0YkOP2uHpKqVvfVP" alt="Example: Orientation of the basis bone in the &#x22;Front&#x22; orthographic view"><figcaption><p>Example: Orientation of the <code>basis</code> bone in the "Front" orthographic view</p></figcaption></figure>

**Accurate orientation of the `basis` bone is vital for:**

* proper alignment and movement of the model in the game space;
* correct placement and visualization of the **selection circle sprite** beneath the model.

<figure><img src="/files/sqHSuHxAhLDQha5W6CUA" alt="Example: Selection circle alignment under a tank model when the unit is selected"><figcaption><p>Example: Selection circle alignment under a tank model when the unit is selected</p></figcaption></figure>

## Visible bones of the vehicle model

**Visible bones** of the model are the **primary bones** and **secondary bones** in the model's element hierarchy that contain the meshes of the model's components.

### **Primary bones**

{% hint style="info" %}
**Primary bones** represent the parent bones in the model element hierarchy, forming the primary part of the visible mesh of **vehicle components**
{% endhint %}

The primary bones include the following bones:

* `body` (hull);
* `turret`;
* `cabin`;
* `gun_rot` (gun elevation mechanism);
* `gun`;
* `engine`;
* `track` and `wheel` (transmission bones).

<figure><img src="/files/zakY2SMiZqrSZ2LImOo1" alt=""><figcaption><p>Primary bones hierarchy scheme</p></figcaption></figure>

### **Secondary bones**

{% hint style="info" %}
**Secondary bones** of a model are bones that contain the mesh of additional visual elements for Сomponents. They are used to add detail and variability, complementing the primary components of the model, such as the Hull, Engine, or Turret.
{% endhint %}

The secondary bones include the following bones:

* `detail` (visual detail);
* `shield` (additional armor part);
* `enumerator` (vehicle identifier);
* `cover`/`door`;
* bones associated with the vehicle's suspension mechanism.

**Secondary bones** are typically linked to the **primary bones** they are part of.

<figure><img src="/files/ni7knHFk84fiONtGsDWx" alt=""><figcaption><p>Illustration of linking secondary bones to the primary bone</p></figcaption></figure>

## Bone properties

Properties of **bones** are defined in the **Object Properties** window.

<table><thead><tr><th width="249">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>poly</code></td><td>Defines bone visibility. <br>Absence of this parameter makes the bone invisible.</td></tr><tr><td><code>ID=&#x3C;value></code></td><td>Component identifier. <br>Links the bone to a specific <strong>vehicle component</strong> (e.g., Hull, Turret, Left track, Gun).</td></tr><tr><td><code>Animation=&#x3C;name></code></td><td>List of animations if the bone is animated</td></tr><tr><td><p><code>IKType=revolute</code>, </p><p><code>IKType=socket</code>, </p><p><code>IKSpeed=&#x3C;value></code>, </p><p><code>IKLimit=&#x3C;value></code>.</p></td><td>Inverse kinematics parameters allow the bone to operate under IK rules, setting the speed and rotation limits for the bone.</td></tr></tbody></table>

<figure><img src="/files/mYdGOaVU4506TNbmeC6O" alt="Example of turret component properties"><figcaption><p><strong>Example of turret component properties</strong></p></figcaption></figure>

### ID values for vehicle components

<table data-header-hidden><thead><tr><th width="230">ID</th><th>Component</th></tr></thead><tbody><tr><td><code>body</code></td><td>Hull</td></tr><tr><td><code>engine</code></td><td>Engine</td></tr><tr><td><code>cabin</code></td><td>Vehicle cabin</td></tr><tr><td><code>turret</code></td><td>Turret</td></tr><tr><td><code>gun</code></td><td>Gun</td></tr><tr><td><code>trackleft</code> / <code>trackright</code></td><td>Left /Right tracks</td></tr><tr><td><code>wheelright&#x3C;N></code> / <code>wheelleft&#x3C;N></code></td><td>Right and Left wheels (<code>&#x3C;N></code> is the wheel's index)</td></tr></tbody></table>

The ID value of **secondary bones** corresponds to the ID value of the **primary bones** of which they are a visual part.

{% hint style="warning" %}
Despite identical naming, a bone is not equivalent to a **vehicle component**.&#x20;

A **vehicle component** can consist of multiple bones with different names but the same ID value. As a whole, bones with the same ID form a specific vehicle component in the game.&#x20;

**Examples:**

* the bones `turret`, `cover`, and `detail`, each assigned the property `ID=turret`, together form the **Turret** component in the game;
* the bones `body`, `cover`, and `detail`, each assigned the property `ID=body`, together form the **Hull** component in the game.
  {% endhint %}

### Animation types for components

* `break`: destruction animation assigned to the bone of the intact part of the model, representing the undamaged **vehicle component**.
* `repair`: animation for repairing the **х-model** of a **vehicle component**.

***

To explore more about configuring the hierarchy of visible bones, consult the following articles

<table data-view="cards"><thead><tr><th data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><a href="/pages/4UCA6IygjqSJZ65wOVCu">/pages/4UCA6IygjqSJZ65wOVCu</a></td><td><a href="/files/mmjkG9mjUJfGqO70kUCb">/files/mmjkG9mjUJfGqO70kUCb</a></td></tr><tr><td><a href="/pages/0bII5TQ7uy2F11elqueQ">/pages/0bII5TQ7uy2F11elqueQ</a></td><td><a href="/files/z9HhkLlcgc2ytqSJaMlL">/files/z9HhkLlcgc2ytqSJaMlL</a></td></tr><tr><td><a href="/pages/95KD3yp4Yw48vHQhyQN0">/pages/95KD3yp4Yw48vHQhyQN0</a></td><td><a href="/files/OQ1ttzCcRdkPMGT9uA6I">/files/OQ1ttzCcRdkPMGT9uA6I</a></td></tr><tr><td><a href="/pages/LKRi1klmDdNu7BIWHK5n">/pages/LKRi1klmDdNu7BIWHK5n</a></td><td><a href="/files/P2aevEoczdn1zyivP6Vu">/files/P2aevEoczdn1zyivP6Vu</a></td></tr><tr><td><a href="/pages/E36I3nF08DtenlnvfrGN">/pages/E36I3nF08DtenlnvfrGN</a></td><td><a href="/files/O9V8zhrSCxxeasLlId2x">/files/O9V8zhrSCxxeasLlId2x</a></td></tr><tr><td><a href="/pages/TPIJQKy5vZHPftOWv5Ph">/pages/TPIJQKy5vZHPftOWv5Ph</a></td><td><a href="/files/ni7knHFk84fiONtGsDWx">/files/ni7knHFk84fiONtGsDWx</a></td></tr></tbody></table>

## Helper bones

{% hint style="info" %}
**Helper bones** are invisible objects that define linkage points to support the model’s visual, functional, and animation elements
{% endhint %}

### Vision bones

* `visor1`: an invisible helper linked to the `turret` bone, representing the turret's field of view.
* `visor2`: an invisible helper acting as the "eyes" of the tank, aligned with the movement vector and linked to the `body` bone, positioned near the frontal armor's view slit.

These bones are aligned along the X-axis

### Special effects bones

Special effect bones (effectors) are used to create visual effects in the game. These bones are aligned along the X-axis for correct effect orientation.

<table data-header-hidden><thead><tr><th width="173"></th><th width="111"></th><th></th></tr></thead><tbody><tr><td><strong>Effector name</strong></td><td><strong>Purpose</strong></td><td><strong>Naming rules and specifics</strong></td></tr><tr><td><code>fxfire1</code></td><td>Engine fire effect</td><td>If multiple bones are needed, they are named sequentially (e.g., <code>fxfire1</code>, <code>fxfire2</code>, etc.).</td></tr><tr><td><code>fxfire2</code></td><td>Body fire effect</td><td>Similar naming convention as above.</td></tr><tr><td><code>fxfire3</code></td><td>Turret fire effect</td><td>The naming continues sequentially if additional bones are required.</td></tr><tr><td><code>fxshot</code></td><td>Dust effect from tank firing</td><td>This bone is used without variation in naming unless additional directional effects are required.</td></tr><tr><td><code>fxsmoke</code></td><td>Exhaust effects</td><td>For multiple exhaust effects, sequential numbering is added (e.g., <code>fxsmoke1</code>, <code>fxsmoke2</code>, etc.).</td></tr><tr><td><code>fxstop</code></td><td>Brake lights</td><td>If more than one brake light is needed, bones are named sequentially (e.g., <code>fxstop1</code>, <code>fxstop2</code>, etc.).</td></tr><tr><td><code>headlight</code></td><td>Headlight glow</td><td>If multiple headlights exist, side indices (<code>L</code> for left, <code>R</code> for right) are included in the names (e.g., <code>headlightL</code>).</td></tr><tr><td><code>fxlight</code></td><td>Additional headlight glow effects</td><td>Sequential numbering is added, but the first bone does not include a number (e.g., <code>fxlight</code>, <code>fxlight1</code>, <code>fxlight2</code>).</td></tr><tr><td><code>fxtrace</code></td><td>Dust and dirt from tracks or wheels</td><td>Bones are named sequentially with side indices (e.g., <code>fxtraceL1</code>, <code>fxtraceR1</code>, <code>fxtraceL2</code>, <code>fxtraceR2</code>).</td></tr><tr><td><code>foresight</code></td><td>Weapon or machine gun firing effects</td><td>If multiple effects are needed, the bones are numbered sequentially (e.g., <code>foresight1</code>, <code>foresight2</code>, etc.).</td></tr></tbody></table>

### Boarding animation bones

Helper bones known as `emit` define the starting points for boarding animations of crew and passenger units. Proper positioning of these bones is essential for accurate animation playback.

<table><thead><tr><th width="157">Name</th><th>Description</th></tr></thead><tbody><tr><td><code>emit0</code>, <code>emit1</code>, <code>emit2</code></td><td>Primary bones defining entry points for animations of crew boarding directly into the tank: <code>emit1</code> and <code>emit2</code> are positioned on either side of the model near the turret, while <code>emit0</code> is optional and used for a driver's hatch animation if present.</td></tr><tr><td><code>emit3</code>, <code>emit4</code>, <code>emit5</code>, etc.</td><td>Bones defining points in space near the tank, marking positions for soldiers boarding the vehicle's armor as passengers.</td></tr></tbody></table>

<figure><img src="/files/pq3fQaIKgfZfTMAyoH9J" alt=""><figcaption><p>Correct placement and orientation of <code>emit</code> bones for crew members and passengers boarding animations</p></figcaption></figure>

**Rules for `emit` bones**

* The **number of `emit` bones** must match the animation requirements. Missing bones can cause incorrect unit behavior.
* The **pivot orientation** of `emit` bones should align along the X-axis towards the `body` bone for proper crew alignment.
* These bones remain **invisible** and do not require properties in the **Object Properties** window.

### Passenger seating bones

Invisible `seat` bones define the seating positions for passengers on the vehicle’s armor and mark the endpoints of boarding animations starting from `emit` bones.

<table><thead><tr><th width="149">Bone name</th><th>Description</th></tr></thead><tbody><tr><td><code>seat01</code>, <code>seat02</code>, <br>etc.</td><td>Bones placed opposite their corresponding <code>emit</code> bones for passengers</td></tr></tbody></table>

**Rules for `seat` bones**

* The number of `seat` bones must match the `emit` bones for visible passengers.
* Proper positioning ensures realistic passenger animations.
* These bones remain invisible and do not require properties in the **Object Properties** window.

### Crew and gunner bones

In tank and vehicle models with open-top compartments, helper bones must be added and configured for all visible units, including crew members and gunners. These bones define positions and enable realistic functionality and animations, such as operating or firing mounted weapons.

<table><thead><tr><th>Bone name</th><th width="591">Description</th></tr></thead><tbody><tr><td><code>commander</code></td><td>Serves as the position for the tank commander and as a reference for playing animations related to the command role.</td></tr><tr><td><code>driver</code></td><td>Defines the position of the driver and enables animations for operating the vehicle.</td></tr><tr><td><code>charger</code></td><td>Serves as the position for the loader and as a reference for playing animations related to loading tasks.</td></tr><tr><td><code>gunner</code></td><td>Serves as the position for the main gunner and as a reference for playing animations related to using the machine gun.</td></tr><tr><td><code>gunner2</code></td><td>Serves as the position for the anti-aircraft gunner and as a reference for playing animations related to operating the anti-aircraft machine gun.</td></tr></tbody></table>

**Rules for crew and gunners bones**

* Proper positioning ensures realistic animations for units.&#x20;
* These invisible bones do not require any settings in the **Object Properties** window.

### Machine gun bones

Helper bones named `mgun` are used to designate machine gun mounting points on a vehicle. These bones can either be visible, incorporating a mounting mesh, or invisible, acting as a helper bone to mark positions, such as gun slots in the vehicle's hull. \
The `mgun` bone is linked to the component where the machine gun is intended to be mounted.

<figure><img src="/files/zMidOVosHzAN7InsWMM8" alt="Positioning of an invisible mgun bone"><figcaption><p>Positioning of an invisible <code>mgun</code> bone</p></figcaption></figure>

#### Properties of `mgun` bones

The properties of `mgun` bones are specified in the **Object Properties** window and can include the following parameters:

| `poly`                                                            | Makes the bone visible. Should be applied if the machine gun mesh is part of the model. If the gun is hidden or only the mounting point is present, the bone remains invisible. |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `IKType=revolute`                                                 | Enables inverse kinematics for rotational aiming.                                                                                                                               |
| <p><code>IKMin=\<value></code><br><code>IKMax=\<value></code></p> | Defines the minimum/maximum rotation limit for inverse kinematics.                                                                                                              |

<figure><img src="/files/OZL2pE1RmRRAPVM3nPEM" alt="Properties of a mgun bone operating with inverse kinematics"><figcaption><p>Properties of a <code>mgun</code> bone operating with inverse kinematics</p></figcaption></figure>

**Linking effectors to `mgun` bones**

Helpers named `foresight` are linked to `mgun` bones to spawn machine gun firing effects along the X-axis.

#### Naming rule for `mgun`-`foresight` linkage

{% hint style="success" %}
If the vehicle has multiple additional machine guns, the naming of the `foresight` helper must match the corresponding `mgun` bone:

* `mgun` → `foresight3`
* `mgun1` → `foresight4`
* `mgun2` → `foresight5`
* `mgun3` → `foresight6`
  {% endhint %}

{% hint style="danger" %}
Failure to follow the naming convention will result in script errors.
{% endhint %}

#### Configuring `mgun` bones

When modeling, it is essential to include a sufficient number of `mgun` bones to accommodate the maximum possible machine gun placements on the vehicle.&#x20;

<table><thead><tr><th width="181">Machine gun type</th><th>Description</th></tr></thead><tbody><tr><td><code>aa</code></td><td>Anti-aircraft gun</td></tr><tr><td><code>hull</code></td><td>Fixed machine gun mounted in the chassis</td></tr><tr><td><code>coaxial</code></td><td>Coaxial machine gun mounted in the turret</td></tr><tr><td><code>rear</code></td><td>Rear-mounted machine gun</td></tr></tbody></table>

The configuration for linking machine guns to bones is defined in the model's `.def` file within `placer` blocks.

> **Syntax:**
>
> ```
> {placer "mgun<N>" [...]}
> Where <N> represents the sequential number of the mgun bone.
> ```

<details>

<summary>Example of the mgun bone description in a .def file of a vehicle model</summary>

```
{place "mgun2"  
  {type "coaxial"}  
  {weapon "dt_vh" filled}  
  {foresight "foresight5"}  
  {gunner "gunner"}  
  {charger "gunner"}  
  ("sequential_aim")  
  ("abm_mgun")  
  {basic}  
}
```

</details>

## Volumes

A `volume` is a parametric shape (e.g., `box`, `sphere`, `cylinder`) or a mesh-based form (`edit poly`) that envelops the model's mesh and is used to calculate the physical interactions of the unit in the game.

### Creation and configuration of volumes

Bones of the `volume` type are created for all major bones of the model.\
Each primary bone requires its own volume or a set of volumes.

{% hint style="warning" %}
It is unnecessary to create volumes for `detail` bones because the game engine does not support volumes for visual parts.
{% endhint %}

The shape of the volume mesh should ensure realistic physical interactions. The `volume` parameter must be set in the **Object Properties** of the volume.\
A `Material ID` is assigned to the polygons of the volume mesh, which determines armor penetration calculations.

{% hint style="success" %}
Volumes should be extruded from a rectangle in the Top viewport. This ensures that `Material IDs` are automatically assigned to the volume surface, eliminating the need for additional verification or reassignment according to the established rules.
{% endhint %}

{% hint style="warning" %}
Volumes must remain standard primitives.\
Converting a primitive into polygonal forms using `editable poly` tools is recommended only when the complex geometry of a part of the model cannot be represented with a primitive.
{% endhint %}

Geometry adjustments at the sub-object level are permissible if the created model is not a single volume. In such cases, creating multiple `volume` bones with identical properties is allowed.\
There should be no gaps between such volumes; however, minor overlaps are acceptable.

<figure><img src="/files/lCjR16zjD5hyOvoBcbR0" alt="Example of volumes for the Body and Engine"><figcaption><p>Example of volumes for the Body and Engine</p></figcaption></figure>

**Examples of volume creation**\
In the first screenshot, the volumes are created correctly.\
In the second screenshot, the volume is created incorrectly as it obstructs projectiles/bullets from hitting units located in the cabin.

<figure><img src="/files/TOYhgxqs9BkI1VY4IpP1" alt="Сorrect volume modeling example"><figcaption><p>Сorrect volume modeling example</p></figcaption></figure>

<figure><img src="/files/wbvSkZBLVaTGycpmZxqO" alt="Incorrect volume modeling example"><figcaption><p>Incorrect volume modeling example</p></figcaption></figure>

### Rules for naming volumes

The volume covering the mesh of the main bone includes the name of that bone.\
For example: `body_vol`, `turret_vol`, `engine_vol`.

If multiple volumes cover a single bone, numbering is used in the volume names. The naming template is: `bonenameN_vol`, where `N` is the serial number.\
For example: `body01_vol`, `body02_vol`, `body03_vol`.

### Reassigning Material ID for polyhedron volume surfaces

In polyhedron volumes for the hull, each polygon must be assigned a `Select ID` value in the `Material IDs` parameter within the `Polygon` properties block. The value must strictly correspond to the following table:

* **Front** - `1`
* **Top** - `2`
* **Left** - `3`
* **Right** - `4`
* **Back** - `5`
* **Bottom** - `6`

The `ID` parameter determines the virtual armor of the vehicle components: front armor, side armor, rear armor, etc.

<figure><img src="/files/eJksFAOWcHRlXdT5Wjcz" alt=""><figcaption></figcaption></figure>

### Volumes for cabin windows

For vehicles and other units with windows, volumes are created for the glass.\
They are named `window<N>_vol`, where `<N>` is the unique index of the volume.

To add glass destruction animations, the `windowed` property must be included in the `props` block of the unit's `.def` file.

<figure><img src="/files/2oXbOqP3R5aTgfe8Tj4f" alt=""><figcaption></figcaption></figure>

### Special-purpose volumes

**Volume for ram collision**

The `ram_vol` volume is used to calculate collisions during vehicle ramming.\
It is a polyhedron with a central convexity to minimize the chance of the vehicle getting stuck when colliding perpendicularly with other objects.\
Assigning `Material ID` to surfaces is not required.

<figure><img src="/files/DlkVVoWdgIEesKnXuUga" alt=""><figcaption></figcaption></figure>

**Crew volume**

The `crew_vol` volume ensures interaction with the crew inside the vehicle.\
It is used in models of heavy vehicles with open cabins or transport vehicles with open cargo areas.\
This volume can be implemented as a primitive geometric shape or as a polyhedron, depending on the model structure.\
Assigning `Material ID` to surfaces is not required.

<figure><img src="/files/n70UEB0ouYFkrOlxy5Ui" alt=""><figcaption></figcaption></figure>

**Grenade catcher volume**

The `sticky_vol` volume is responsible for attracting grenades thrown at the vehicle to specific zones.\
It is used in heavy vehicles with open cabins or transport vehicles with open cargo areas.\
The volume is formed based on the internal space of the vehicle to increase the likelihood of a grenade entering the vulnerable area.

**Fuel tank volume**

The `fuel_vol` volume defines the geometry for interacting with external fuel tanks on vehicles.


---

# Agent Instructions: 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:

```
GET https://docs.bestway.com.ua/modeling/vehicle-model-setup-pipeline/bone-hierarchy-in-vehicle-models.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.