Non-player characters (npc.* kits) #

People that walk, see, hear and react, as data: the base kit, the ambient crowd of a city, and the conversations. Readable offline: gripforge docs npcs, or the MCP tool gripforge_docs (topic npcs).

What it is for #

Enemies are NPCs with health and attacks: see the Enemies guide.

Turn it on #

gripforge_gamekit_install   { project_id: "gkp_…", id: "npc.core" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "npc.core", config: { "maxNpcs": 48 } }
gripforge_gamekit_install   { project_id: "gkp_…", id: "npc.pedestrian" }

npc.core requires world.ground, spawn.entities, physics.port and game.engine; npc.pedestrian requires npc.core and a road network (world.roads, from the district kit). When the game has ai.navigation, NPCs follow collision-derived routes (closed or moving colliders invalidate them; an unreachable goal stops the NPC instead of cutting straight through walls).

The NPC document #

{ "schema": "gripforge.npc/1", "id": "guard", "faction": "town",
  "locomotion": { "type": "walk", "speed": 1.6, "runSpeed": 4 },
  "perception": { "sight": { "range": 18, "fov": 110 }, "hearing": 4, "memory": 8 },
  "behavior": { "initial": "patrol", "behaviors": ["patrol", "idle", "investigate", "flee"],
                "params": { "patrol": { "route": [[0,0,0],[10,0,0]], "wait": 2, "loop": true } } },
  "assets": { "model": "guard" },
  "spawn": { "zones": ["gate"], "count": 2 } }

assets.model names a model slot of the project; spawn.zones name zones of world.zones. locomotion.type is walk, static (it does not move) or fly; fly makes an NPC move freely in the air (it keeps the altitude it is sent to and never goes below the ground). A behaviour is registered by name: another kit adds its own (chase, hunt, ship_attack...), and the document lists which ones the NPC may use and which one it starts in. Placing: an archetype of kind npc with the component npc { doc }, or a spawn block in the documents of a scene (spawned on entering the scene, removed on leaving).

Settings and defaults #

Services, events, variables #

• npc.locomotion: moveTo, stop, path following (a flying NPC keeps its altitude). npc.perception: canSee(entity, target), heard(entity), lastKnown(entity). npc.behavior: register a behaviour, spawn, switch.
• pedestrian.ai: pedestrians(), count(), setDensity(n).
• Events: npc.spawned, npc.state ({ entity, npc, from, to, target }), npc.despawned (reason despawn, died or removed), and from pedestrians npc.hit ({ npc, entity, by, speed, direction, lethal, blood }), which a wanted-level kit counts as heat.
• Condition npc_state { npc, state }, verb npc_state.
• Slot pedestrian (a rigged character, several allowed); a capsule is drawn until a model is bound.

Hooks and modding #

{ "id": "brave_guards", "hook": "npc.switch", "match": { "faction": "town", "to": "flee" }, "set": { "to": "investigate" } }

Moddable: tickHz, maxNpcs, the pedestrian settings (bloodEffects aside), and the collection npcs (add, patch or remove documents).

Engines #

The brains, perception and the built-in behaviours are the same Rust logic on the web and in the native player, and are also delivered to Godot and Unity as files and to Unreal through the shared kit library. The local population of the pedestrians and the blood effects are web options; the native adapters keep the world-wide crowd. The hooks run on the web and in the Rust player.

When it does not do what you expect #