Attachment modding

This guide explains how to create new attachments for horses using the HorseMod attachment API.

The attachments API functions for modders are defined in a module HorseMod.api.AttachmentsAPI which provides functions to add new slots and attachments, as well as tables to store the defined slots and attachments. You can find their full documentation there.

Hint

If you want more in-depth information of how the attachment system works internally, please refer to Attachments system description.

Important

A full example mod showcasing how to create new attachments for the horse is available in the PZ-HorseTeam GitHub repositories here.

Creating a new slot

Slots require the use of HorseMod.SlotDefinition to associated a slot name to a model attachment point on the horse model. You can also use multiple times the same attachment point if needed. Alternatively, extra properties can be set to have the attachment be a mane attachment.

To add a new slot, add a new HorseMod.SlotDefinition entry to the HorseMod.attachments.AttachmentData.slotsDefinitions table. Below is an example of adding a new slot called “Hat” attached to the “head” model attachment point on the horse model:

local AttachmentsAPI = require("HorseMod/api/AttachmentsAPI")

AttachmentsAPI.addNewSlot("Hat", {
    modelAttachment = "head",
})

The slots are first defined in the table HorseMod.attachments.AttachmentData.slotsDefinitions, which is later processed to generate the various tables used by the attachment system. See AttachmentData for more details on that process.

Hint

A full list of available slots in the Horse mod by default can be found in Example.

Important

First verify that the default slots of the HorseMod listed in HorseMod.attachments.AttachmentData.slotsDefinitions don’t already provide what you need before creating a new one to avoid redundancy.

Defining a new attachment point on the horse model

When defining a custom slot, you don’t necessarily need to use an existing model attachment point on the horse model. You can define your own custom attachment points by adding a new attachment point to the horse model via a helper function provided by the HorseMod. This function is HorseMod.attachments.AttachmentData.addNewModelAttachment.

Below is an example of adding a new model attachment point called “leftAttachTestPoint” to the horse model:

local AttachmentsAPI = require("HorseMod/api/AttachmentsAPI")

AttachmentsAPI.addNewModelAttachment("leftAttachTestPoint", {
    bone = "DEF_Spine2",
    offset = {x=0.3, y=0.1528, z=0.041},
    rotate = {x=0.0, y=0.0, z=0.0},
})

Hint

By default, the attachment editor won’t work for the horse due to the lack of a custom AnimSet, so we made a patch (Attachments Editor Patch) but it isn’t perfect.

Warning

You should not modify the horse model script directly via the use of a model script override, as Project Zomboid provides all the tools needed to directly modify, add or remove attachment points on models scripts via Lua.

Defining a new attachment

Defining a whole new attachment depends on the function HorseMod.AttachmentData.addNewAttachments. This function allows you to add new slot and item definitions to an existing item full type or create a new item definition entry.

Below is an example usage:

local AttachmentsAPI = require("HorseMod/api/AttachmentsAPI")
local attachmentDef = {
    unequipBehavior = {
        time = -1,
        anim = {
            ["Left"] = "EquipMyItem_Left",
            ["Right"] = "EquipMyItem_Right",
        },
        shouldHold = true,
    },
    model = "MyMod.MyItemModel", -- has variants with riding state suffixes
}
AttachmentsAPI.addNewAttachment("MyMod.MyItemFullType", "Reins", attachmentDef)

Warning

Attachments should be added from the shared folder so that both the server and client are aware of them.