Battle Script Notes

Battle scripts organize story events, skill effects, damage resolution, and attached unit scripts during battle. Battle story commands, battle queries, and skill commands each have their own index; this page covers shared rules and formats.

Event Execution in Battle

Battle uses a separate story event execution system. It is similar to the world-map story event executor, but executing an event does not force combat to pause. Use battle story commands such as PAUSE and RESUME inside the event when you need to pause or resume combat.

When the console is open during battle, you can debug battle script commands by entering bs@ followed by the command content.

bs@KILL_ALL*1

Role Attribute Field Trigger Modes

Some role attribute fields are not just numeric values; they can also trigger commands in battle. The trigger mode controls when the field is checked, how condition parameters are filled, and which kinds of objects the command affects.

Trigger Mode	Condition Parameter	Description
by_code		Handled by internal game logic, or an attribute field with no default implementation.
halo	Object type#distance	Aura effect. Executes trigger commands every frame for targets inside the aura. Object type: 0 allied, 1 enemy, 2 both sides, 3 resonance.
hit_chance	Attack type list; can append command*condition	Triggers with field value as probability when hitting a target. Attack types: 0 melee, 1 ranged, 2 skill. Use swallow_dmg to clear this damage and stop later checks.
do_crit	Attack type list	Triggers on a critical hit.
every_5hits		Triggers every 5 attacks, using the field value as probability.
hit_by	Attack mode	Triggers when attacked. 0 all, 1 melee, 2 ranged.
on_crit	Attack mode	Triggers when critically hit. 0 all, 1 melee, 2 ranged.
on_dodge	Attack mode	Triggers when dodging. 0 all, 1 melee, 2 ranged.
on_block	Attack mode	Triggers when blocking. 0 all, 1 melee, 2 ranged.
on_dead	command*condition	Triggers on death. Use stop to terminate this death check.
on_skill	Skill series	Triggers when the role uses a skill. Empty means all skills.
in_abnormal	Abnormal state type	Triggers when the role enters an abnormal state. 0 all, 1 stun, 2 root, 3 taunt, 4 silence, 5 calm, 6 fear, 7 stealth, 8 control or confusion.
out_abnormal	Abnormal state type	Triggers when the role exits an abnormal state. Abnormal state types are the same as in_abnormal.
buff_weaken	Target Buff ID	Increases damage against targets with the specified Buff. Increase percentage is Buff stacks * field value / 100.
buff_dmgadd	Buff ID	Increases damage taken when the unit has the specified Buff. Increase percentage is Buff stacks * field value / 100.
defeat_tag		Triggers when defeating an enemy.
on_frienddown		Triggers when an allied unit is knocked down.
on_enemydown		Triggers when an enemy unit is knocked down.
polymorph	ModelID#ModelActionID#TransformEffectID#RestoreEffect#DynamicModelInfo	Unit transformation effect. If Model ID, action ID, or dynamic model info is RAW, the original model info is used.
global_add_stat	Condition expression group	Adds attributes to a specified object range before battle based on conditions.
week_getitem	ItemID	Gains the specified item each week. Multiple item IDs are separated with #. Only affects the main character.
name_prefix	Color code#name text size	Adds a prefix to the name. Color uses hexadecimal code. Text size can be omitted.

Damage Expression Format

Attacks, skills, effects, and commands usually describe damage resolution parameters with a damage expression. A damage expression is made of key-value pairs separated by semicolons.

key1:value1;key2:value2;...;keyN:valueN

Key	Description
type	Damage type. 0 normal melee, 1 normal ranged, 2 skill damage, 3 healing, 4 mana recovery, 5 empty hit check.
dmg	Physical damage value. The value is a damage formula.
t_dmg	True damage value. Healing also uses this value.
hit	Hit parameter, range -1000 to 1000. Use 1000 when the attack cannot be dodged.
blk	Parry parameter, range -1000 to 1000. Use -1000 when the attack cannot be parried.
cri	Critical parameter, range -1000 to 1000. Use -1000 when the attack cannot crit.
act	Whether to play the hit reaction. 1 yes, 0 no.
eft	Hit effect ID.
trig	Whether to trigger damage effects such as reflect damage.
attack_type	Specifies the weapon attack type of the damage. Type 900 is shamanic attack and uses shamanic defense.
buff	Buff attached when this damage is received. Format: BuffID,[time],[overlay]; time and stacks are optional parameters.

Damage formulas support +, -, *, /, ^, %, parentheses, and predefined fields embedded in [%cmd%] form.

Field	Description
[%rnd:min_val,max_val%]	Random integer greater than or equal to min_val and less than or equal to max_val.
[%field%]	field can be replaced with any role attribute field, returning that field's value.

Special Object IDs in Battle

When a battle command needs to locate a target unit, you can use the following built-in object IDs in addition to role IDs.

Special ID	Description
PLAYER	Player unit.
GM_A	Fixed built-in unit for side A, used to execute skill commands without a specific caster.
GM_B	Fixed built-in unit for side B, used to execute skill commands without a specific caster.
THIS	The unit currently executing the command, commonly used by unit attached scripts.
RND_ENEMY_UNIT	Random enemy common soldier unit. Enemy is relative to the current PLAYER side.
RND_FRIEND_UNIT	Random allied common soldier unit. Ally is relative to the current PLAYER side.
EMITTER={EMITTER_ID}	Emitter unit with ID EMITTER_ID.

Attached Trigger Scripts on Unit Objects

Dungeon unit objects can define attached trigger scripts in their trigger commands. Roles in the role table can also use the TAG field attached_script to specify a script event ID and attach trigger scripts to that role. Each object can attach multiple triggers.

[CMD_BEGIN]#TriggerType1#TriggerCondition(optional)#TriggerParam(optional)
command line 1
command line 2
...
[CMD_END]
[CMD_BEGIN]#TriggerType2#TriggerCondition(optional)#TriggerParam(optional)
command line 1
command line 2
...
[CMD_END]

Trigger Type	Description
on_spawn	Triggered when the unit spawns.
enter_combat	Triggered when entering battle.
get_hurt	Triggered when the unit takes damage.
dead	Triggered when the unit dies.
on_timer	Triggered when a timer on the unit expires. The timer is set by SET_UNIT_TIMER.
on_skill	Triggered when the unit starts casting a skill. The trigger parameter is the skill ID.
hp_pct	Triggered the first time the unit's HP falls below the target percentage. The trigger parameter is the target HP percentage.
interactive	Triggered when a unit with an in-battle interactable object performs an interaction.

[CMD_BEGIN]#enter_combat#
B_TALK*THIS#Close the gate, release the hounds!
[CMD_END]
[CMD_BEGIN]#get_hurt#[%this_hp_pct%][<=]5&[%dg_int_val:test_counter_1%][<=]0
SET_DG_INTVAR*test_counter_1#1#1
SKILL_CMD*THIS#THIS#0#add_buff#中立#caster
B_TALK*THIS#Stop! Stop! I surrender. Take everything!
CMD_RETREAT*1
[CMD_END]