Story Events and Triggers

Story events are the basic units used to organize game story scripts. Triggers find and call events at the right timing. Commands inside an event enter the story event queue and run in order.

Script Symbols

Use English half-width symbols for special script syntax, such as *, #, :, ;, |, [, ], and $. Avoid treating these symbols as ordinary text inside story text or config tables.

Story Events

A story event mainly consists of an event ID, command content, and results.

Part	Description
Story Event ID	The unique identifier for a story event, used by triggers or commands such as EVENT and SUB_EVENT.
Command Content	Command entries executed after the event is triggered. Multi-line commands enter the execution queue in order.
Results	Conditions evaluated from command return values, used to jump to another event or end the current event.

Trigger Execution

Triggers connect game timings such as interactions, map entry, quest completion, and battle results to story events. When a trigger is hit, it does not immediately interrupt every flow. Instead, it places the corresponding event into the story event queue, then the event executor processes queued events in sequence.

Interface Type	Trigger Timing	Object Parameter
passive	Passive trigger, commonly used by map editor triggers or direct execution through the TRIGGER command.
talk	Triggered when interacting with an NPC.
first_in	Triggered the first time the game is entered.
encounter	Triggered when interacting with a unit on the sandbox map.	Target unit control ID
before_enter_map	Triggered before entering the target map. If an event responds, the current map-entry action is interrupted.	Target map ID
enter_map	Triggered when entering a map.	Target map ID
before_leave_map	Triggered before leaving the current map. If an event responds, the current map-leave action is interrupted.	Current map ID
leave_map	Triggered when leaving the current map.	Current map ID
enter_place	Triggered when entering a place.	Target place ID
reach_place	Triggered before entering a place on the world map. If an event responds, place entry is interrupted.	Target place ID
leave_place	Triggered when leaving a place.	Current place ID
before_leave_place	Triggered before leaving a place. If an event responds, place leaving is interrupted.	Current place ID
reach_building	Triggered before entering a facility. If an event responds, facility entry is interrupted.	Target facility ID
set_lord	Triggered when AI appoints or removes the player as a city lord.	Trigger type and object ID
job_cmd	Triggered when a work command is issued to the player.
see_warband	Triggered when encountering a battle between other teams on the world map.
curplace_inwar	Triggered when the place where the player is located is attacked.
quest_done	Triggered when all quest conditions are completed but the quest has not been turned in.	Quest ID
on_end_work	Triggered when ending work at a place.
occupy_place	Triggered when the player successfully occupies a place.	Target place ID
new_day	Triggered when a new day begins.	Target day count
reward_follower	Triggered when rewarding the player's followers.
reward_player	Triggered when the player receives a reward.
dip_event	Triggered when the player faction encounters a diplomacy event.	Diplomacy event type and opposing faction ID
dip_ret_success	Triggered when a diplomacy action requested by the player faction succeeds.	Diplomacy event type and opposing faction ID
dip_ret_fail	Triggered when a diplomacy action requested by the player faction fails.	Diplomacy event type and opposing faction ID
player_failed	Triggered when the player loses an encounter battle.
reinforce_request	Triggered by reinforcement events related to the player.
is_fall	Triggered when a faction collapses.	Faction ID
is_to_fall	Triggered when a faction loses all strongholds and is about to collapse.	Faction ID
before_cash_present	Triggered before a commendation reward, and can be used to interrupt the commendation.
before_present	Triggered before giving a gift, and can be used to interrupt gift giving.
on_present	Triggered when giving a gift.
encounter_role	Triggered after encountering a role and before entering common dialogue.	Target role ID
helped_camp	Triggered after helping one side in a battle between two encountered sides.	Faction of the opposing team's leader
on_saodang	Triggered after sweeping an outdoor place.
on_place_rep_up	Triggered when place contribution increases. The latest contribution can be read from arg_int_val1.
on_place_rep_down	Triggered when place contribution decreases. The latest contribution can be read from arg_int_val1.
team_dismiss	Triggered when a team disbands.	Team type
team_into_place	Triggered when a team enters a place.	Team type and place ID
in_game	Triggered after creating or loading a game.
bar_challenge	Triggered when the player starts a tavern challenge.
tournament_start	Triggered when the player joins a local fighting tournament.
be_promoted	Triggered when the player's title rank rises. tagrole is the faction lord.
be_demoted	Triggered when the player's title rank drops. tagrole is the faction lord.
space_move	Triggered when the player switches areas inside a city.	enter or leave; area ID
on_diplomacy_strategy	Triggered when pressing the diplomacy button in the intelligence screen. tagcamp is the target faction.
on_diplomacy_quit	Triggered when pressing the exit button in the intelligence screen. tagcamp is the target faction.
after_generate_role	Triggered after a role is generated. tagrole is the generated role.	Generation template ID
match_prepare	Triggered when a tournament starts preparing.	Tournament ID
match_start	Triggered when a tournament officially starts.	Tournament ID
match_end	Triggered when a tournament ends.	End type and tournament ID
match_fight	Triggered when a tournament battle starts.	Tournament ID
match_watch_fight	Triggered when watching a tournament battle.	Tournament ID
match_fast_fight	Triggered for a quick tournament battle.	Tournament ID
match_join_team	Triggered when joining a tournament team. arg_int_val1 is the team ID being applied to.	Tournament ID
match_end_talk	Triggered for tournament end dialogue.	Result type and dialogue role

