AttachProp

This module let you de-/attach props to an entity (player). If the player drops the attached props will be deleted.

Example

client.lua

Listen clients from the server.

-- Gets the attach-prop api.
---@type NssLibsAttachPropClientApi
attach_prop_api = exports.nss_libs:getAttachPropClientApi(GetCurrentResourceName())

-- You can clear all attached props before you attach new ones, see the following methods:
attach_prop_api.detachOnlyAllKnown() -- Detaches all known props (attached via this api before, not awaitable).
attach_prop_api.detachOnlyAllScenarioProps() -- Detaches all possible scenario props.
attach_prop_api.detachAll() -- Detaches all props known and possible scenario props.

-- If you want to await the detach process is finished on all affected clients then you can use the following methods:
attach_prop_api.awaitDetachOnlyAllScenarioProps()
attach_prop_api.awaitDetachAll()
-- This is useful if you want to ensure the detach process is finished before you attach the new prop.
-- The timeout is currently 250 milliseconds so if the process is not finished after this time the promise will be rejected.

-- Gather data to create a prop.
local prop_model_name = 'p_axe02x'
local pos = { x = 0.12, y = -0.5, z = -0.3 }
local rot = { x = 62.0, y = 0, z = 180.0 }
local bone_id = 6286 -- See https://github.com/femga/rdr3_discoveries/tree/master/boneNames for available bones (consider male/female!)

-- Create the prop (not visible at this state!)
local prop = attach_prop_api.create(
        prop_model_name,
        pos.x, pos.y, pos.z,
        rot.x, rot.y, rot.z,
        bone_id
)

-- Example to check if the prop is attached.
Citizen.CreateThread(function()

    while true do

        if prop.isAttached() then
            print('Prop is attached!')
        else
            print('Prop is not attached!')
        end

        Citizen.Wait(1000)
    end
end)

-- Attach the prop to the player (visible now!)
prop.attach()

-- Wait for demonstration purpose.
Citizen.Wait(5000)

-- Detach the prop from the player (not visible now!)
prop.detach()

Methods

exports.nss_libs:getAttachPropClientApi(resourceName)

Gets the attach-prop API instance scoped to the calling resource.

Param	Type	Default	Description
resourceName	string	—	The name of the calling resource

Returns NssLibsAttachPropClientApi — The attach-prop client API

---

.detachOnlyAllKnown()

Detaches all known props (attached via this API before). Not awaitable.

---

.detachOnlyAllScenarioProps()

Detaches all possible scenario props. Not awaitable.

---

.detachAll()

Detaches all props — both known and possible scenario props. Not awaitable.

---

.awaitDetachOnlyAllScenarioProps()

Detaches all possible scenario props and awaits completion.

WARNING

The timeout is currently 250 milliseconds. If the process is not finished after this time the promise will be rejected.

---

.awaitDetachAll()

Detaches all props (known and scenario) and awaits completion.

WARNING

The timeout is currently 250 milliseconds. If the process is not finished after this time the promise will be rejected.

---

.create(model, posX, posY, posZ, rotX, rotY, rotZ, boneId)

Creates a prop instance. The prop is not visible until .attach() is called.

Param	Type	Default	Description
model	string	—	The prop model name
posX	number	—	X position offset
posY	number	—	Y position offset
posZ	number	—	Z position offset
rotX	number	—	X rotation
rotY	number	—	Y rotation
rotZ	number	—	Z rotation
boneId	number	—	The bone ID to attach to

Returns PropInstance — The created prop instance

---

.isAttached()

Checks whether the prop is currently attached to the player.

Returns boolean — true if attached

---

.attach()

Attaches the prop to the player, making it visible.

---

.detach()

Detaches the prop from the player, making it invisible.

---

Things to know

INFO

• If a resource stops the owned props will be deleted automatically.
• If the nss_libs stops all props created with this module will be deleted automatically.
• If the player drops the props will be deleted automatically (on all clients). The client that controls a prop deletes it.
• If the player dies the previously attached props will be deleted automatically (on all clients).
• .attach() loads the model itself (up to 2 seconds). An invalid model or one that does not load gives no prop and an error line in the console, .isAttached() stays false.
• A prop removed elsewhere (death, detachAll()) no longer counts as attached, the next .attach() creates a new one.
• The server only accepts network ids of objects with the given model that are owned by the sending player, and checks them again before a drop cleanup, since network ids get reused.
• Scenario props of other players are only removed as local, non networked copies, and only for the models in NssLibsAttachPropShare.AttachableScenarioProps.