-
Notifications
You must be signed in to change notification settings - Fork 111
event_type
Jan Boon edited this page Mar 13, 2026
·
1 revision
title: NPC Event Types description: Reference of events that trigger NPC event handler actions published: true date: 2026-03-14T00:00:00.000Z tags: editor: markdown dateCreated: 2026-03-14T00:00:00.000Z
NPC event handlers respond to events that occur during gameplay. When an event fires on a group, all event handlers matching that event name execute their configured action. Events can also trigger AI script code blocks.
Events are registered in the AI service source code. The base events (defined in event_reaction_container.h) are available for all group types. Additional events are registered by specific manager types (NPC, fauna, outpost, spire).
These events relate to the group's behavioural state flow.
| Event | Description |
|---|---|
| start_of_state | Triggered at the beginning of a state, just after the state change. Also triggered at the start of the initial state when the group is first initialized. |
| end_of_state | Triggered at the end of a state, just before the new state is set. |
| state_timeout | Triggered when the state timeout timer elapses. This timer is set by the set_state_timeout action. Used to time idle states; may be automatically cleared on state change. |
| punctual_state_timeout | Triggered when the punctual state timeout timer elapses. Set by the set_punctual_state_timeout action. |
Triggered by the four general-purpose timers (T0-T3), set via the set_timer action or the setTimer() AI script function.
| Event | Description |
|---|---|
| timer_t0_triggered | Timer T0 has elapsed |
| timer_t1_triggered | Timer T1 has elapsed |
| timer_t2_triggered | Timer T2 has elapsed |
| timer_t3_triggered | Timer T3 has elapsed |
Generic events triggered programmatically by trigger_event actions or the setEvent() AI script function. Used for custom inter-group communication.
| Event | Description |
|---|---|
| user_event_0 .. user_event_9 | Triggered by the corresponding trigger_event action or setEvent() call. Ten user events (0-9) are available per group state machine. |
| Event | Description |
|---|---|
| group_under_attack | Triggered when a bot in the group enters combat mode AND no other bots in the group are already fighting. This fires once at the start of combat for the group. |
| group_attack_end | Triggered when no bot in the group is fighting anymore (end of combat for the entire group). |
| bot_begin_fight | Triggered each time an individual bot begins to fight. A say action under this event will automatically use the bot that started fighting as the speaker. |
| bot_target_killed | Triggered each time a bot's combat target is killed. A say action under this event will automatically use the bot as the speaker. |
| Event | Description |
|---|---|
| bot_killed | Triggered each time a bot of the group is killed. (NPC and fauna managers only) |
| group_eliminated | Triggered when the last bot of a group is killed. (NPC and fauna managers only) |
| squad_leader_killed | Triggered when the squad leader is killed. (NPC manager only, used for outpost squads) |
| group_despawned | Triggered when the last bot of a group despawns (not necessarily killed - may have timed out or been explicitly despawned). |
| group_spawned | Triggered when the first bot of a group spawns. |
| Event | Description |
|---|---|
| destination_reached | Alias for destination_reached_first. (NPC and fauna managers only)
|
| destination_reached_first | Triggered when the first member of the group reaches its destination. (NPC and fauna managers only) |
| destination_reached_all | Triggered when all members of the group have reached their destinations. (NPC and fauna managers only) |
| Event | Description |
|---|---|
| player_target_npc | Triggered each time a player targets an NPC in the group. |
| player_follow_npc | Triggered each time a player targets to follow an NPC, or changes target while in follow mode. |
| player_arrived_trigger_zone | Triggered when a player enters a trigger zone associated with the group. |
| player_left_trigger_zone | Triggered when a player leaves a trigger zone associated with the group. |
Used for escort missions where players must accompany a group of bots.
| Event | Description |
|---|---|
| escort_away | Triggered when the last player of the escort team leaves the escort range. |
| escort_back | Triggered when the first player of the escort team re-enters the escort range. |
| Event | Description |
|---|---|
| variable_changed | Triggered when any of the group's logic variables is changed. If multiple variables are changed in the same server tick, the event fires once. |
| variable_v0_changed .. variable_v3_changed | Triggered when a specific variable (V0-V3) is changed. |
| Event | Description |
|---|---|
| egs_up | Triggered when the EGS (Entities Game Service) comes online. Useful for re-initializing state that depends on EGS data. |
These events are only valid for groups inside an outpost NPC manager.
| Event | Description |
|---|---|
| outpost_peace_state_begin | The outpost enters peace (default) state |
| outpost_peace_state_end | The outpost leaves peace state |
| outpost_tribe_ownership_begin | The outpost owner changes and the new owner is a tribe |
| outpost_tribe_ownership_end | The outpost owner changes and the old owner was a tribe |
| outpost_guild_ownership_begin | The outpost owner changes and the new owner is a guild |
| outpost_guild_ownership_end | The outpost owner changes and the old owner was a guild |
| outpost_owner_changed | The outpost owner changes (any ownership transition) |
| outpost_attacker_changed | The outpost attacker changes |
| outpost_state_changed | The outpost state changes (any state transition) |
These events are only valid for groups inside a spire manager. They mirror the outpost events.
| Event | Description |
|---|---|
| spire_peace_state_begin | The spire enters peace state |
| spire_peace_state_end | The spire leaves peace state |
| spire_tribe_ownership_begin | New spire owner is a tribe |
| spire_tribe_ownership_end | Old spire owner was a tribe |
| spire_guild_ownership_begin | New spire owner is a guild |
| spire_guild_ownership_end | Old spire owner was a guild |
| spire_owner_changed | The spire owner changes |
| spire_attacker_changed | The spire attacker changes |
| spire_state_changed | The spire state changes |
The following events are defined in the World Editor event type list but are not registered in the current AI service code. They were planned for the team/escort system which was never fully completed.
| Event | Planned Description |
|---|---|
| all_pets_arrived_from_stable | All pets for all group members are present |
| all_pets_gone_to_stable | All pets for all group members have gone into stables |
| all_team_npcs_present | All NPCs in the team have spawned and arrived |
| all_team_players_present | All players in the team have logged on and arrived |
| other_team_enters_view | Another team enters the view range |
| other_team_meets_team | Another team enters the contact range |
| player_request_pause | A player requests that the team mark a pause |
| player_request_pause_end | A player who requested a pause cancels or disconnects |
| route_blocked | The route ahead of the group is blocked |
| route_blocked_end | A previously blocked route becomes unblocked |
| team_attacked | A team member is attacked |
| team_attacked_end | End of hostilities regarding the team |
| team_member_badly_hurt | A team member is badly hurt (movement reduced) |
| team_member_killed | A team member is killed |
| team_member_LD | A player team member loses connection without logging out |
| team_member_logout | A team member logs out explicitly |
| team_pack_animal_hurt | A pack animal belonging to a team member is badly hurt |
| team_pack_animal_killed | A pack animal belonging to a team member is killed |
- NPC Logic Action Types - Actions executed when events fire
- AI Script - Scripting language for event handler code blocks
- AI Script Function Reference - Built-in script functions
- NPC Event Handler Action - How to configure event handlers
Event registrations: ryzom/server/src/ai_service/event_reaction_container.h, ai_mgr_npc.cpp, ai_mgr_fauna.cpp, ai_outpost.cpp, ai_spire.cpp
Event type HTML docs: ryzom/common/data_leveldesign/leveldesign/world_editor_files/npc/event_type/