# 🔗 6. Sockets & Attachments (Weapons & VFX)

One of the biggest challenges with GPU-driven animation is that the CPU has no idea where the character's bones are. Traditionally, if you wanted to attach a sword to a GPU-animated hand, you had to read data back from the video card, resulting in a noticeable 1-frame lag.

**GPU Animation Entities PRO solves this completely.**\
By baking bone matrices into highly optimized `BlobAssets`, our Burst-compiled `AnimatorAttachmentSystem` can synchronously calculate the exact bone position on the CPU with **zero latency**. Your weapons, armor, and particle effects will stick to your units flawlessly.

Here is how to set up and manage attachments using our visual editor.

***

#### Step 1: Expose the Bones (Prerequisite)

Before you can attach anything to a bone, the system needs to know which bones to track.

1. Open the **Animator Baker** window and assign your source `GameObject`.
2. Go to the **Bones** tab.
3. Click **Add the bone to the bake list**.
4. Select the bones you plan to use (e.g., `Spine` for stowing a weapon, `RightHand` for holding it).
5. Click **Process** to bake your DOTS Prefab.

> 🛑 **Warning:** If you do not add a bone to this list during baking, it will not be available in the Socket system later!

***

#### Step 2: The Prefab Animation Settings Window

Once your DOTS Prefab is generated, you can configure its attachments visually.

1. Locate your generated DOTS Prefab in the Project window (inside the Character folder).
2. **Double-click the Prefab** to open it in Unity's Prefab Isolation Mode.
3. A custom window named **Prefab Animation Settings** will automatically open.\
   (If you accidentally close it, you can reopen it by clicking the "Sockets Window" button in the Prefab's Inspector).

In this window, you will see a **Preview Settings** section where you can select any of your baked animations and scrub through the frames using the slider. Your character in the Scene view will animate accordingly!

***

#### Step 3: Setting the Default State

Let's attach a sword to the character's back.

1. In the **Attachments** section, click **Add Attachment**.
2. A new slot will appear. Drag and drop your weapon or VFX Prefab into the **Attachment** object field.
3. Click the **show** button next to it. A green "ghost" mesh of your weapon will appear in the Scene view.
4. In the **Attachment Details** panel below, look at the **Default State**.
5. Select a bone from the dropdown (e.g., Spine) and click **Attach**.
6. Now, use Unity's standard Move and Rotate tools (W, E) in the Scene view to position the ghost weapon perfectly on the character's back.

The system automatically calculates the local offset. Whenever this character spawns, the weapon will default to this position!

***

#### Step 4: Animation Events (Equipping Weapons)

What if the character plays an "Equip" animation and needs to move the sword from their back to their hand? We use **Attachment Events**.

1. In the **Preview Settings**, select your "Equip" animation from the dropdown.
2. Slowly drag the **Frame** slider until you find the exact moment the character's hand grabs the sword hilt.
3. In the **Attachment Details** panel, look at the **Add Event** section.
4. Select the new target bone (e.g., `RightHand`) from the dropdown.
5. Click **Add Event**.

***

#### Step 5: Spawning Attachments at Runtime (C# ECS)

You have configured the sockets visually, but how do you spawn them in your game code?

When you baked the prefab, the Baker automatically added an `AnimatorSlotsBuffer` to your character. This buffer contains the prefabs of all the attachments you configured.

Here is a quick ECS snippet showing how to spawn a character and their weapon together:

```csharp
using SnivelerCode.GpuAnimation.Runtime.Components;
using Unity.Entities;
using Unity.Transforms;

public partial struct SpawnCharacterWithWeaponSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        var ecb = new EntityCommandBuffer(Unity.Collections.Allocator.Temp);

        // Assuming you have a query to find your spawner and prefab
        foreach (var spawner in SystemAPI.Query<MySpawnerData>())
        {
            // 1. Spawn the Character
            Entity character = ecb.Instantiate(spawner.CharacterPrefab);
            
            // 2. Get the Slots Buffer (contains our weapon prefabs)
            var slotsBuffer = SystemAPI.GetBuffer<AnimatorSlotsBuffer>(spawner.CharacterPrefab);
            
            if (slotsBuffer.Length > 0)
            {
                // 3. Spawn the Weapon (Slot 0)
                Entity weapon = ecb.Instantiate(slotsBuffer[0].Value);
                
                // 4. Link the Weapon to the Character
                ecb.AddComponent(weapon, new AttachmentData 
                { 
                    CharacterEntity = character, 
                    SlotID = 0 // Matches the index in the AnimatorSlotsBuffer
                });
            }
        }

        ecb.Playback(state.EntityManager);
        ecb.Dispose();
    }
}
```

Once the `AttachmentData` component is added, the `AnimatorAttachmentSystem` takes over. It will automatically read the `Blob Asset`, track the current animation frame, trigger your equip/unequip events, and update the weapon's `LocalToWorld` matrix every frame!


---

# 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/6.-sockets-and-attachments-weapons-and-vfx.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.