Skip to content

Courage.Actors#

require("Courage.Actors") exposes functions to spawn actors (dynamic game objects like enemies, NPCs, and items) in the game world.

Loading the module#

local Actors = require("Courage.Actors")

import * as Actors from "Courage.Actors"

API#

Actors.spawn(name, x, y, z, angleY?, room?, params?) (returns integer or nil)#

Spawns an actor in the world by its process name. Returns the spawned actor's runtime ID on success, or nil on failure.

Parameter Type Description
name string The process name of the actor to spawn (such as "E_DF")
x, y, z number World coordinates where the actor should spawn
angleY integer? Yaw rotation angle in degrees. Defaults to 0
room integer? Room ID to spawn the actor in. Defaults to -1 (current room)
params number? Initialization parameter bitmask. Defaults to 0 
local Actors = require("Courage.Actors")
local id = Actors.spawn("E_DF", 1200.0, 500.0, -3000.0, 90, -1, 0)
if id then
    print("Spawned actor with ID: " .. tostring(id))
end

import * as Actors from "Courage.Actors"
const id = Actors.spawn("E_DF", 1200.0, 500.0, -3000.0, 90, -1, 0)
if (id !== undefined) {
    console.log(`Spawned actor with ID: ${id}`)
}

Actors.spawn_id(procId, x, y, z, angleY?, room?, params?, argument?) (returns integer or nil)#

Spawns an actor in the world by its numeric process ID. Returns the spawned actor's runtime ID on success, or nil on failure.

Parameter Type Description
procId integer The numeric process ID of the actor to spawn
x, y, z number World coordinates where the actor should spawn
angleY integer? Yaw rotation angle in degrees. Defaults to 0
room integer? Room ID to spawn the actor in. Defaults to -1 (current room)
params number? Initialization parameter bitmask. Defaults to 0
argument integer? Optional spawn argument. Defaults to -1 
local Actors = require("Courage.Actors")
local id = Actors.spawn_id(23, 1200.0, 500.0, -3000.0)

import * as Actors from "Courage.Actors"
const id = Actors.spawn_id(23, 1200.0, 500.0, -3000.0)

Joint inspection API#

Actors.joint_count(actor) (returns integer)#

Returns the number of joints in an actor's J3D model skeleton. actor is a raw actor pointer (lightuserdata or NativePtr). Returns 0 if actor is invalid or has no model.

Actors.joint_index(actor, name) (returns integer)#

Looks up the 0-based joint index by bone/joint name string. actor is a raw actor pointer. Returns -1 if not found.

Actors.joint_pos(actor, jointIndex) (returns x, y, z or nil)#

Returns the world-space coordinates (x, y, z) of jointIndex on actor's skeleton, or nil on failure. actor is a raw actor pointer.

Actors.joint_name(actor, jointIndex) (returns string or nil)#

Returns the name string of jointIndex, or nil if jointIndex is out of range. actor is a raw actor pointer.

local Actors = require("Courage.Actors")

Hook["daAlink_c::execute"]:before(function(ctx)
    local link = ctx.self
    local headIdx = Actors.joint_index(link, "head")
    if headIdx >= 0 then
        local x, y, z = Actors.joint_pos(link, headIdx)
        -- x, y, z are world coordinates of head joint
    end
end)

import * as Actors from "Courage.Actors"
import * as Hook   from "Augment.Hook"

Hook.daAlink_c_execute.before((ctx) => {
    const link = ctx.self
    const headIdx = Actors.joint_index(link, "head")
    if (headIdx >= 0) {
        const [x, y, z] = Actors.joint_pos(link, headIdx)
        // x, y, z are world coordinates of head joint
    }
})