# Sub-Mesh

### Intro

Meshes in Cavalry can contain a hierarchy of other Shapes within them. We refer to these meshes as ‘Sub-Meshes’. This hierarchy is a tree structure, much like the [Scene Window](https://scenegroup.gitbook.io/cavalry/user-interface/menus/window-menu/scene-window), only it exists inside a Shape.

For example, [Text](https://scenegroup.gitbook.io/cavalry/nodes/shapes/text-shape) consists of **Lines**, **Words** and **Characters**, a [Duplicator ](https://scenegroup.gitbook.io/cavalry/nodes/shapes/duplicator)is built of many **Input Shapes** and [SVG](https://scenegroup.gitbook.io/cavalry/nodes/shapes/svg-shape)s can have any number of layers. The **Sub-Mesh** Behaviour provides a way to access and affect these individual meshes by specifying the level(s) within a hierarchy.

### UI

[Common Attributes](https://scenegroup.gitbook.io/cavalry/nodes/behaviours/common-attributes-behaviours) +

**Position** - set the X and Y position. 0,0 is in the centre of your comp.

**Rotation** - set the rotation (in degrees).

**Scale** - set the X and Y scale values.

**Opacity** - set the opacity.

**Visibility** - affect the sub-shape's visibility on a per shape basis.

**Time Offset** - set the animation curve for duplicates on a per shape basis. *Tip - connect a Stagger node*

**Center Pivot** - centre the pivot to each sub-mesh's bounding box.

**Deformers** - a list of connected Deformers. 

**Filters** - a list of connected [Filters](https://scenegroup.gitbook.io/cavalry/nodes/effects).

**Level Mode** - choose which level(s) of a sub-mesh to affect.

* **Custom...** - manually set a **Custom Level Range**.
* **Text (Lines)** - used with a **Text Shape**, this will affect each **line**.
* **Text (Words)** - used with a **Text Shape**, this will affect each **word**.
* **Text (Characters)** - used with a **Text Shape**, this will affect each **character**.
* **All** - affects all sub-meshes, regardless of level.

{% hint style="info" %}
The **Level Mode** provides several settings designed to make working with **Text** easier. For example, the **Text (Words)** mode sets internal **Custom Level Range** values of `2, 2`. While these settings will affect any words in a [Text Shape](https://scenegroup.gitbook.io/cavalry/nodes/shapes/text-shape), the same settings can also be valid for an [SVG Shape](https://scenegroup.gitbook.io/cavalry/nodes/shapes/svg-shape).
{% endhint %}

**Custom Level Range** - set the level within the Sub-Mesh's hierarchy to affect. This can also be used to set a range of levels. For example, setting a range of `1, 2` might be used to override the color of an SVG for all the shapes on levels 1 and 2 but not on level 3.

{% hint style="info" %}
As the Level value increases the Sub-Mesh travels deeper into the Shape's hierarchy.
{% endhint %}

**Flatten Mesh at Level** - all sub-meshes below this level will be merged and brought up to this one.

### **Fill and Stroke**

**Sub-Mesh** also has Fill and Stroke tabs. They are identical to those found on [Shapes](https://scenegroup.gitbook.io/cavalry/nodes/shapes/common-attributes) apart from two exceptions.

**Replace Fill/Stroke** - when checked the Sub-Mesh will overwrite any materials on the shapes it is connected to with the Color and/or Shaders set in this tab.

**Replacement Mode** - by default, all materials will be replaced but, by using this option, you can target certain conditions:

* **Replace All** - Sub-Mesh will replace the Fill/Stroke of all sub-meshes.
* **Replace Missing** - Sub-Mesh will only replace the Fill/Stroke of any sub-meshes that **do not** have **Fill/Stroke** enabled.
* **Replace Existing** - Sub-Mesh will only replace the Fill/Stroke of any sub-meshes that **do** have **Fill/Stroke** enabled.

**Fill/Stroke Overrides** - see [Color Material Overrride](https://scenegroup.gitbook.io/cavalry/nodes/behaviours/color-material-override) and [Alpha Material Override](https://scenegroup.gitbook.io/cavalry/nodes/behaviours/alpha-material-override).

{% hint style="info" %}
Levels for [Text](https://scenegroup.gitbook.io/cavalry/nodes/shapes/text-shape) are as follows:

1. Line.
2. Word.
3. Character.
   {% endhint %}

{% hint style="success" %}
Example usage:

1. Create a [Text Shape](https://scenegroup.gitbook.io/cavalry/nodes/shapes/text-shape).
2. Create a **Sub-Mesh** node.
3. Connect ***subMesh.id*** > ***textShape.deformers***
4. Set **Position Y** on the **Sub-Mesh** to 30
5. Right click on the **Falloff** attribute and select '*Add Falloff'.*

When you animate the Falloff through the text each letter will move up 30px.
{% endhint %}


---

# 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://scenegroup.gitbook.io/cavalry/nodes/behaviours/sub-mesh.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.