NPC AI, combat and voice control

Control individual spawned NPCs from server Lua with Open77.npcs. Behavior settings apply to the selected NPC, not its gang, other NPCs using the same record, player characters or global audio.

Available in client and server 2.31.13+op77.55, using protocol 1.24. Both sides must be updated to apply the behavior policy. Find spawn IDs in the NPC record catalogue.

Spawn a passive, silent NPC#

-- Server manifest: permission "world.npcs"
local npc, reason = Open77.npcs.create({
    record = "Character.cpz_maelstrom_grunt1_ranged1_lexington_wa",
    position = { x = 381.0, y = -2400.0, z = 182.0 },
    aiMode = Open77.npcs.ai.tasks,
    behavior = {
        combatEnabled = false,
        voiceEnabled = false,
    },
})
if not npc then print(reason); return end

-- Optional: pause both the native AI agent and Open77 task execution.
local ok, error = Open77.npcs.setAIEnabled(npc, false)
if not ok then print(error) end

-- Resume the selected aiMode, without changing the passive/silent options.
Open77.npcs.setAIEnabled(npc, true)

The record and its assets must exist on each client. A successful create returns a canonical server ID, not proof that the engine has spawned the body. See NPC lifecycle and readiness.

Independent controls#

All four options default to true. Omitting an option preserves its current value when updating.

Each helper requires a boolean, not 0, 1, or "false". Use one atomic update for several options:

local ok, reason = Open77.npcs.setBehavior(npc, {
    aiEnabled = true,
    combatEnabled = false,
    perceptionEnabled = false,
    voiceEnabled = false,
})
local behavior = Open77.npcs.getBehavior(npc)
-- Equivalent read: Open77.npcs.get(npc).behavior

setBehavior and the four setters return true, or false with a validation reason when supplied data is invalid. Unknown/not-owned NPCs and missing permission return false. getBehavior returns a detached table or nil when unavailable. Malformed options return npc_behavior_invalid; unknown option names return npc_behavior_unknown_option.

Open77.npcs.update(id, { behavior = {...} }) accepts the same partial object. Changing the loadout/appearance, changing bucket, or reviving the NPC does not reset these settings. They are not stored in client KVP and do not constitute disk persistence across server restarts.

Two further options govern damage rather than AI: vehicleContactEnabled (default false, below) and hitPricing (default "resource", below). They are set the same way, at creation or later, and read back from getBehavior:

local npc, reason = Open77.npcs.create({
    record = "Character.cpz_maelstrom_grunt1_ranged1_lexington_wa",
    position = { x = 381.0, y = -2400.0, z = 182.0 },
    damagePolicy = Open77.npcs.damage.mortal,
    behavior = { vehicleContactEnabled = true, hitPricing = "platform" },
})
if not npc then print(reason); return end
print(Open77.npcs.getBehavior(npc).hitPricing) --> platform

Vehicle contact damage#

behavior.vehicleContactEnabled defaults to false. The NPC's creating server resource may opt in with Open77.npcs.setBehavior(id, { vehicleContactEnabled = true }). This replaces native vehicle-hit damage pricing with server-priced contact damage, and it keeps the NPC's damage policy (invulnerable, immortal or mortal). The client simulating the NPC reports the contact; the server checks its current lease, world readiness, revision, bucket and the vehicle's recent trajectory, with a two-second contact cooldown per NPC. Damage uses the same speed curve as car impacts on players (the combat.vehicleHitDamage* server options), derived from accepted positions. Nothing scans the world for contacts every frame.

An accepted contact adopts an existing native fall or requests a native NPC knockdown. Identical ragdoll trajectories on every screen are not guaranteed.

Who prices player hits: hitPricing#

An NPC's health and death belong to the server. No client lets the game change a network NPC's health or kill it on its own: a shot plays its hit reaction, and the NPC loses health or dies only when the server's ledger says so, on every client at once.

By default the resource that created an NPC prices player hits on it, typically from the client event open77:npcHit it forwards to its own server script and a weapon table. A resource that prices nothing leaves players unable to kill its NPCs: they react to shots but never lose health.

A resource can instead opt in to the platform's pricing for a mortal NPC (damagePolicy = Open77.npcs.damage.mortal). The shooter's client then sends the engine's own price for each hit, and the server applies it with Open77.npcs.applyDamage semantics. onNpcDamaged and onNpcDied receive the source "player:<id>" and the cause "player_hit".

-- A guard that players may kill, with no hit pricing of your own.
local guard = Open77.npcs.create({
    record = "Character.cpz_maelstrom_grunt1_ranged1_lexington_wa",
    position = { x = 381.0, y = -2400.0, z = 182.0 },
    damagePolicy = Open77.npcs.damage.mortal,
    behavior = { hitPricing = "platform" },
})
-- or later: Open77.npcs.setBehavior(guard, { hitPricing = "platform" })

Resources that create mortal NPCs and do not price open77:npcHit should opt in, or players cannot kill those NPCs. The opt-in exists because the amount is still the shooter's own claim: every report must ride shots the server itself admitted (see below), but the server has no weapon damage table, so a modified client could still claim one maximum per admitted shot. Price hits in your resource when that matters.

The server checks each report before applying it:

