SgAgent

A Crowd locomotion body for NPCs and other AI characters. Links to an SgNavMesh with Enable Crowd, optionally drives a mesh with idle / walk / run clips, and interprets a flat Active goal (None / Idle / GoTo / Patrol / Wander / Follow).

Unlike SgPlayer (Bullet KCC + input), agents stay on the Recast Crowd.

Inherits from

SceneObject

Setup

1. Add an SgNavMesh, enable Crowd, and bake.
2. Add an SgAgent, assign Nav mesh, optionally Mesh and locomotion clips.
3. Tune capsule Radius / Height using the editor helper (same feet-origin capsule as SgPlayer), then set Active goal.
4. Press Play — the agent registers with the Crowd and follows the active goal.

For Patrol, add ordered Patrol waypoints (world points or scene nodes) in the Inspector before play; setGoal(Patrol) only starts that authored list (optional loop). See Navigation and AI.

In the editor a capsule wireframe (and forward arrow) shows the crowd agent volume so you can match it to the character mesh. Helpers are hidden during play.

Game events

On a Behaviour attached to the agent (or via node:on):

• goalReached — GoTo arrived, or Patrol finished without loop
• waypointReached — Patrol / Wander reached the current waypoint

Full guide: Node Game Events.

local SgAgent = require 'engine/sceneobjects/sgagent'

function NpcScript:init()
    self.node:on("goalReached", function(ev)
        print("arrived", ev.data.goalType)
    end)
end

function NpcScript:update(dt)
    -- runtime goal change
    -- self.node:setGoal(SgAgent.GoalType.GoTo, { point = Vector3.new(10, 0, 0) })
end

create

static create(self, options, parent)

Create a new Crowd agent in the scenegraph.

Parameters

• self
• options (table): A table of options to fill the parameters
• parent (SceneObject): The parent scene object to add this to

Returns

• Promise: promise which will resolve to the created object

Example

SgAgent.create({
    name = "NPC",
    navMesh = navMeshNode,
    mesh = meshNode,
    activeGoalType = SgAgent.GoalType.Idle,
    walkSpeed = 3.5,
    runSpeed = 6,
})

Properties

You can access these properties directly on the object (preferred), for example obj.active = true or local v = obj.active. The :get("propertyName") / :set("propertyName", value) methods also work, but prefer direct property access in examples and scripts.

setAutoGoal

setAutoGoal(enabled)

Enable or disable automatic ActiveGoalType interpretation.

Parameters

• enabled (boolean)

isAutoGoal

isAutoGoal()

Return whether automatic goal interpretation is enabled.

Returns

• boolean

setGoal

setGoal(goalType, options)

Set the active goal type and optional parameters.

Parameters

• goalType (string): one of SgAgent.GoalType
• options (table|nil): optional fields: urgency, point, node, target, stopDistance, radius, center, loop, arrivalDistance

setDestination

setDestination(x, y, z)

Request a Crowd move to a world-space position (does not change ActiveGoalType).

Parameters

• x (number)
• y (number)
• z (number)

stopMoving

stopMoving()

Stop the current Crowd move target.

getHorizontalSpeed

getHorizontalSpeed()

Return horizontal movement speed (XZ).

Returns

• number

getVelocity

getVelocity()

Return the last known Crowd velocity.

Returns

• table: with x, y, z

getAgentInfo

getAgentInfo()

Return Crowd agent info (position, velocity, target, …) or nil.

Returns

• table|nil

warp

warp(x, y, z)

Teleport the agent to a world-space position.

Parameters

• x (number)
• y (number)
• z (number)

Enum: GoalType

Active locomotion goal types.

Enum: Urgency

Urgency / speed profile for moving goals.

Further reading

• SgNavMesh
• SgObstacle
• SgPlayer
• Navigation and AI