Battle System

Overview of the turn-based battle engine.

The battle engine is the largest subsystem in pokeemerald. It is turn-based, event-driven, and built around a central callback loop in src/battle_main.c. Each participant — player, opponent, link partner, Safari Zone — is managed by a dedicated battle controller.

Architecture

A battle proceeds through phases managed by function pointers in gBattlerControllerFuncs. The top-level callback BattleMainCB2 in src/battle_main.c dispatches to gBattleMainFunc every frame.

The global gBattleStruct (type struct BattleStruct *) holds all per-battle transient state: turn trackers, switch targets, Safari counters, arena points, and more.

Battle controllers

Each of the up to four battler positions is served by a controller that handles input, animations, and communication. Controllers are assigned at battle start based on gBattleTypeFlags.

Source file	Controller role
src/battle_controller_player.c	Local human player
src/battle_controller_opponent.c	AI-driven opponent
src/battle_controller_player_partner.c	Multi-battle human partner
src/battle_controller_link_partner.c	Remote link partner
src/battle_controller_safari.c	Safari Zone (no move selection)
src/battle_controller_wally.c	Wally tutorial battle
src/battle_controller_recorded_player.c	Recorded battle playback (player)
src/battle_controller_recorded_opponent.c	Recorded battle playback (opponent)

The shared controller infrastructure lives in src/battle_controllers.c.

Battle actions

Each battler selects one action per turn. The chosen action is stored in gChosenActionByBattler[].

// include/battle.h

// Battle Actions — determine what each battler does in a turn
#define B_ACTION_USE_MOVE               0
#define B_ACTION_USE_ITEM               1
#define B_ACTION_SWITCH                 2
#define B_ACTION_RUN                    3
#define B_ACTION_SAFARI_WATCH_CAREFULLY 4
#define B_ACTION_SAFARI_BALL            5
#define B_ACTION_SAFARI_POKEBLOCK       6
#define B_ACTION_SAFARI_GO_NEAR         7
#define B_ACTION_SAFARI_RUN             8
#define B_ACTION_WALLY_THROW            9
#define B_ACTION_EXEC_SCRIPT            10
#define B_ACTION_TRY_FINISH             11
#define B_ACTION_FINISHED               12
#define B_ACTION_CANCEL_PARTNER         12  // when choosing an action
#define B_ACTION_NOTHING_FAINTED        13  // when choosing an action
#define B_ACTION_NONE                   0xFF

Move targeting

The MOVE_TARGET_* constants define which battlers a move can hit.

// include/battle.h
#define MOVE_TARGET_SELECTED         0          // player picks the target
#define MOVE_TARGET_DEPENDS          (1 << 0)   // depends on battle type
#define MOVE_TARGET_USER_OR_SELECTED (1 << 1)   // self or selected foe
#define MOVE_TARGET_RANDOM           (1 << 2)   // random opposing battler
#define MOVE_TARGET_BOTH             (1 << 3)   // both opponents
#define MOVE_TARGET_USER             (1 << 4)   // user only
#define MOVE_TARGET_FOES_AND_ALLY    (1 << 5)   // all other battlers
#define MOVE_TARGET_OPPONENTS_FIELD  (1 << 6)   // entire opposing field

Battle script engine

Battle scripts are sequences of bytecode commands that drive battle flow: dealing damage, printing messages, playing animations, checking conditions, and branching. The interpreter advances gBattlescriptCurrInstr each frame.

Script files

data/battle_scripts_1.s   # Core battle flow scripts
data/battle_scripts_2.s   # Item use, ability triggers, and more

Scripts are authored using macros from asm/macros/battle_script.inc.

Command handler

src/battle_script_commands.c implements every battle script command. Each command is a C function that advances gBattlescriptCurrInstr when complete.

A call stack (struct BattleScriptsStack, max depth 8) allows scripts to call sub-scripts and return:

// include/battle.h
struct BattleScriptsStack {
    const u8 *ptr[8];
    u8 size;
};

Battle AI

The AI runs scripts from data/battle_ai_scripts.s and scores each move candidate.

Source file	Role
src/battle_ai_script_commands.c	Implements AI script commands; populates score[] for each candidate move
src/battle_ai_switch_items.c	Decides whether the AI should switch Pokémon or use an item on its turn

// include/battle.h
struct AI_ThinkingStruct {
    u8  aiState;
    u8  movesetIndex;
    u16 moveConsidered;
    s8  score[MAX_MON_MOVES];  // score for each of the 4 moves
    u32 funcResult;
    u32 aiFlags;
    u8  aiAction;
    u8  aiLogicId;
    u8  simulatedRNG[MAX_MON_MOVES];
};

aiFlags is loaded from trainer data and enables optional behaviors such as smart switching and item use prediction.

Battle animations

Every visual effect during a move is handled by animation source files organized by elemental type. Animation scripts live in data/battle_anim_scripts.s; the coordinator is src/battle_anim.c.

src/battle_anim_fire.c

Fire-type move visual effects.

src/battle_anim_water.c

Water-type move visual effects.

src/battle_anim_electric.c

Electric-type move visual effects.

src/battle_anim_ice.c

Ice-type move visual effects.

src/battle_anim_psychic.c

Psychic-type move visual effects.

src/battle_anim_ghost.c

Ghost-type move visual effects.

src/battle_anim_mon_movement.c

Pokémon sprite movement during animations.

src/battle_anim_status_effects.c

Status condition visual effects.

Additional animation files: battle_anim_dragon.c, battle_anim_bug.c, battle_anim_dark.c, battle_anim_fight.c, battle_anim_flying.c, battle_anim_ground.c, battle_anim_normal.c, battle_anim_poison.c, battle_anim_rock.c, battle_anim_throw.c, battle_anim_effects_1.c, battle_anim_effects_2.c, battle_anim_effects_3.c.

Battle Frontier

Each Battle Frontier facility has its own source file implementing facility-specific rules, party generation, and streak recording.

Battle Arena

src/battle_arena.c — three-turn judge-scored battles; awards Mind and Skill points.

Battle Dome

src/battle_dome.c — tournament bracket with scouting; uses BATTLE_TYPE_DOME.

Battle Factory

src/battle_factory.c — rental Pokémon battles with post-round swapping.

Battle Palace

src/battle_palace.c — AI selects moves based on nature; player has no direct move control.

Battle Pike

src/battle_pike.c — series of rooms with randomized encounters, trainers, and healing.

Battle Pyramid

src/battle_pyramid.c — ascending floors with restricted items and darkness.

Battle Tower

src/battle_tower.c — streak-based single and multi battles with BP rewards.

The BATTLE_TYPE_FRONTIER composite flag ORs together all seven facility flags: BATTLE_TYPE_BATTLE_TOWER, BATTLE_TYPE_DOME, BATTLE_TYPE_PALACE, BATTLE_TYPE_ARENA, BATTLE_TYPE_FACTORY, BATTLE_TYPE_PIKE, and BATTLE_TYPE_PYRAMID.