======Attach Points======
----

**Attach points** allow you to dynamically attach object models to [[character|characters]], [[tile|tiles]], or even other [[object|objects]] during the game (for example, to place a sword into a character's hand, a torch onto a dungeon wall, or a book onto a table).

=====Creating Attach Points=====
Attach points for models can be created with the "Create Attach Point" tool in the [[Voxel Editor]]. This tool can be selected using the shortcut key of "F8" or by clicking on the tool button with the "link" icon on the Model Tools panel. While active, left-clicking a voxel will place an attach point at that coordinate. The attach point's location can be adjusted later using the offset sliders (see next section).

After left-clicking a voxel, the editor will prompt for an attach point ID. Each attach point within a model frame must have an ID that is unique to that frame. Once added, a white cube with a "link" icon will be displayed at the new attach point's location.

<WRAP center round info 100%>
To change the ID for an attach point, selected the desired ID from the "Attach Points" dropdown on the [[Model Properties]] Panel, then click the "pencil" button to the right of the dropdown. A popup dialog will be displayed prompting for the new ID.
</WRAP>

<WRAP center round info 100%>
To remove a previously created attach point, select the desired ID from the "Attach Points" dropdown on the [[Model Properties]] panel, then click the red "X" button to the right of the dropdown. A popup dialog will be displayed to confirm its removal.
</WRAP>

=====Offset, Rotation, and Scale=====
There are several properties that can be adjusted for attach points from the [[Model Properties]] panel: //offset//, //rotation//, and //scale//. These properties affect an [[object|object's]] appearance when attached to that particular attach point. The settings for these properties can be assigned per frame, allowing attached [[object|objects]] to be animated along with the parent model.

^Property^Description^
|Offset|The offset values define the position of the attach point within the frame and is relative to the model grid's center (at ground level). When an [[object]] model (the "child") is attached to an [[entity]] (the "parent"), the attach points for the parent and child models will be connected together at their respective attach point locations.|
|Rotation|The rotation values determine the angle of an attached [[object]]. This can be used, for example, to angle a sword downward along with the swinging of a character's arm during an attack [[animation]].|
|Scale Factor|The scale factor value determines the size of an [[object]] when attached to an attach point. A scale factor of 1 will keep the model's original size, whereas a value of 2 will double the model's size. The default scale factor of 1.05 will enlarge models slightly to help prevent [[https://en.wikipedia.org/wiki/Z-fighting|z-fighting]].|

=====Scripting with Attach Points=====
Once you've set up any necessary attach points for your [[object|objects]] and the models to which they will be attached, you can use the [[Attach Object]] scripting function to trigger an [[object]] to be attached to a target [[entity]] in-game, for example to attach a torch to a wall tile when the player interacts with it.

The example below will attach the "sword" [[object]] model's "handle" attach point to the player's "right_hand" attach point.
<code bauxite>
attach_object("sword", player, "handle", "right_hand");
</code>

Alternately, you can create attach points for the sword [[object]] and player [[character]] using the same ID (e.g. "hand") and leave out the function's fourth parameter.
<code bauxite>
attach_object("sword", player, "hand");
</code>

To detach a previously attached [[object]], you can use the [[Detach Object]] scripting function, for example to remove a book from a table when the player interacts with the table.

The example below will detach the [[object]] currently attached to the player's "right_hand" attach point.
<code bauxite>
detach_object(player, "right_hand");
</code>

You can reference the [[object]] that's currently attached to an attach point using the "attachment" property with the desired attach point ID. In the example below, the "glow" [[animation]] will be played for the [[object]] attached to the player's "right_hand" attach point.
<code bauxite>
play_animation(player.attachment["right_hand"], "glow");
</code>

=====Equipment=====
Although most of the equipment system is yet to be implemented, there is some experimental functionality that can be used to automatically attach models to a character whenever an item is equipped. The steps below can be followed to create an equippable item with a corresponding [[object]] model.

1) Toggle the "Equippable" setting to "On" for the [[item]] in the [[Item Editor]].

2) Assign an [[object]] model to the [[item]] in the [[Item Editor]].

3) Create an attach point for both the [[character]] and [[object]] that matches the equipment slot ID (e.g. "right_hand").

4) Call the [[Equip Item]] scripting function to equip the [[item]] to the appropriate slot (e.g. "right_hand") and the [[object]] will automatically be attached to the corresponding attach point.

<code bauxite>
equip_item(player, "right_hand", "ITEM_0001");
</code>

With this setup, calling the [[Unequip Item]] scripting function will automatically detach the [[object]] model associated with the [[item]] that is unequipped.

<code bauxite>
unequip_item(player, "right_hand");
</code>

~~NOTOC~~