ACE3/docs/wiki/framework/attach-framework.md

---
layout: wiki
title: Attach Framework
description: Explains how to add items to the ACE Attach Framework.
group: framework
order: 0
parent: wiki
mod: ace
version:
  major: 3
  minor: 17
  patch: 0
---

## 1. Config Values
### 1.1 Make item attachable

An item can be added to the ACE Attach framework by adding the `ACE_attachable` property to a class in `CfgWeapons` or `CfgMagazines`. The value must be the classname of a valid class in `CfgVehicles`:
```cpp
class CfgWeapons {
    class attach_item: CBA_MiscItem {
        ACE_attachable = "new_attachable_item_classname";
    };
};

class CfgVehicles {
    class ThingX;
    class new_attachable_item_classname: ThingX {
        scope = 1; // Should be 1 (private) or 2 (public), scope 0 will cause errors on object creation
        displayName = "New ACE attachable item";
        model = "\path\to\my\model.p3d";
        vehicleClass = "";
    };
};
```

### 1.2 Define attach orientation for non-symmetric items
In the case the item needs to have a particular orientation when attached, add the config value: `ace_attach_orientation` which is an array describing the `roll` and `yaw` orientation of the object.
The default value is: `[0,0]`.

Example:
```cpp
class CfgWeapons {
    class attach_item: CBA_MiscItem {
        ACE_attachable = "new_attachable_item_classname";
        ace_attach_orientation[] = {0,180}; // 180deg yaw
    };
};
```

## 2. Event Handlers
### 2.1 Listenable Events

| Event Key | Parameters | Locality | Type | Description |
|----------|---------|---------|---------|---------|
|`ace_attach_attached` | [_attachedObject, _itemClassname, _temporary] | Local | Listen | After an item was attached to a unit/vehicle. _temporary flag means a item is being re-attached after the player exits a vehicle |
|`ace_attach_detaching` | [_attachedObject, _itemName, _temporary] | Local | Listen | Just before an item gets detached/removed from a unit/vehicle. _temporary flag means its detached because the player unit entered a vehicle. |

### 2.2 Other events for attached objects
Use [CBA Extended Event Handlers](https://github.com/CBATeam/CBA_A3/wiki/Extended-Event-Handlers-(new)). Note that objects attached to units will be deleted/created upon entering/exiting vehicles and should be handled accordingly.