Character Behaviour

Character Behaviour

Character behaviour lets a character world-item act as a follower, melee enemy, shooter, idle character, or patrol character. Use it for NPC companions, enemies, guards, objective characters, and simple AI-driven movement.

Behaviours are stored on the character item as worldItem.characterBehavior. The container has an enable toggle and a behaviors list, so one character can be configured with multiple behaviours.

Enabling Behaviours

1. Select a character world-item in the editor.
2. Open the item settings for that character.
3. Enable Character Behaviour.
4. Add one or more behaviour entries.
5. Choose a Behaviour Type: follow, attack, shoot, idle, or patrol.
6. Assign activation events, navigation, weapon, or patrol options as needed.

Behaviour Data

Each behaviour can define activation events, a behaviour type, optional navigation, and type-specific settings.

• activateEvent - world event name that starts this behaviour.
• deactivateEvent - world event name reserved for stopping this behaviour.
• behaviorType - follow, attack, shoot, idle, or patrol.
• navmeshItemId - optional navmesh world-item used for pathfinding.

Follow

Follow makes the character walk or run toward the player and stop at a follow distance of 2 units. When a navmesh is assigned, the path is recalculated about every 2 seconds.

• Use for: companions, guides, escort characters, or helper NPCs.
• Options: activateEvent, deactivateEvent, navmeshItemId, and runWhileChasing.
• Tip: assign a navmesh in complex environments so the character can route around obstacles.

Attack

Attack makes the character chase the player up to 120 units. When the character is within 1 unit, it plays a melee attack animation and applies damage after the configured impact delay.

• Use for: melee enemies, guards, creatures, or close-range hazards.
• Options: runWhileChasing, attackImpactDelay, activateEvent, deactivateEvent, and navmeshItemId.
• Default: runWhileChasing is true. Runtime default attackImpactDelay is 0.26 seconds.
• Tip: match attackImpactDelay to the visible hit moment in the melee animation.

Shoot

Shoot makes the character chase the player, stop within 8 units, and fire an equipped weapon. A weapon world-item must be assigned.

• Use for: ranged enemies, sentries, turrets with character models, or boss phases.
• Options: weaponItemId, difficulty, aimReactionDelay, runWhileChasing, activateEvent, deactivateEvent, and navmeshItemId.
• Default: runtime aimReactionDelay is 0.22 seconds and shootCooldown is 0.4 seconds.
• Tip: confirm the assigned weapon item is configured before testing shoot behaviour.

Shoot Difficulty

• Easy - 0.8x damage, 1.35x cooldown, 0.75x accuracy.
• Medium - baseline damage, cooldown, and accuracy.
• Hard - 1.3x damage, 0.75x cooldown, 1.18x accuracy.

Idle

Idle makes the character stand still and do nothing. Use this as a resting state, a disabled state, or a behaviour to return to after another action.

• Use for: neutral NPCs, waiting guards, staged enemies, or event-controlled characters.
• Options: activateEvent and deactivateEvent.
• Tip: use idle as the default behaviour before an event activates follow, attack, shoot, or patrol.

Patrol

Patrol moves the character through user-defined patrol points in order. It can loop, run, and pause at each point.

• Use for: guards, roaming enemies, route-based NPCs, and background character movement.
• Options: patrolPoints, loop, useRun, waitAtPoint, activateEvent, deactivateEvent, and navmeshItemId.
• Defaults: loop is true, useRun is false, and waitAtPoint is 0 seconds.

Patrol Setup

1. Add a patrol behaviour to the character.
2. Add patrol points in the order the character should visit them.
3. Name each point clearly, such as Gate, Hallway, or Exit.
4. Position each point in the world.
5. Enable loop if the patrol should repeat.
6. Enable useRun if the character should run between points.
7. Set waitAtPoint if the character should pause at each point.
8. Assign a navmesh when the route must go around walls, props, or terrain.

Event-Driven Activation

Each behaviour can be connected to world events using activateEvent and deactivateEvent. This lets other objects, triggers, logic, or scripts control when NPC behaviour starts.

• activateEvent starts the selected behaviour.
• deactivateEvent is part of the data model, but runtime deactivation is currently not implemented.
• At runtime, activation routes to the matching behaviour call: follow, chase, shoot target, patrol, or idle.

Navmesh and Pathfinding

Follow, attack, shoot, and patrol can use an optional navmeshItemId for pathfinding. If no navmesh is assigned, movement is direct.

• Use a navmesh when characters need to move around walls, props, buildings, or uneven routes.
• Direct movement is simpler and can work in open spaces.
• The editor includes a Generate Default Navmesh button.

Multiple Behaviours

A character can have multiple behaviour objects in its behaviors list. Use separate activation events to switch phases, such as idle first, patrol after the level starts, then attack when the player enters a danger area.

Because automatic deactivation is not yet implemented, avoid overlapping activation events unless you are deliberately replacing the current runtime state. Use clear event names so each behaviour phase is easy to test.

Runtime Defaults

• walkSpeed: 1.8 units/sec
• runSpeed: 4.5 units/sec
• followDistance: 2.0 units
• chaseDistance: 120 units
• attackRange: 1 unit
• shootRange: 8 units
• attackImpactDelay: 0.26 sec
• shootCooldown: 0.4 sec
• aimReactionDelay: 0.22 sec
• rotationSpeed: 10 rad/sec

Runtime States

Character behaviour can move through these runtime states: idle, move, follow, chase, attack, shoot, patrol, and dead.

Animations

The behaviour system expects common character animations and uses them when available.

• Idle, Walk, Run, Jump_forward, Dying, and Right_Hook for melee attack.
• Shoot uses the character's weapon firing state.
• If an expected animation is missing, the behaviour can still run, but visual feedback may look static or incomplete.

Damage and Callbacks

• onAttackPlayer(pos, damage) applies melee damage through hitPlayer(damage).
• onShootPlayer(pos, damage) applies ranged damage through hitPlayer(damage).
• onDead() calls character.die().

Known Limitations

• deactivateEvent exists in the behaviour data model, but deactivateCharacterBehavior is currently a runtime stub.
• Behaviour deactivation must be handled manually by activating another behaviour, such as idle, or by custom logic/script.
• Shoot behaviour requires a valid assigned weapon world-item.
• Pathfinding quality depends on the assigned navmesh. Without a navmesh, movement is direct.