11. ATB and turn-based

In short: The classic battle modes are menu-driven fights on a stage where two sides face each other in rows. ATB gives every unit a time bar that fills until the unit can act. Turn-based drops the bar: one unit acts at a time, in a round (everyone once, fastest first) or on a timeline (fast units come around more often). They share the same party, abilities, items and menus as the grid mode, and one director and one stage run both.

11.1 Basics

11.1.1 The words

11.1.2 Set up your first classic battle

1. Put an RSE ATB Stage in your level on open ground (or inside a dedicated arena). It shows the two sides' slots in the editor.
2. Put an RSE ATB Battle Director next to it. Set its Stage and its Encounter (an encounter whose Battle Mode is Battle.Mode.ATB or Battle.Mode.Turn).
3. Add an RSE Encounter Trigger that points at the director, or use Make Battle Zone Here (which can add a stage), or the Studio's World → New battle (see Editor tools).
4. Play. Walk into the trigger. The party stands in its formation (set in the party menu), the enemies in their rows, and the bars start to fill.

Layout the enemies and their rows with the Encounter Layout mode on the stage: drag an enemy to another slot or row, or press R to swap its row. Each enemy's ATB Row is also a field on the encounter.

11.1.3 Play a classic battle

1. A unit's gauge fills. When it is full the command menu opens for it. A banner says "Mira's turn".
2. Choose a command (the menu's structure is data, see below), then a target. The target list shows enemies by name, allies for heals, or groups ("Front row", "All enemies" with the number of targets).
3. The action plays. Abilities with a Charge Time wait before they resolve. If the target fell meanwhile, the ability hits another valid target on the same side.
4. Commands given while an action is still showing are not lost. They queue and run right after it.
5. Flee (if the encounter allows it) tries to escape. The chance depends on the speed of your party compared to the enemies. A failed attempt costs the unit's turn.

Switch characters with the next-unit key. Wait or Active can be toggled in the battle with its key (and the player can store a preference in the options).

11.2 How it works

11.2.1 One director, two time models

URSEATBBattle is the ATB battle (headless, in RSECore). URSETurnBattle derives from it and replaces only the time model. Everything else is shared: commands, rows, scopes, items, flee, summons, statuses, objectives, AI. The director picks the class with URSETurnBattleSettings::ResolveClassicMode:

1. the profile's Classic Mode Override (empty, Battle.Mode.ATB or Battle.Mode.Turn), else
2. the encounter's Battle Mode (Turn means turn-based, anything else ATB).

That is how a rules profile can switch every classic battle of a game at once.

11.2.2 ATB timing

• A gauge fills at ATB Fill Per Speed (2.0) gauge points per second per point of Speed, up to ATB Gauge Max (100). A Speed 10 unit is ready every 5 seconds.
• At battle start each gauge begins at ATB Initial Gauge Per Speed (3) times Speed, never full.
• Time advances in fixed steps (ATB Step Seconds, 1/30 s), so a battle is deterministic for a seed.
• A full gauge makes the unit ready for one command. It then pays the ability's charge time (if any) and the gauge restarts.
• Haste and slow work through the Speed stat (status modifiers).

Wait and Active are a presentation rule: the director stops calling Advance while a menu is open in Wait mode.

• Wait Pause says which open menus stop time: Any Menu (default), Submenus And Targeting (time flows on the first list) or Targeting Only.
• Wait Pauses Enemies (on): while time stands still, ready enemies wait too.
• Active Menu Time Scale: in Active mode, the speed while the player is in a sub-list or choosing a target (1 = full speed).
• Busy Commands: Queue (default) or Reject a command given while an action shows.
• Time never runs while animations play.

Initiative. If the player touches an unaware visible enemy from behind, the battle is Preemptive: the party's gauges start filled and the enemies' empty. If a chasing enemy catches the party from behind it is a Back Attack, the reverse. The shares are Initiative Gauge Fraction and Surprised Gauge Fraction in Encounters settings. The turn-based round mode has no gauges and only records it.

11.2.3 Rows, scopes and flee

• A unit in the back row deals and takes ATB Back Row Physical Multiplier (0.5) of melee physical damage, each side applying it separately. Magic and abilities with Ignores Row (bows, throwing) are not affected.
• Scope comes from the ability's ATB Rules: Single (one target), Row (the target's row), All (the target's whole side).
• Flee chance = Flee Base Chance (40%) plus Flee Chance Per Speed (3) for each point the party's average Speed exceeds the enemies', limited to 5% to 95%. Set Can Flee off on the encounter for bosses and story battles. A successful flee ends the battle as Fled.
• Pact summons take the summoner's place in the row, and the summoner steps out until the summon ends (see Characters and party).

11.2.4 Turn-based styles

Set in Project Settings → RPG Saga Engine → Turn-Based Battle (a rules-profile section):

In Round mode every active unit acts once per round, in order of initiative. A unit that falls or steps out loses its place. A summon that arrives mid-round acts from the next round. Charge times are ignored: abilities resolve at once.

In CTB mode the ATB gauge still exists (using the same fill rates as ATB) but the timeline jumps straight to the next full gauge. A unit twice as fast acts twice as often. The HUD shows the turn order strip. GetTurnOrderPreview replays the timeline on copies of the gauges.

Exactly one unit is ready at a time in turn-based modes, so Wait and Active do not matter there.

11.2.5 The command menu

The structure of the menu is data, not code. A Command Menu Layout asset (URSECommandMenuLayout) lists the top-level commands. Each one has an id, a label, a help line and a kind:

• Ability: uses the first of the unit's abilities that matches, and goes straight to targeting ("Attack").
• List: opens a list of the matching abilities, and optionally the party's items, Flee and summons.

Abilities sort into commands by their Ability Type tag (Ability.Type.Attack, Skill, Magic, Action). The first command that accepts an ability's type takes it. Abilities no command takes go to the command with Catch All ticked. A list command can also tick Include Items, Include Flee and Include Summons. Passives never appear.

• Set the project's layout in Project Settings → RPG Saga Engine → Command Menu → Default Layout. Without an asset, the Fallback Entries list gives Attack, Skills, Magic, Items and Actions.
• A class can name another layout (URSEClassData::CommandMenu). A layout can also rename or hide commands for a class tag (Class Overrides: Magic becomes "Songs" for a bard).
• Empty Groups hides empty commands or shows them greyed out. Remember Cursor opens each list where the unit's cursor was.
• The same menu structure is used in grid battles (with Move and End Turn added).

While a command is highlighted the help area shows its description, target scope, cost, element and charge time. At targeting, a cursor sits over the target and smaller ones over everyone the ability hits.

11.2.6 The stage and formation

ARSEATBStage holds the two sides' slots: Front Row Distance (300 cm), Row Spacing (180 cm) and Unit Spacing (170 cm), Lanes Per Row (a row holds this many units before newcomers use the other row), a camera, and a box showing the area. A stage can sit in an arena or directly on the live map, where the camera is framed so obstructions fade.

FRSEATBFormation (RSE, no world) gives every unit a side, a row and a lane across the row. Lanes are kept for the whole battle (fallen units lie where they stood). A row change from a knockback or swap moves only that unit. Reinforcements take the nearest free lane. A unit pushed out of place by an animation glides back after the action.

The party in a classic battle is the ATB formation (active members, default four, ATB Party Size) and their chosen rows, set in the party menu. Recruitable secondary characters never join classic battles.

11.2.7 The HUD

URSEATBHUDWidget shows the party with HP, MP and gauge state (READY, charging, QUEUED, KO), the enemies as clickable chips, the command column with the banner and help, the target list and card, the time mode, and the log. In turn-based modes it shows the round and the turn order strip (the Turn Order Bar settings control its look). Data flows through view models, so a custom UMG screen can use the same values. Text formats and sizes are in Classic Battle UI.

11.3 Key classes and assets

11.4 Settings

Project Settings → RPG Saga Engine:

The player's own Wait or Active choice is stored in their options and overrides the default. See Appendix B for the full list.

11.5 Blueprint usage

Start a classic battle on the stage next to the player:

1. Event (an NPC dialog's effect, or a button) → Find ATB Director (Encounter = DA_Encounter_Starter_Z1_Skirmish).
2. Start Battle (Encounter Override = your encounter). The director keeps its own encounter again after End Battle.
3. For a surprise attack, call Set Next Initiative (Preemptive or Back Attack) first.

Useful director nodes: Start Battle, End Battle, Set Next Initiative, Get Battle Initiative, Get Phase (Idle, Battle, Finished), Is Active, Get Battle, Get Battle Mode, Get Time Mode, Set Time Mode, Get Time Scale, Is Command Queued, Is Playback Idle, Get Battle Outcome, Get Encounter. The On Event Presented event carries every shown battle event.

Switch between Wait and Active from an options menu: Set Time Mode (Wait or Active) on the director. The settings class stores the player's choice with URSEBattleSettings::SetPlayerATBTimeMode.

Change a character's row from the party menu: the party library has Get ATB Row and Set ATB Row, plus Get ATB Formation, Is In ATB Formation and Set In ATB Formation.

In a battle effect, Get Unit and Get Unit Ids give units, and Shift Turn moves a unit sooner or later: in ATB it changes the gauge, in a round it moves the unit to the front or back of the round, on the CTB timeline it changes the gauge.

See Appendix A.

11.6 C++ usage

The classic battle runs headless exactly as the simulator and tests drive it:

URSETurnBattle* Battle = NewObject<URSETurnBattle>();
Battle->Initialize(Spawns, /*Seed*/ 11, /*bCanFlee*/ true);

while (!Battle->IsBattleOver())
{
    Battle->Advance(0.f);                       // turn-based: makes the next unit ready
    for (int32 UnitId : Battle->GetReadyUnits())
    {
        if (Battle->CanUseAbility(UnitId, Ability) == ERSEATBCommandResult::Ok)
        {
            TArray<int32> Targets;
            Battle->GetValidTargets(UnitId, Ability, Targets);
            Battle->IssueCommand(UnitId, Ability, Targets[0]);
        }
        else
        {
            Battle->PassTurn(UnitId);
        }
    }
}

ERSEATBCommandResult explains refusals: Not Ready, Blocked, Unknown Ability, Not Enough Resources, Invalid Target, Item Unavailable, Requirement Not Met, or Queued (accepted while an action is shown). Use GetAffectedUnits for a scope's real targets and GetFleeChance for the HUD. Turn-based previews come from URSETurnBattle::GetTurnOrderPreview.

Extension points on URSEATBBattle (virtual): Advance, GetActionTimeCost, UsesChargeTime, OnActionFinished, OnBattleInitialized, ApplyTurnShift. A new time model is a subclass that overrides these, which is exactly what URSETurnBattle does.

11.7 Advanced

11.7.1 Presets by genre

The rules profiles DA_Rules_Genre_ClassicATB, DA_Rules_Genre_TurnRound, DA_Rules_Genre_TurnCTB, DA_Rules_Genre_TacticsOnly and DA_Rules_Genre_Hybrid set the classic mode for a whole game. Choose one as the project default (Rules Profiles → Default Profile or Set as default in the Configurator), switch it from the story with the Set Rules Profile effect, or put it on one encounter. Hybrid has no override, so every encounter picks its own mode.

11.7.2 More than one classic encounter on a map

A map has one classic director, and the controller uses the first. An encounter trigger's Classic Encounter replaces the director's encounter for the fight that trigger starts, and the director gets its own encounter back at the end. The same works from code with StartBattle(EncounterOverride).

11.7.3 Customizing the menu

Write a new layout asset per class for different command sets (a "Songs" command, a "Tricks" command with a hidden Magic). For a completely different screen, replace the HUD widget class and bind to the view models (CurrentList, MenuPath, HelpText, the target list). The actions on the view model (HoverTarget, ChooseTarget, ToggleTimeMode...) are the same ones the default screen uses.

11.7.4 Action commands and timing

Abilities with an Action Command ask for a timed press before they are issued. The grade becomes part of the command, so it stays deterministic. Enemy attacks on a unit with a shield can open a block prompt. Setting Action Commands → Default Player Mode (or the player's option) to Offense Only or None removes prompts (see Abilities).

11.7.5 Networking and AI

The host runs the battle. Guests send commands. Enemy AI acts as soon as a unit is ready after a short AI Think Delay, and a gauge-aware AI interrupts charging units according to its intelligence (see Enemy AI). In co-op, each local player has its own command component.

11.7.6 Performance

The battle logic is a fixed-step loop with a small state. A very large number of units mainly costs presentation. Keep ATB Step Seconds at the default unless you need finer timing.

11.7.7 Development commands

In development builds: RSE.Battle.StartATB, RSE.Battle.StartTurn [EncounterName], RSE.ATB.Mode Wait|Active, RSE.ATB.Input select | cancel | up | down | next | toggle | block | ... (menu input without a keyboard), RSE.Battle.AutoPlay 1 (the AI plays your party too) and RSE.Exploration.Encounter ATB|Turn.

11.8 Troubleshooting

11.9 See also

• Battle fundamentals for encounters, objectives, rewards and the simulator.
• Abilities and statuses for ATB Rules, scope, charge time and action commands.
• Characters and party for formations, rows and Pact summons.
• Enemy AI and adaptive difficulty, Camera and battle presentation, User interface.
• Product page: docs/product/encounter-editor.md.