• the shooter is alive, has a weapon drawn according to its own recent player snapshot, has a fresh position in the NPC's routing bucket and is within 150 m of it;
• the report names at least one shot (a spent round or a melee swing) that the server admitted for that drawn weapon at the weapon class's fire rate, fired within the last 3 s (1.5 s for a swing) from within 150 m (12 m for melee) of the NPC, and not yet used against this NPC. Each shot prices a given NPC once. The server option combat.handheldDischarges (default true) runs this admission; turning it off turns platform pricing off;
• the NPC is alive, mortal and opted in;
• one report is worth at most the NPC's maximum health;
• a player may apply at most 40 reports and 6 × maximum health per second across all NPCs;
• an NPC may receive at most 24 reports and 2 × maximum health per second from all players.

Immortal and invulnerable NPCs are never priced this way.

The value must be one of these two strings; anything else returns npc_behavior_invalid. Open77.npcs.getBehavior(id).hitPricing reads it back. The bundled Cordon, Deathmatch and Freeroam PvP bots state "resource" explicitly.

Damage no player caused is always reported by the client that simulates the NPC: environment, falls, fire, explosions without a player instigator, and the NPC's own grenade. Vehicle collisions are not player hits; opt in to vehicle contact damage for those.

Server configuration#

Both options live in the combat section of server.jsonc and are read at startup:

"combat": {
  "handheldDischarges": true,     // default: admit handheld shots, required by "platform" pricing
  "handheldVehicleDamage": false  // default: see Armed vehicles & Lua API
}

handheldDischarges (default true) makes the server bind each living body and admit fire declarations against the drawn catalogued weapon and a per-class cadence. A receipt damages nothing by itself; platform-priced NPC hits require one. With false, no binding is sent and platform-priced NPCs cannot be priced from a player's hit. handheldVehicleDamage is described in Armed vehicles & Lua API.

Speech: one line, on demand#

Open77.npcs.speak(id, voice, options) is the ON switch beside setVoiceEnabled's OFF: one voice-over line from the NPC's own voiceset, queued on every client that has the body streamed. It is the counterpart of FiveM's PlayPedAmbientSpeechNative. What is proven is the plumbing — the SoundPlayVo event reaches each viewer's puppet, and a muted NPC refuses — not the sound: the test loop has no audio capture, so whether a given line is heard on a given record is something to check by ear before shipping it.

-- A guard greets whoever walks up, and warns them off when they linger.
local guard = Open77.npcs.create({ record = "Character.Judy", position = gate })
AddEventHandler("onNpcInteracted", function(npcId, playerId)
    if npcId ~= guard then return end
    local ok, reason = Open77.npcs.speak(guard, "greeting")
    if not ok then print("guard stayed silent: " .. reason) end
end)
Open77.npcs.speak(guard, "rep_ask_to_leave", { ignoreDistance = true })

voice is a voContext name — the same word vanilla passes to GameObject.PlayVoiceOver, resolved by the engine against the puppet's voiceset (Character.*.voiceTag) — not a Wwise event; Open77.effects.sound remains the way to play a sound bank event on an NPC. Open77.npcs.voices() lists the generic barks that can be pointed at in the game's own 2.31 sources, each with the file and line that plays it:

The list is documentation, not an allowlist: any identifier is accepted (letters, digits, underscore, at most 64), because a record may carry lines no vanilla script calls. A name the voiceset does not have is silent, and nothing can report that — the engine drops it without a word, so true means "queued on every viewer", not "heard". Test the names you ship on the records you ship; a character whose record has no voiceTag never speaks.

Options: ignoreFrustum (default true) plays even when the NPC is off-screen; ignoreDistance (default false) skips the engine's distance cull. Refusals, by name:

Requires world.npcs and ownership, like every NPC mutator. The line rides the existing effect one-shot to every client in the NPC's routing bucket; a client that does not have the body streamed resolves no target and drops it, which is the same rule an entity-bound sound follows. On the client the bundled open77_effects resource queues the engine's own SoundPlayVo event on the puppet through Open77.sfx.playVoice, which a client resource may also use for a purely local bark (see Effects).

Tasks, authority and replication#

aiMode and behavior are different controls. frozen suspends Open77's task scheduler; use setAIEnabled(id, false) when the native agent must also stop. Re-enabling AI does not change aiMode: a frozen task scheduler stays frozen until its mode is changed. Tasks resume with renewed timing rather than expiring because of the paused interval.

The server validates resource ownership and replicates the full policy in reliable NPC state, including to late joiners, observers and newly streamed incarnations. Engine mutations run on the game thread. An unavailable native/component is logged as behavior pending, not reported as a successful application. Applying these options requires the matching updated client and server; the existing 1.24 wire layout is unchanged, but older clients ignore the new policy.

Clients with npcs.read can inspect Open77.npcs.get(id).behavior and .all(), but cannot override the server policy. Custom network event handlers must validate ownership themselves; never forward an arbitrary client-supplied NPC ID to these setters.

If your gamemode accepts NPC hit reports, re-check current canonical behavior before applying damage: ignore reports when aiEnabled or combatEnabled is false. A delayed report is not permission to damage a player after a server-side policy change.

Boundaries#

• These APIs control Open77-created NPCs, not arbitrary ambient world handles.
• Voice suppression is prospective. It does not promise to interrupt every line already playing, or audio emitted outside the game's voice/dialogue pipelines.
• Disabling AI is not time dilation, a pose freeze, ragdoll, invulnerability or hiding a character. Use the dedicated animation and damage APIs for those effects.
• Perception off does not override explicit script commands. Combat off does not prevent your own Lua code from deliberately calling a damage API or playing a custom attack animation.
• Vehicle auto-driving belongs to Open77.vehicles.ai; disabling a seated NPC's agent is not a substitute for stopping the vehicle's drive command.