# 🚑 10. Troubleshooting & FAQ

Even with automated baking pipelines, working with DOTS and GPU skinning can sometimes lead to unexpected results. This page covers the most common issues developers face and how to fix them instantly.

***

#### 👻 1. My characters are completely invisible!

This is the most common issue when setting up custom materials. If your meshes are not rendering at all, it means the vertices are collapsing to (0,0,0).

**Checklist to fix:**

1. **URP Settings:** Open your active URP Asset in the Inspector. Ensure **SRP Batcher** and **DOTS Instancing** are checked.
2. **Shader Graph Properties:** If you are using a custom Shader Graph, open it and check the Blackboard. Ensure you have two `Vector4` properties named exactly `_SnivelerRenderFrames` and `_SnivelerRenderFramesTarget`.
3. **Hybrid Rendered Checkbox:** Select those two properties in the Shader Graph and look at the Graph Inspector. The **Hybrid Rendered (DOTS Instancing)** checkbox MUST be enabled.
4. **Scene Renderer:** Ensure you have an `AnimatorRendererAuthoring` component in your `SubScene`, and your baked DOTS Prefab is assigned to its array.

***

#### 🦔 2. My characters look like spikes / are horribly deformed!

This happens when the C# script sends one type of mathematical data to the GPU, but the shader tries to read it as another type.

**Checklist to fix:**

1. **DQS Mismatch:** If you baked your prefab with **Use Dual Quaternion** enabled, your material must have the `_SNIVELER_DQS` keyword enabled.
2. **How to fix:** If you are using our templates `Sniveler_Lit_Template`, the Baker handles this automatically. If you are using a custom Shader Graph, ensure you added the `_SNIVELER_DQS` Boolean Keyword to your Blackboard (even if it's hidden/not exposed).
3. **Re-bake:** Sometimes simply clicking **Process** again in the Animator Baker window resolves keyword mismatches on generated materials.

***

#### ⚔️ 3. My weapons/attachments are spawning at (0,0,0) on the ground!

The Socket system relies on the `AttachmentData` component to link the weapon to the character.

**Checklist to fix:**

1. **Missing Component:** When you spawn the weapon via `EntityCommandBuffer.Instantiate`, you must manually add the `AttachmentData` component to it.
2. **Missing Link:** Ensure you set the `CharacterEntity` field inside AttachmentData to the Entity ID of the character holding the weapon.
3. **Missing Slot ID:** Ensure the `SlotID` matches the index of the weapon in the character's `AnimatorSlotsBuffer`.

Example of correct spawning:

```csharp
ecb.AddComponent(weaponEntity, new AttachmentData 
{ 
    CharacterEntity = characterEntity, 
    SlotID = 0 
});
```

***

#### 🛑 4. The Baker throws an error: "No shader selected" or "Shader does not use SnivelerAnimationNode"

The Baker validates your custom shaders before generating prefabs to prevent broken builds.

**Checklist to fix:**

1. **Missing Properties:** Your custom Shader Graph is missing the `_SnivelerRenderFrames` and `_SnivelerRenderFramesTarget` properties. Add them.
2. **Missing Node:** You forgot to add the `SnivelerAnimationNode` SubGraph to your custom shader, or you didn't connect it to the Vertex output block.
3. **Use Templates:** If you are struggling, delete your custom shader, right-click in the Project window, and select **Create > Shader Graph > Sniveler GPU Animation > Lit Shader**. Use this template as your starting point.

***

#### 🏃 5. My character is animating, but Root Motion isn't moving them!

**Checklist to fix:**

1. **Baker Setting:** Open the Animator Baker, select your source prefab, and ensure **Apply Root Motion** is checked in the Animator tab. Re-bake the prefab.
2. **Animator Controller:** Ensure the original animations in your Unity Animator Controller actually contain root motion data (the red trajectory line in the Animation preview window).
3. **Custom Physics:** If you are using a custom physics system, ensure you haven't accidentally deleted or overridden the `LocalTransform` after the `AnimatorRootMotionApplierSystem` runs. (See the **Root Motion** page for how to integrate with custom physics).

***

#### 📉 6. Performance drops when I spawn 20,000+ units

While the GPU can handle massive numbers, the CPU still needs to process the logic.

**Checklist to fix:**

1. **Burst Compilation:** Ensure **Jobs > Burst > Enable Compilation** is checked in the top menu. Running DOTS without Burst will destroy your framerate.
2. **Tick-Rate Optimization:** Select your `AnimatorRendererAuthoring` component in the `SubScene`. Reduce the **Half Tick Distance** and **Quarter Tick Distance** values. This forces distant units to update their logic at `30fps` or `15fps`, drastically reducing CPU load.
3. **LOD Aggressiveness:** Open the Animator Baker and check your LOD settings. Ensure your distant LODs (e.g., LOD 2) are set to **1 Bone** Quality and have **Interpolation** disabled. Re-bake.

***

#### 💬 Still need help?

If you've checked all the above and are still experiencing issues, we are here to help!\
Please reach out to us with a screenshot of your issue and any console errors:

📧 **Email:** [sniveler.code@gmail.com](https://www.google.com/url?sa=E\&q=sniveler.code)\
🌐 **GitHub:** <https://github.com/sniveler-code>


---

# 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://sniveler-code.gitbook.io/dots/gpu-animation-entities-pro/10.-troubleshooting-and-faq.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.