Runtime control

Any resource can take over selected AI domains of any active NPC (static, ambient, or a bound external one). HumaLike stops acting in those domains until the lease ends. The NPC’s definition and entity are untouched. All exports on this page return one result table: { apiVersion = 1, ok = true, value = ... } or { apiVersion = 1, ok = false, error = code }. They must be called from a resource other than humalike, or they fail with external_resource_required.

Acquire a lease

local result = exports.humalike:AcquireNpcControl(npcId, {
    domains = { 'movement', 'animation' },
    ttlMs = 30000,
    reason = 'hostage_scenario',
})
if not result.ok then return print(result.error) end
local lease = result.value  -- { id, npcId, kind, ownerResource, domains, reason, expiresInMs }

exports.humalike:RenewNpcControl(lease.id, 30000)
exports.humalike:ReleaseNpcControl(lease.id)

Option	Description
`domains`	1 to 4 of `movement`, `animation`, `speech`, `perception`, or `all` alone.
`ttlMs`	1,000 to 300,000. Default 30,000.
`reason`	Optional string up to 128 characters, returned in the lease.

Domain	Effect while held
`movement`	Movement actions are refused and HumaLike stops pacing the ped.
`animation`	Animation actions are refused and the current pose is forgotten.
`speech`	The NPC does not speak. Voice targeting and labels show it as unavailable.
`perception`	The NPC does not hear players and player events are not delivered to it. Server observations are still filed.
`all`	All of the above. `aiEnabled` reports `false`.

Acquiring a lease cancels the NPC’s in-progress action in that domain. A request that overlaps a held domain is refused as a whole.

Error	Meaning
`npc_not_active`	The NPC has no live entity.
`invalid_domains`, `invalid_domain`, `all_domain_must_be_exclusive`	Bad `domains` list.
`invalid_ttl`, `invalid_reason`, `invalid_options`	Argument shape.
`domain_conflict`	A requested domain is already leased.
`lease_not_found`, `not_owner`	Renew or release of an unknown or foreign lease.

A lease ends at its TTL, when its owner resource stops, when the NPC’s entity disappears, or when an ambient NPC is re-assigned to another body.

Runtime state

local state = exports.humalike:GetNpcRuntimeState(npcId).value
local rows = exports.humalike:ListNpcRuntimeStates().value

Field	Description
`kind`	`static`, `ambient` or `external`.
`active`	Whether a live entity exists.
`entity`, `networkId`, `routingBucket`, `modelHash`	Current entity. `entity` is a server handle; use `networkId` across boundaries.
`aiEnabled`	`false` while every domain is leased.
`controlledDomains`	Map of domain to `{ leaseId, ownerResource, expiresInMs }`.
`entityOwner`	`humalike`, `external` or `despawned`.
`bindingId`, `despawnId`, `entityOwnerResource`	Present when a resource owns the entity or the despawn.

ListNpcRuntimeStates returns every roster NPC, including unbound external ones, plus current ambient bodies, sorted by npcId, each with name and model. GetNpcRuntimeState fails with npc_not_found for an id not on the roster.

Get started

Configure

Integrate

Operate

Acquire a lease

Runtime state

Next

​Acquire a lease

​Runtime state

​Next

Acquire a lease

Runtime state

Next