Script Preset Fields

Preset fields can stand in for objects in the current context, making reusable shared events easier to write.

Field	Description
CUR_ROLE	The current encounter role template ID. Commonly used in dialogue and selection boxes.
CUR_BATTLE	The battle ID corresponding to the current encounter’s world-map spawned unit.

Battle Parameter Info

The restriction field of a specific battle table, as well as battle parameters for commands such as BATTLE, can override the original battle settings.

param1ID:param1;param2ID:param2;...

Parameter	Description
player	Overrides player-side hero units. Format: RoleID|RoleID2, for example 主角|曲玉.
units	Overrides player-side squads. Format: CardID,count,level|CardID2,count,level. If level is omitted, the card’s initial level is used.
add_stat	Adds attributes to initial deployment roles. Format: RoleIDOrCardID=StatFieldID,fieldValue|StatFieldID2,fieldValue2.
place_stat	Adds attribute fields to the battle place. Format: StatFieldID,fieldValue|StatFieldID2,fieldValue2.
can_capture	Whether the losing side can be captured in this battle. 1 means yes, 0 means no.
can_loot_equip	Whether enemy equipment can drop in this battle. 1 means yes, 0 means no.

Result Script Format

Result scripts route events to different follow-up commands based on conditions. The game checks from the first line and executes the command for the first matching condition.

conditionExpressionGroup1:command1
conditionExpressionGroup2:command2
...
conditionExpressionGroupN:commandN

Global Save Queries

Form	Description
[%global_int:ID%]	Returns the value of global integer field ID.
[$global_str:ID$]	Returns the value of global string field ID.

Built-in Global Variables

Field	Description
save_max_hard_level	The highest difficulty ever unlocked. Default value: 0.

Built-in Custom Variables

Field	Description
system_沙盒模式	Marks whether the current mode is sandbox mode.
system_探索地图点数	Stores exploration map points.
system_星星	Stores the star count.
system_敌方角色血量百分比	Extra multiplier for the opponent’s HP when the player fights an enemy role.
system_敌方角色攻击百分比	Extra multiplier for the opponent’s attack and magic attack when the player fights an enemy role.
config_ai_level	Current AI strength level: 0 easy, 1 normal, 2 hard.
config_roll_limit	Whether combat roll limits are enabled. 0 off, 1 on.
config_hunger_penalty	Whether hunger penalties are enabled. 0 off, 1 on.
config_upgrade_cost_reduce	Current discount percentage for unit upgrade EXP and material costs.
config_soldier_dead_scale	Current death chance multiplier for common soldiers, as a percentage.

Initial Setting Fields

Initial setting fields are usually used for character creation, starting maps, default time speed, default battle formulas, and other base configuration.

Field	Description
init_pos	Default spawn position info.
init_statu	Default attribute state info when the player spawns.
init_money	Default starting assets.
home_place	Default starting place ID.
init_skillpages	Skill pages lit at the start.
init_skills	Skills initially owned by the main character.
init_equip	Initial equipment table info for the main character.
init_camp_rl	Initial faction relationship table. Format: FactionA,FactionB,RelationState,Favor|...
gametime_scale	Scale coefficient for game time on the world map.
battletime_scale	Scale coefficient for game time in battle. When 0, game time is frozen in encounters or siege battles.
custom_intval_watcher	Default custom variable watcher field, using the same format as ADD_INTVAL_WATCHER.
def_dropitem_model	Default model and effect info for dropped items on the ground in battle.
default_role_model_male / default_role_model_female	Default male and female role models used when no role model is specified.
default_role_act_male / default_role_act_female	Default male and female action IDs used when an action cannot be mapped from weapon type.
default_weapons_speed	Default attack speed for all weapon types.
def_formula_phy_x / def_formula_mag_x	Formula factors for physical defense and shamanic defense.