1. Introduction

In short: RPG Saga Engine is a framework for role-playing games in Unreal Engine 5.8: battles in several modes, characters, abilities, items, exploration, dialog, quests, saves and an enemy AI, all driven by data you author in the editor. You make a game with its tools, mostly without code or Blueprints. This chapter says what is in the box, how the plugin is organised, and how to read the rest of the manual.

1.1 Basics

1.1.1 What the plugin is

RPG Saga Engine gives you the systems a JRPG or a tactical RPG needs, and the editor tools to fill them with your own content:

• Battles in six styles that share the same party, abilities, items and rules: grid Tactics on your live map, Free Tactics (live tactics with free movement in meters), classic ATB, turn-based (by round or by timeline) and real-time Action combat, from sword fights to shooters. Each encounter names its own mode. The player never chooses it.
• Characters and growth: classes, stats and resources you define, levels, equipment, recruitable units, guests, Pacts (summons), and three growth systems (levels only, points to spend, or a growth board).
• Story and world: a global story state (flags and variables), a visual dialog editor, quests, puzzles, shops, inns, save points, maps, a clock and weather, and living NPCs.
• An adaptive enemy AI that gets smarter or makes more mistakes depending on how you play, without changing enemy stats.
• Editor tools: RPG Saga Studio (wizards for every task), the Configurator (every setting in one window), spreadsheet import and export, a battle simulator, a whole-campaign balance tool and many more.

Everything you make is ordinary Unreal data: Data Assets, Data Tables and Project Settings. You can open it, edit it, version it, import it from spreadsheets or script it.

1.1.2 Who it is for

• Designers and solo developers who would rather spend their time on the story, the characters and the world than on writing battle systems. The Studio explains every choice.
• Blueprint users who want to react to the game from their own actors and widgets. Every system has a Blueprint API in the category RPG Saga.
• Programmers and teams who want a tested, data-driven base to extend. The C++ source is included and every system has extension points (subclasses, interfaces, delegates, command handlers).

You do not need to write code to make a complete game. You need to know the Unreal editor: how to open a project, use the Content Browser, press Play and edit a Details panel.

1.1.3 The four layers of a game

The Studio organises making a game in four layers, from the bottom up. Each layer builds on the one below, and the included starter set already fills the lower ones, so you can start at any layer.

Chapter Game foundation and archetypes covers the first two layers. Later chapters cover content and world systems one by one.

1.2 How it works

1.2.1 Logic and presentation are separate

The plugin is split into modules, and the compiler enforces one rule: rules and state never depend on presentation. All game logic (battle rules, grids, pathfinding, abilities, items, AI, conditions and effects, story state, save structures) lives in a module with no actors, no widgets and no input. Because of this a battle can run headless, with no window and no rendering. The battle simulator, the balance tools and the automated tests all rely on it.

Presentation (actors, camera, input, UI, the world) sits on top and talks to the rules through events (delegates) and commands. Chapter Core concepts explains this in practice.

1.2.2 The modules

The boundaries are strict:

• RSECore never includes anything from RSE, RSEEditor or any optional module.
• The plugin never depends on a game module or on content under /Game.
• The optional bridges (RSEGAS, RSEStateTree, RSECommonUI) are inert until you use them. If you never touch them they cost nothing.

1.2.3 Where things live on disk

• Plugin content is under /RPGSagaEngine/ (turn on Content Browser → Settings → Show Plugin Content to see it): the starter data (/RPGSagaEngine/Data/...), the example map, the UI styles and more. Plugin assets are templates: the Studio never edits them in place and offers Create a copy in the project instead.
• Your content goes into your own folders, for example /Game/MyRPG. The wizards create assets only there.
• Settings are under Project Settings → RPG Saga Engine and are saved to your project's Config/DefaultGame.ini.
• Gameplay tags are defined in the plugin's Config/Tags files and in your own tag sources.

1.2.4 What the plugin turns on for you

The plugin enables the engine plugins it needs: Enhanced Input, Niagara, Animation Warping (optional), IK Rig (editor only), Online Subsystem and its utilities, Gameplay Tags Editor (editor only), and for the optional bridges Gameplay Abilities, StateTree, Gameplay StateTree and Common UI. None is Beta or Experimental. The plugin targets Windows (Win64) and Unreal Engine 5.8.

1.3 How to read this manual

The chapters go from the general to the specific.

1. Installation and your first project gets the plugin running and a playable slice open.
2. Core concepts explains the ideas every other chapter uses: data-driven content, settings, rules profiles, tags, events, saved state and validation. Read it before the system chapters.
3. Systems (foundation, characters, progression, abilities, items, battles, AI, story, exploration, world, visuals, UI, save, networking and so on) each follow the same shape. Chapter Game foundation and archetypes starts the series.
4. Reference chapters (Editor tools, Extending the plugin, Troubleshooting and FAQ, the Glossary) and four generated appendices complete the book.

Every system chapter has the same sections: Basics (the idea and a first working example using the editor), How it works, Key classes and assets, Settings, Blueprint usage, C++ usage, Advanced and Troubleshooting. If you only want to make a game, read Basics and Settings and skim the rest. If you extend the plugin, read Advanced and C++ usage.

The generated appendices are produced from the code, so they are always current:

• Appendix A: every Blueprint node, event and override;
• Appendix B: every Developer Settings class and its properties;
• Appendix C: every RSE.* console variable and command;
• Appendix D: every data asset type and its properties.

1.3.1 Conventions

• Class names are written as in the code: URSE... for objects, ARSE... for actors, FRSE... for structs, ERSE... for enums.
• Blueprint node names are written as the editor shows them, in bold or in step lists: Get Party Subsystem, Add Party Member.
• Menu paths use an arrow: Project Settings → RPG Saga Engine → Party.
• Settings are named as they appear in Project Settings, with their defaults when the default matters.

1.4 Key classes and assets

You will meet these first. Each has its own chapter.

1.5 Troubleshooting

• I cannot find a feature the manual describes. Check that you run the matching plugin version, and that the feature is not switched off in Project Settings → RPG Saga Engine → Features (see Core concepts).
• A class named here is not in my C++ project. Add the module to your Build.cs (RSECore, plus RSE for presentation classes). The optional bridges are separate modules.

1.6 See also

• Installation and your first project
• Core concepts
• Product pages: docs/product/index.md (overview), docs/product/modularity.md (using only part of the framework).

2. Installation and your first project

In short: Install the plugin (from Fab or by hand), enable it, and either open the Starter project or run Set up the project in RPG Saga Studio. In about 45 minutes you will have a playable slice, a character of your own and a battle you made yourself. This chapter walks through every step and tells you where each window is.

2.1 Basics

2.1.1 What you need

• Unreal Engine 5.8 on Windows (Win64).
• A project. A new blank project is fine (Blueprint or C++, any template). You do not need to write code.
• About 1 GB of free disk space for the plugin and the content it creates.

The plugin turns on the engine plugins it needs by itself (see Introduction).

2.1.2 Step 1: install the plugin

From Fab (recommended).

1. In the Epic Games Launcher, open your Fab Library, find RPG Saga Engine and choose Install to Engine, then pick 5.8.
2. The launcher copies the compiled plugin into the engine's plugin folder (Engine/Plugins/Marketplace). It is then available to every 5.8 project on the computer.

By hand (a zip or a source copy). Copy the RPGSagaEngine folder into your project's Plugins folder (create the folder next to the .uproject if it does not exist). A copy without a Binaries folder must be compiled: the project has to be a C++ project and you need Visual Studio 2022 with the Game development with C++ workload. When the editor offers to rebuild the missing modules, answer Yes.

Install the plugin once: either in the engine (Fab) or in the project's Plugins folder, not both.

2.1.3 Step 2: enable it

1. Open your project.
2. Edit → Plugins, type RPG Saga in the search box, tick RPG Saga Engine.
3. Press Restart Now.

After the restart you should see:

• an RPG Saga Engine menu in the main menu bar, just before Help;
• a Studio button on the level editor toolbar;
• the RPG Saga Studio window, which opens by itself and comes to the front.

The RPG Saga Engine menu is short on purpose:

2.1.4 Step 3: the fast way, the Starter project

If you downloaded the Starter project from the product page, unzip it, install the plugin (Step 1), open the project and press Play. It is a blank Blueprint-only project with a tiny playable game already made by the plugin's own tools: a village with people living their daily routines, a trader, a save point, an elder who gives a quest, a house you can enter, and one battle of every mode (grid Tactics, free-movement Tactics, active-time, turn-based at a gate, and a real-time Action arena).

The zip contains neither the plugin (it comes from Fab) nor the engine's mannequin (it comes from your own engine; the first item of the First steps list installs it).

The first time you open the project, RPG Saga Studio opens by itself with a First steps list at the top of its start page:

Hide this list removes it from the start page, and Show the first steps brings it back. Nothing in it is required.

Making a Starter project yourself. Any project with the plugin can generate the same slice with the New RPG Project commandlet:

UnrealEditor-Cmd.exe <Project>.uproject -run=RSENewProject -Root=/Game/Starter -Genre=Hybrid -Slice=Starter
    [-Foundation=Tactics] [-UIStyle=<style id>] [-NoKit]

-Foundation applies a foundation preset (its UI style becomes the default), -UIStyle picks the default UI style by its id, and -NoKit leaves the mannequin out. -DryRun prints the plan without writing anything. The people, shop, house and battle sites of the slice are listed in Project Settings → RPG Saga Engine → Starter Project, so you can change what it contains.

2.1.5 Step 4: see what the framework does (optional)

Before you build anything, play the plugin's own example:

1. RPG Saga Engine → Advanced tools → Open Example Map (or the Learn panel on the right of the Studio). The map is /RPGSagaEngine/Examples/Maps/L_RSE_StarterExample.
2. Press Play. Walk with WASD or the left stick, interact with E or the bottom face button.

The map is the first zone of the starter set: a guide explains the map, a quartermaster recruits the other starter heroes, a trader sells gear, the tall grass starts random classic battles, a patrol roams the field, a Tactics battlefield hosts the zone's key battle, and a boss waits at the far end. Characters are placeholder shapes until you install a body (next step). That is expected.

To browse the plugin's own assets, turn on Content Browser → Settings → Show Plugin Content. They are under RPG Saga Engine Content. They are templates: the Studio never changes them and offers Create a copy in the project instead.

2.1.6 Step 5: tour of RPG Saga Studio

Open RPG Saga Engine → Studio (or the Studio toolbar button).

The start page shows your game in four layers (see Introduction). Each card opens a short wizard or tool inside the Studio, and Back to the Studio (bottom left) returns to the start page.

On the right of the page:

• Continue where you left off lists the assets you created or edited lately, with thumbnails.
• Learn has short guides and the example map.
• Show advanced tools everywhere puts the Advanced tools menu sections directly into the main menu.

In a new project with no foundation applied, a blue banner says New project? Start with the foundation. You can ignore it; the starter set works as it is.

Explanations. The Explanations switch in the Studio's top right corner has three levels: Beginner (the default: a "Why it matters" panel on every page, tooltips and ? buttons), Normal (tooltips and ? buttons) and Expert (the bare fields). A ? button opens the documentation page for its field. The texts live in the data table DT_RSE_StudioHelp (Project Settings → RPG Saga Engine → Studio → Help Table), so they are translated with the rest of the plugin.

2.1.7 Step 6: set up your project

1. In the Studio, 1. Game foundation → Set up the project. (The same wizard is at RPG Saga Engine → Advanced tools → New RPG Project....)
2. Choose:
   • the content root, the folder for everything the wizard creates, for example /Game/MyRPG;
   • the genre preset: JRPG (ATB), Turn-based (rounds), Turn-based (CTB), Tactics only or Hybrid (Tactics + classic). It sets the default rules and the kinds of battle your first map gets;
   • the theme, the visual style, the languages, and whether the new maps become the project's startup maps;
   • Start From Example Map (optional): your first map becomes a copy of the example zone;
   • Copy Starter Content (optional): your own editable copy of the starter set;
   • Install Mannequin Kit: leave it ticked. It copies the UE5 mannequin from your engine's templates and gives the starter characters real bodies and animations. (Later: Advanced tools → Install UE Mannequin Kit.)
3. Read the plan on the right: every asset it will create and every setting it will change. Nothing is written yet.
4. Press Apply, then Open start map.

You now have a main menu map and a first map with a Player Start, a save point, an NPC who talks and battle sites for your genre, plus a starting party. Everything is in your own folders and in your Config/Default*.ini. Nothing is written into the plugin, and the new content validates clean.

Press Play. The first time a system appears (the first battle, the time gauges, the rows), a short tutorial card explains it and pauses the game until you page through it. Each card shows once per save, and they can be turned off in the game's Options.

2.1.8 Step 7: pick a foundation preset

The foundation is the rule book of your game. You can keep the starter rules, or start from another genre:

1. 1. Game foundation → Configure the foundation.
2. Choose a starting preset (see Game foundation and archetypes).
3. Press Next through the pages. Each has a live preview on the right and Use recommended values.
4. On Summary and Apply, press Check my project (changes nothing), then Apply.

Nothing is written before Apply. You can come back and change the preset at any time with Change the preset.

2.1.9 Step 8: make your first character

1. 3. Content → New character. A live 3D preview turns on at the right.
2. Who is it? Type a name, choose Hero.
3. Start from: pick a hero class archetype, for example Paladin.
4. How does it look? Keep the look, or pick one you imported.
5. Which class? Confirm the class and the starting level.
6. What can it do? The abilities by level; leave them as they are.
7. Where does it appear? Choose In the starting party.
8. Summary and Create, then Open the character sheet. The sheet shows everything about the character on one page, with Test in battle: a few quick simulated battles that tell you the win rate without opening a level.

Characters and party explains what you just made.

2.1.10 Step 9: make your first battle and play it

1. Open the first map. In the viewport, look at an open, flat piece of ground near the Player Start: the battle is placed in front of the camera.
2. 4. World → New battle. Choose the battle mode (for example Tactics), add one or two enemies, read the estimated difficulty (aim for Fair), set rewards, and under Where it happens choose A Tactics zone.
3. Create, then Test now for a quick simulated check. Undo (Ctrl+Z) removes what was placed.
4. Save the level (Ctrl+S) and press Play. Walk into the battle site. The world turns into a grid on the ground. Place your units on the blue tiles and start. Moving and acting both cost Action Points, in any order.

You have made a playable RPG battle without code.

2.1.11 Step 10: check your work

RPG Saga Engine → Validate All Data checks every setting, rules profile and data asset. The results open in the Message Log under RPG Saga Engine Validation. Run it before you package and whenever something behaves strangely.

2.2 How it works

• The plugin loads its modules at editor start: the runtime modules (RSECore, RSE, RSENet, RSEOnline and the optional bridges) and the editor modules (RSEEditor and friends).
• Plugin defaults (Config/Defaults/Game.ini inside the plugin) are applied under your project's config: a key is used only when your Config/DefaultGame.ini does not set it. This is how a plugin-only project already has the starter content registered with the Asset Manager.
• The wizards write only to your project: assets into the content root you chose, settings into your Config/Default*.ini. They show a plan first and write nothing until you press Apply.
• The Studio is a front end. Every card ends up creating ordinary data assets and settings. Anything you can do in the Studio, you can also do in the Content Browser, the Configurator or Project Settings.

2.3 Key classes and assets

2.4 Settings

The full lists are in Appendix B.

2.5 Blueprint usage

The setup tools are editor tools and need no graph. In your own game graphs, two nodes are useful on day one:

• Is Feature Enabled (category RPG Saga → Features) tells your own UI whether a system is switched on.
• Get Party Subsystem (category RPG Saga → Party) returns the object that holds your party.

Example: show a Quests button only when quests are on.

1. In your widget, Event Construct.
2. Is Feature Enabled with Feature = Quests.
3. Set Visibility of the button from the result (Visible or Collapsed).

See Appendix A for every node.

2.6 C++ usage

A C++ project that uses plugin classes adds the modules to its Build.cs:

PublicDependencyModuleNames.AddRange(new string[] { "RSECore", "RSE" });
// Add "RSEGAS", "RSEStateTree" or "RSECommonUI" only if you use those optional bridges.

Then include headers by their domain folder, for example Characters/RSEPartySubsystem.h. Never add RSEEditor to a game module that ships in a packaged build.

2.7 Advanced

• Command-line setup. -run=RSENewProject accepts -Root, -Genre, -Theme, -MenuMapName, -FirstMapName, -Enemies, -NoMenuMap, -NoFirstMap, -NoParty, -NoKit, -NoSettings (create assets and maps only), -DryRun, -Slice=Starter, -Foundation=<preset> and -UIStyle=<style id>. Use it on a build machine to produce the same starting point every time.
• Unattended runs. The Studio never opens by itself when the editor runs unattended, in automation, in commandlets or with -NoRSEStudio.
• Using only part of the plugin. Systems can be switched off in Project Settings → RPG Saga Engine → Features, and our state can live inside your own SaveGame. See Core concepts and docs/product/modularity.md.
• Packaging. The plugin ships compiled for Win64. A Blueprint-only project never shows a compile prompt.

2.8 Troubleshooting

2.9 See also

• Core concepts
• Game foundation and archetypes
• Characters and party
• Editor tools
• Product pages: docs/product/getting-started.md, docs/product/studio.md, docs/product/starter-content.md, docs/product/editors-and-wizards.md.

3. Core concepts

In short: A handful of ideas explain how the whole plugin works: content is data, rules are settings, state is plain serializable data, logic is separate from presentation, and everything is checked by validation. Learn them once here and every other chapter will read the same way.

3.1 Basics

3.1.1 Content is data

Everything a player meets in an RPG Saga Engine game (a class, a character, an ability, an item, an enemy group, a dialog, a quest) is a data asset you create in the Content Browser or with a Studio wizard. New content means new data, not new code or new Blueprints.

Data assets derive from URSEPrimaryDataAsset. They share a few fields:

• Display Name: the player-facing, localizable name. While it is empty, the asset name is shown, so placeholder content still reads.
• Dev Notes: design notes for your team (editor only, stripped from packaged builds).
• Balance Locked: tells the balance tools never to change this asset.
• Archetype link (editor only): the template the asset follows. See Game foundation and archetypes.

Data assets refer to each other by reference (a class lists abilities, a character names its class). Saved games never store those references as pointers: they store IDs (see below), so content can be renamed, moved or removed between versions without breaking old saves.

3.1.2 IDs and the Asset Manager

Every data asset has a Primary Asset Id: its type (the first native class name, for example RSEAbilityData) plus its asset name. Save files, runtime state and the tools use this stable ID. Two practical consequences:

• Give assets clear, stable names (DA_Ability_Fireball, DA_Char_Hero) and avoid renaming them after players have saves. If you must, add a redirect: the save system applies Unreal's core redirects and the Asset Manager's redirects when it loads old content references.
• The folders are scanned by the Asset Manager. The plugin registers its own folders (for example /RPGSagaEngine/Data/Abilities) through its default config. The Set up the project wizard registers your content root the same way, so your assets are found at run time.

3.1.3 Gameplay tags

Gameplay Tags name the things that content and rules share: stats, resources, elements, statuses, classes, equipment kinds and story flags. The plugin uses tag families with a fixed root:

Tags are edited in Project Settings → Gameplay Tags. The plugin's own tags are in its Config/Tags files. Your tags go in your project's tag sources. Only the tags that C++ code references directly are native (RSEGameplayTags::Battle_Mode_Tactics and so on). All content tags are plain data, so you can add your own stats, elements and statuses without code.

3.1.4 Settings: the rules of your game

Global rules live in Project Settings → RPG Saga Engine, one page per system (Battle, Grid, Items, Economy, Party, Progression and more). Each page is a subclass of URSEDeveloperSettings, saved to your project's Config/DefaultGame.ini. You can edit them in three places:

• Project Settings → RPG Saga Engine → <page>;
• the Configurator (RPG Saga Engine → Configurator): every settings page in one window, grouped by domain, searchable, with validation, a Reset section to defaults button and quick test launch buttons;
• the Studio's wizards, which write settings for you and show what they will change first.

There are no tunable numbers hardcoded in the plugin. If a rule has a number, it has a setting or a field on a data asset.

3.1.5 Rules profiles

A Rules Profile (URSERulesProfile) overrides some settings for one place: a boss, a chapter, a "story mode", a genre. A profile holds one override per settings page (a section) and only stores what differs from the global settings. Everything else follows the global values.

Lookup order for a setting, in the first match wins:

1. the encounter's own profile (an encounter can name one);
2. the game's active profile (chosen by the story with the Set Rules Profile effect, saved with the game, default from Project Settings → RPG Saga Engine → Rules Profiles → Default Profile);
3. the profile's parent, then its parent's parent, and so on;
4. the global settings.

A running battle copies the profile it started with, so switching the game's profile never changes a battle in progress. Some fields are global only because they must match your content (for example the tile size of the grid, the maximum level, the starting party). A profile's value for them is ignored and validation warns when it differs.

To make a profile in the Configurator, open Rules Profiles → New profile, then Add override on the sections you want to change. Debug commands: RSE.Rules.Dump logs the active profile and its overridden sections; RSE.Rules.SetProfile <AssetName | None> switches it.

3.1.6 Feature toggles

Project Settings → RPG Saga Engine → Features has one checkbox per system (Grid Tactics, Live Tactics, ATB / Turn-Based, Action Combat, Dialog, Quests, Story Scenes, Inventory, Economy, Growth / Progression, Living NPCs, Time and Weather, Map and Minimap, Stealth, Puzzles, Cards, Bestiary, Tutorials, Adaptive Difficulty, Online and Co-op). All are on by default. A switched-off system is not created at all: its subsystems do not exist, so it costs no memory or time, and its menu pages, option rows and HUD widgets disappear.

Never switched off: the party, the save system, the story state (flags and variables), the rules and the command bus.

The Configurator's Validate button warns about combinations that leave something half-working (for example Quests on, Dialog off). For one test run only, -RSEDisableFeatures=Quests,Cards on the command line turns features off without touching your settings.

3.1.7 Validation

Data is checked in the editor with Unreal's standard Data Validation (IsDataValid), so problems appear when you save, in the Message Log and in the Content Browser. RPG Saga Engine → Validate All Data checks every setting, rules profile and data asset at once and opens the results in the Message Log under RPG Saga Engine Validation. The Studio's wizards keep Create disabled until every problem is fixed, and say why at the bottom of the window.

Run Validate All Data before you package and whenever something behaves strangely.

3.2 How it works

3.2.1 Data → rules → presentation

The plugin has three layers, and information flows one way:

data assets + settings   ->   rules and state (RSECore)   ->   presentation (RSE)
(what you author)             (what happens)                    (what the player sees)

• Data is authored by you.
• Rules (RSECore) read the data and compute what happens: damage, turn order, pathfinding, conditions, effects, story state. They use no actors, no widgets, no input and no rendering.
• Presentation (RSE) reads the rules' state and events and shows them: actors in the world, animation, camera, HUDs and menus.

Because rules never include presentation, a battle can run headless. The battle simulator, Test in battle, the difficulty estimates and the automated tests all play real battles with no window. Presentation reacts to what rules report through events (delegates), and sends player actions back as commands.

3.2.2 State is plain data

All runtime state (the party, inventory, story flags, quests, progression) is stored in plain structs whose saved fields are marked SaveGame. Content is referenced by soft path or ID, never by pointer. Three properties follow:

• Saving is serializing those structs. A system that wants to be saved registers a save participant with the save system, which owns one named section of the save file (Party, Narrative, Quests...). Each section has a version number, so old saves are converted by the system that owns the section, and fields added later load as their defaults.
• Missing content never crashes a load. Content removed since the save was made is dropped with a warning.
• State is the unit of networking. The same sections are what co-op replicates (see Co-op and online).

The Blueprint nodes of the Save Interop group (Export Sections To Bytes, Import Sections From Bytes and friends) let you keep plugin state inside your own SaveGame. See Save and load.

3.2.3 Commands: one path for player actions

Player actions that change shared state go through the command bus (URSECommandSubsystem). A command is a small struct (Add Party Member, Equip Item, Bind Pact, Unlock Growth Node) with a handler that validates it and then applies it:

Submit(command) -> validate -> apply -> result (Applied / Rejected / ...)

In single player it runs locally, on the spot. In a co-op session a guest's command travels to the host, which validates and applies it and sends the result back. There is one code path for every mode, so your own systems become network-ready by using it. Menus, input and Blueprint nodes all send commands; the authority's own systems (battle results, loads, story effects) write state directly.

3.2.4 Conditions and effects: one language for content

Dialogs, quests, puzzles, encounters, interactions and abilities all use the same primitives:

• a condition is a question about the game state: has the item, a flag has a value, a member is in the party, a puzzle is solved (URSECondition subclasses such as Flag Is, Has Item, Member In Party, Puzzle Solved, combined with All Of, Any Of and Not);
• an effect is a change: set a flag, give or take an item, add a member, give experience, start a battle, start a dialog, unlock an area (URSEWorldEffect subclasses such as Set Flag, Give Item, Add Member, Start Battle, Start Dialog, Unlock Area).

You add them inline in any data asset's list. Every effect also has an Only If gate. Story, dialog and quests covers the full list. Your own conditions and effects can be Blueprint classes (Extending the plugin).

3.2.5 Formulas as data

Derived stats, combat damage, hit chance and resource gains are small formulas written in data (FRSEExpression), compiled once when the project loads and evaluated without allocations. The language has numbers, + - * / % ^, comparisons, && and ||, and the functions min, max, clamp, floor, ceil, round, abs, sqrt, pow and if. Names refer to stats by short name (Stamina), to the unit with a scope (Attacker.Attack, Target.Defense) and to context variables (Level, Power). See Game foundation and archetypes.

3.3 Key classes and assets

3.4 Settings

Every page is documented in Appendix B.

3.4.1 Console variables and commands

Debug switches are console variables and commands under RSE.*; no debug behaviour is hardcoded. A few you will use early:

The full list is in Appendix C.

3.5 Blueprint usage

All Blueprint nodes are under the category RPG Saga. Systems that need the game's state take a hidden World Context Object, so you can call them from any actor, widget or game instance.

Reading the game's rules and state:

1. Event BeginPlay
2. Is Feature Enabled (Feature = Dialog)
3. Branch on the result, then create your dialog button only on True.

Switching the rules profile from a graph:

1. In data, prefer the story effect Set Rules Profile. In a graph, use Get Game Instance Subsystem (class RSERulesSubsystem), then call Set Active Profile on it and pass your profile asset.
2. Bind to On Rules Profile Changed on the same object to refresh your UI.

Sending a command from Blueprint:

1. Make Instanced Struct with the command type, for example Add Party Member.
2. Fill its fields (Character = your character asset).
3. Get Game Instance Subsystem (class RSECommandSubsystem) → Submit Command.
4. Read the result's Status.

Most systems also have convenience nodes that do the same in one call. For example, Add Party Member in the party library sends that command for you. See Appendix A.

3.6 C++ usage

Read a rule through the active profile instead of the raw settings, so profiles keep working:

#include "Core/RSERulesSubsystem.h"
#include "Battle/Common/RSEBattleSettings.h"

int32 GetATBPartySize(const UObject* WorldContext)
{
	const URSERulesProfile* Profile = URSERulesSubsystem::GetActiveProfileFor(WorldContext);
	const URSEBattleSettings* Battle = RSERules::Get<URSEBattleSettings>(Profile);
	return Battle->ATBPartySize;
}

Never call GetDefault<T>() for a settings class that is a rules profile section in rule code. RSERules::GetGlobal<T>() states the intent when you do want the global value.

A new settings page is a subclass of URSEDeveloperSettings:

UCLASS(Config = Game, DefaultConfig, EditInlineNew, meta = (DisplayName = "My Rules"))
class UMyRulesSettings : public URSEDeveloperSettings
{
	GENERATED_BODY()
public:
	// A rules profile may override this page.
	virtual bool IsProfileSection() const override { return true; }

	UPROPERTY(Config, EditAnywhere, Category = "Combat", meta = (ClampMin = "0"))
	float MyBonus = 1.f;
};

It appears under Project Settings → RPG Saga Engine and in the Configurator automatically. Add EditInlineNew and IsProfileSection only if a profile may override it.

A system that stores its own save section registers a struct:

// In a UGameInstanceSubsystem::Initialize
URSESaveSubsystem* Save = Collection.InitializeDependency<URSESaveSubsystem>();
Save->RegisterStruct<FMyState>(TEXT("MyState"), /*Version*/ 1, this, [this] { return &State; });
// After changing State at run time (the authority only):
Save->MarkSectionChanged(TEXT("MyState"));

Gate a subsystem on a feature toggle with RSE_FEATURE_GATE(ERSEFeature::Cards) right after GENERATED_BODY(), or by calling RSEFeatures::IsEnabled from ShouldCreateSubsystem.

3.7 Advanced

• Profile sections. Only settings classes that return true from IsProfileSection() can be overridden. A profile's section is created inline (EditInlineNew), initialised from the global values the first time, and stores a value only if it differs. Use GetGlobalOnlyProperties() for fields that must always come from the global settings.
• Writing rules code. Rule code reads settings through RSERules::Get<T>(Profile) and never through the class default object. Battles read through their own copy of the profile (URSEBattle::GetRules<T>()).
• Subsystem lookup in tests. Headless tests create subsystems with NewObject without a subsystem collection. RSESubsystemLookup::FindFor<T>(Object) finds either kind, so write rule code with it when it must run in tests.
• No Tick by default. Systems use events, timers and one-shot tickers. If you add a system, do the same.
• Heavy references are soft. Mesh, texture and animation references on data assets are TSoftObjectPtr, so loading a data asset never pulls its art in.
• Save versions. Never rename a section id once saves exist. Bump the version and convert old bytes in ReadSaveSection.
• Extending the language. New conditions and effects are subclasses of URSECondition and URSEWorldEffect, or Blueprint classes of Custom (Blueprint). Both are EditInlineNew, so they appear in every list at once.
• Plugin defaults. The plugin's Config/Defaults/Game.ini is applied under your config at load. A key you set in your DefaultGame.ini wins. A list you set (any +Key= or !Key=ClearArray) replaces the plugin's list.

3.8 Troubleshooting

3.9 See also

• Game foundation and archetypes
• Story, dialog and quests
• Save and load
• Co-op and online
• Extending the plugin
• Product pages: docs/product/modularity.md, docs/product/glossary.md; design notes docs/design/rules-profiles.md, docs/design/configurator.md, docs/design/attributes.md.

4. Game foundation and archetypes

In short: The Game Foundation is the rule book of your game: what you call things, which stats and resources exist, how damage is computed, which elements and equipment slots there are, which battle modes you use, and how progression and money work. Archetypes are templates you make content from ("a typical knight", "a healing spell"). You choose a foundation preset first, then make content that follows archetypes.

4.1 Basics

4.1.1 What the foundation decides

The foundation answers "what kind of RPG is this?". Does it have MP or Stamina? Fire and ice, or plasma and radiation? Grid battles or active-time battles? It has nine parts:

Applying a foundation writes into settings you can also edit by hand (the attribute registry, Combat Formulas, Battle, Turn-Based Battle, Items, Command Menu, Progression, Economy, Bestiary and Game Terms). Nothing new runs in the game: a foundation is a convenient, validated way to set a lot of settings at once, and you can keep editing Project Settings afterwards.

4.1.2 Foundation presets

Presets live in /RPGSagaEngine/Data/Foundation and appear as cards on the first page of the wizard.

Every preset except Empty comes with a small starter set made for it (four hero classes with their heroes, five abilities per class that use the preset's resources and damage types, eight items, five enemies and three battles). Every preset is validated and played in a simulated battle in each of its modes by the plugin's automated tests.

4.1.3 First working example: apply a preset

1. Open the Studio: RPG Saga Engine → Studio.
2. 1. Game foundation → Configure the foundation.
3. On the first page, pick a starting preset (for example Dark Fantasy) or My current setup (your Project Settings as they are).
4. Go through the pages: Vocabulary, Stats and resources, Battle formulas, Elements, Equipment and items, Abilities and the battle menu, Battle modes, Progression, Economy. Each has a short explanation, the fields, Use recommended values (back to the preset's values for this page) and a live preview on the right: | Page | Preview | |---|---| | Vocabulary | the battle screen and command menu with your words | | Stats and resources | a sample character's stats at any level (derived stats use your formulas) | | Battle formulas | a damage calculator: power, attack, defense, result | | Elements | the weakness matrix: what a 100-damage hit does to a weak, resistant, immune or absorbing target | | Equipment and items | what a character wears and the inventory tabs | | Abilities and the battle menu | the command menu | | Battle modes | the modes and the party size | | Progression | experience needed at levels 2, 5, 10, 20, 50 and the last level | | Economy | starting money, what a 100 item sells for, an inn night |

1. On Summary and Apply, press Check my project (changes nothing). It lists the tags to add and the content that uses stats, elements, slots or categories the foundation drops, with a proposed replacement for each (for example MP becomes Energy). Change the replacements if you want and press Apply the replacements to my content.
2. Optionally tick Copy the starter content into my project when I press Apply and Use the starter heroes as my starting party.
3. Press Apply. The foundation is saved in your project (/Game/Foundation) and written into Project Settings. It stays blocked while content would break, unless you tick Apply anyway.

Pick the foundation first, before you make much content: it is cheaper to choose "Stamina instead of MP" on day one than to replace it in a hundred abilities later (although the replacement tool does that for you).

4.1.4 Archetypes

An archetype is a template you create content from: "Knight", "Goblin", "Merchant", "Healing spell". Content made from an archetype remembers it and follows it for every field you did not change.

Working with them in the Studio:

1. 2. Archetypes → Archetype library shows every archetype of your project and of the plugin. Filter by kind, role (tank, damage, support, merchant...), library tag, search text, or Mine only.
2. Click a card. The right panel offers New character from it / New enemy from it, Create content from it, Open the archetype sheet, Duplicate, Duplicate as child (a variant that keeps following the original, such as Fire Knight from Knight), Show who uses it and Update content from it....
3. Plugin archetypes are templates. Duplicate one into your project before you change it.
4. New class, New enemy type and New NPC type make a new archetype in three steps: start from, name and one-sentence summary, Create. You set its values on its sheet.

4.1.5 How content follows its archetype

• An inherited field is shown greyed, with from archetype X next to it.
• A field you change becomes overridden and is yours. Editing an inherited field anywhere (the sheet, the generic editor, the Details panel) marks it overridden automatically.
• Reset to archetype brings the archetype's value back. Reset all to archetype drops every override. Keep my changes marks every difference as an override.
• Nothing changes silently. When you save an archetype and some content now differs, a notification offers Review changes. The update list shows every asset made from the archetype with what would change (old value, new value). Check the assets that should follow, press Apply to checked. Values an asset changed itself are listed as kept and never touched. Plugin assets are never changed from here.
• When a variant (child archetype) changes, Continue with ... reviews its own content the same way.
• The game never loads archetypes: content always holds its final values, so there is no runtime cost, and content made without an archetype works exactly the same.

Make an archetype for anything you will create more than three times (a family of goblins, a kind of healing potion).

4.2 How it works

4.2.1 Applying a foundation

A foundation (URSEGameFoundation) is a data asset only; it is editor-only and never cooked. Applying it:

1. Validates it (Validate Foundation): missing required stats (Stat.Speed; Tactics also needs Stat.ActionPoints and Stat.Jump), Resource.HP, formulas that do not compile, unknown tags, empty menus.
2. Adds missing tags to the project's tag file (Game Foundation → New Tag Source, RSE_Foundation_Project.ini by default).
3. Checks change safety: scans the project's content (and, if you ask, the framework's own settings: Pacts, Bestiary, Progression Designer) for stats, elements, slots and categories the new foundation drops, and proposes replacements (the foundation's Suggested Replacements first).
4. Writes the project's attribute registry and command menu layout (into Game Foundation → Project Foundation Folder, /Game/Foundation), writes the settings and saves them to Config/DefaultGame.ini, and remembers the foundation (Applied Foundation).
5. Optionally copies the starter content into /Game/StarterContent/<Preset> (Starter Content Folder), keeps assets you already have, and can make the starter heroes your starting party.

Copying again never loses your edits: assets already there are kept. Reset starter assets that are already in my project is off by default; on, existing assets go back to the starter values, but nothing is ever deleted or moved. The copies point at each other, never at the plugin's originals. A foundation's UI style becomes the project's default style when you apply it in the Studio.

4.2.2 Stats, resources and the attribute registry

Stats and resources are defined in an Attribute Registry (URSEAttributeRegistry), chosen in Project Settings → RPG Saga Engine → Attributes. Without one, the framework's built-in definitions (HP, MP, Resonance and the standard stats) apply, which reproduce the default rules exactly.

An attribute (FRSEAttributeDefinition) is a stat such as Stat.Attack: tag, display name, short label, the short name formulas use, a category and description, a minimum and optional maximum, a rounding mode (None, Floor, Round, Ceil), an optional Derivation formula, and whether it shows in menus. A plain attribute comes from class growth and modifiers. A derived attribute has a formula over other attributes, for example 50 + Stamina * 10 + Level * 5 for Max HP. Formulas can read Level and Base (the attribute's own base value from class growth).

A resource (FRSEResourceDefinition) is a current value with a maximum that changes in battle: Resource.HP, Resource.MP, Resource.Resonance, or your own (Rage, Steam). Its fields are:

• Maximum: an attribute (Stat.MaxHP) or a formula; Availability, a formula that says whether a unit has the resource at all (HasPact);
• Start: Full, Empty or a fixed value; Persists After Battle, so the party keeps the value between battles and saves it (HP and MP usually do);
• Change over time: Regen Per Turn, Regen Per Second (ATB and real-time modes), and gain rules that grow the resource on battle events (damage dealt, damage taken, kill, perfect command, block, ability used);
• HUD style: where it shows, the bar style, colors that follow the UI theme, a low-value color and an icon.

Resource.HP is the life resource: 0 defeats a unit. Every other rule is data.

4.2.3 Formulas and stats

The order of operations for one stat is always the same, whatever the order of its sources (class, equipment, statuses, Pacts, growth boards, personal modifiers):

1. Base: the class's growth at the level, or, for a derived stat, the formula's result.
2. Add: plus the sum of all Add values.
3. Percent: times 1 + (sum of all Percent values) / 100, so 20 means +20%.
4. Multiply: times the product of all Multiply values (1.5 is +50%, two of them multiply each other).
5. Override: the stat becomes the Override value (with several, the last source wins).
6. Clamp Min / Clamp Max: at least the largest Clamp Min, at most the smallest Clamp Max (if they cross, the maximum wins).
7. The attribute's own rounding and its Min and Max from the registry.

A Multiply of 0 sets the stat to 0, so validation of an equipment asset warns about it. Examples: a ring with Multiply 1.1 on Attack, a curse with Clamp Max 50 on Speed, a boss phase with Override 999 on Defense.

Combat formulas (Project Settings → RPG Saga Engine → Combat Formulas, a rules-profile section) are the same kind of formulas: which stats feed physical and magical offense and defense, and the expressions for Defense Factor, Physical Damage, Magical Damage, Fixed Damage, Healing, Hit Chance, Critical Chance, Critical Multiplier and Final Damage. Names inside them: Power, Offense, Defense, DefenseFactor, Position, Variance, HitBonus, Damage, Affinity, Level and the battle's constants (such as DefenseConstant), plus Attacker.<stat> and Target.<stat> for any stat. The defaults reproduce the framework's original numbers.

Formula tester. Studio → Formula tester (also Test with a real class and equipment under the stats preview of the foundation wizard). Pick a character, a class or a hero class archetype, a level and the equipment worn, add extra modifiers to try, and press Compute. Every attribute and derived stat is listed with its final value, the value it started from, the modifiers that apply in order, and its formula. Problems are highlighted: red for an unknown variable, a syntax error or a cycle (the base value is used until you fix it), orange for a division where a stat it reads is 0 (the formula counts that part as 0).

4.2.4 Elements and the weakness table

Elements are tags under Element.*. A unit's affinity to an element is one of Normal, Weak, Resist, Immune or Absorb. When sources disagree, the strongest protection wins (Absorb over Immune over Resist), and Resist plus Weak cancel to Normal. The damage multiplier per affinity is the Affinity Multipliers map in Project Settings → RPG Saga Engine → Battle; a foundation can write its own.

4.2.5 Equipment slots and item categories

Equipment slots (FRSEEquipmentSlotDef) are a list in Project Settings → RPG Saga Engine → Items → Equipment Slots: a slot id (Weapon, Accessory1), a display name, the slot type it accepts (Equip.Slot.*), the body part for the paperdoll, an empty icon, and where an item worn there is shown on the body. The foundation also names the off-hand slot that a two-handed weapon occupies, the equipment kinds classes may use (Equip.Type.*: firearms, blades, implants) and the item categories for inventory tabs. A Equipment Slot Set asset (URSEEquipmentSlotSet) can hold a ready slot layout and apply it to the project.

The foundation also sets the inventory mode: Shared (one party grid: classic JRPG, ATB, Tactics) or Per Character (a bag per member and a stash at save points). It can be switched later in both directions.

4.2.6 The battle command menu

The classic battle menu (Project Settings → RPG Saga Engine → Command Menu) is a layout (URSECommandMenuLayout): an ordered list of top-level commands. Each command (FRSECommandMenuEntry) has an id, a label, a help line, a kind and the ability types that go into it (children included), plus options:

• Kind: Ability uses the first matching ability at once (an "Attack" command), List opens a list (Skills, Magic, Items, Actions).
• Catch All: abilities no other command takes come here (one command should have it).
• Include Summons, Include Items, Include Flee.

A class can name its own layout (URSEClassData::CommandMenu) and a layout can rename or hide commands for one class (Class Overrides). Commands with nothing in them are hidden or shown disabled (Empty Groups). The menu remembers the cursor per unit (Remember Cursor).

4.2.7 Game Terms: the words on screen

Every screen reads its vocabulary from Game Terms (Project Settings → RPG Saga Engine → Game Terms): the battle HUDs, party menu, shop, battle results, save and load screens, bestiary, battle log and Pact screens. Change a term (or apply a foundation) and every screen follows, with no restart. The ids screens ask for:

Tag Names gives player-facing names to tags (Element.Fire becomes "Fire", Equip.Type.Weapon.Firearm becomes "Firearm"). The ability groups of the party menu use the names of the ability categories.

Screen texts in Project Settings use the words as arguments, for example {Term.LevelShort} {Level} or +{Amount} {Term.ExperienceShort}. Keep the argument to follow the game's vocabulary, or type a fixed word to override it for that screen only. Terms are localizable text.

4.3 Key classes and assets

4.4 Settings

Every page is in Appendix B.

4.5 Blueprint usage

At run time, the foundation's words and rules are available through simple nodes (category RPG Saga → Foundation):

• Get Game Term (Id, Fallback) returns the game's word for an id.
• Resolve Game Terms (Text) fills the {Term.<Id>} arguments of any text.
• Get Known Game Terms lists every word with its default and current value.
• Get Tag Display Name (Tag) returns a tag's player-facing name.

Example: a custom HUD label that follows the game's vocabulary.

1. Event Construct in your widget.
2. Get Game Term with Id = LevelShort, Fallback = "Lv".
3. Format Text with {0} {1} (term, current level) and Set Text on your label.

In the editor (Editor Utility Blueprints and Python), the foundation tools are categories RPG Saga → Foundation and RPG Saga → Studio → Foundation:

• Validate Foundation, Is Foundation Valid, Get Foundation Presets, Get Missing Tags;
• Plan Foundation Apply To Project (changes nothing), Apply Foundation To Project, Apply Foundation With Starter Content;
• Copy Starter Content To Project, Copy Starter Content With Options, Plan Starter Content Copy;
• Create Project Foundation, Analyze Impact, Apply Replacement Mapping To Project;
• Run Foundation Test Battle, Run Starter Content Battles;
• Run Formula Test and Format Formula Test Report.

Archetypes (categories RPG Saga → Archetypes and RPG Saga → Studio → Archetypes): Find Archetypes, Create Content From Archetype, Duplicate Archetype, Create Archetype From Content, Find Assets Using Archetype, Compute Propagation In Project, Apply Propagation And Save, Set Parent Archetype, Reset Field To Archetype, Is Field Inherited, Is Field Overridden, Get Out Of Date Fields.

Example: make a new goblin from an archetype in an Editor Utility Blueprint.

1. Find Archetypes (Kind = RSEEnemyArchetype, Content Class = RSECharacterData).
2. Pick the archetype, then Create Content From Archetype (Folder = /Game/MyRPG/Enemies, Asset Name = DA_Char_Goblin, Save = true).
3. Check Out Error is empty.

The full node list is in Appendix A.

4.6 C++ usage

Apply a foundation from an editor module and read the result:

#include "Foundation/RSEFoundationLibrary.h"
#include "Archetypes/RSEFoundationEditorLibrary.h"

void ApplyPreset(const URSEGameFoundation* Preset)
{
	// 1. Dry run: lists errors, missing tags and content that would break.
	const FRSEFoundationApplyReport Plan = URSEFoundationEditorLibrary::PlanFoundationApplyToProject(Preset);

	// 2. Apply. Refused (nothing written) when content would break and bAllowBreakingChanges is false.
	const FRSEFoundationApplyReport Report =
		URSEFoundationEditorLibrary::ApplyFoundationToProject(Preset, /*bAllowBreakingChanges*/ false);
}

Read the game's words at run time in your own widgets:

#include "Foundation/RSEGameTerms.h"

const FText PartyWord = RSEGameTerms::Get(RSEGameTerms::Party, NSLOCTEXT("MyUI", "Party", "Party"));
const FText Label = RSEGameTerms::Resolve(FText::FromString(TEXT("{Term.LevelShort} 5")));

Compute a stat the way the game does:

FRSEFormulaTestInput Input;
Input.Character = MyCharacter;   // or ClassData / Archetype
Input.Level = 20;
const FRSEFormulaTestResult Result = URSEFormulaTesterLibrary::RunFormulaTest(Input);
UE_LOG(LogTemp, Display, TEXT("%s"), *URSEFormulaTesterLibrary::FormatFormulaTestReport(Result));

Extension points: a new archetype kind is a subclass of URSEArchetype that overrides GetBaseContentClass() (and InitializeNewTemplate() for kind-specific defaults); all archetype classes share one Asset Manager type, RSEArchetype. Terms are plain ids, so a game can define any id of its own and use {Term.MyWord} in screen texts.

4.7 Advanced

• Per-zone or per-boss formulas. Combat Formulas, Attributes and Battle are profile sections, so a Rules Profile can give a boss other formulas or a zone another attribute registry. Keep persistent resources consistent between registries used in the same game.
• Suggested replacements. A foundation's Suggested Replacements map (for example Resource.MP to Resource.Energy) is what the breaking-change report offers first. Fill it when you make your own foundation that drops tags of the plugin's.
• Your own foundation. Change the preset → My current setup captures the project's settings into a foundation asset in your project (Create Project Foundation), which you edit in the wizard. Presets in the plugin stay untouched.
• Resource gain rules. A gain rule's amount is a formula that can read Amount, DamagePercent and, for Pacts, the Pact rates, so a resource can grow in proportion to damage taken or on perfect commands. Pact resources use this (see Characters and party).
• Archetype internals. An archetype holds a Template (an instanced data asset of its Content Class) and a list of Non Inherited Fields (identity such as the class tag, copied once at creation). Content stores an FRSEArchetypeLink (the archetype plus the overridden field names), which is editor-only data. Propagation recomputes differences when you apply, so a stale report can never overwrite anything.
• Scripting archetypes. Use Set Template From Content to turn a hand-made asset into a template, Detach From Archetype to stop an asset following its archetype (it keeps its values), and Validate Archetype Link in batch checks.

4.8 Troubleshooting

4.9 See also

• Core concepts for settings and rules profiles
• Characters and party
• Progression
• Abilities and statuses
• Items, inventory and economy
• Product pages: docs/product/archetypes-and-foundation.md, docs/product/studio.md, docs/product/starter-content.md; design notes docs/design/studio.md, docs/design/attributes.md.

5. Characters and party

In short: A class (URSEClassData) defines stat growth, abilities by level and allowed equipment. A character (URSECharacterData) is a specific hero, recruit or enemy with a fixed class plus personal traits. The party (URSEPartySubsystem) holds who is in your team, their levels, equipment, resources and Pacts for the whole game, and survives level changes and saves.

5.1 Basics

5.1.1 The three kinds of character

Every character has a Roster that says where it can fight:

Two more ideas modify this:

• Guest: a character with Guest ticked is a temporary party member. It always wears its Default Equipment and the player cannot change it, for exactly as long as it is in the party. A guest keeps a fixed loadout, build and Pact.
• Class is fixed. There is no job change. A character keeps its class for the whole game. What changes a character over time is levels, equipment, the progression system (Progression) and, for main characters, Pacts.

The same character, class, stats and abilities work in every battle mode.

5.1.2 First working example: make a class, a hero and put it in the party

1. Archetypes first. In the Studio, 2. Archetypes → Archetype library, pick a hero class archetype such as Paladin and press Create content from it. That creates a class in your project.
2. A hero. 3. Content → New character. Answer the seven steps: Who is it? (name, Hero), Start from (an archetype or an existing character), How does it look?, Which class? (and starting level), What can it do? (abilities by level, with checkboxes), Where does it appear?, Summary and Create.
3. Where does it appear? offers four choices:
   • Not yet: only the asset is made.
   • In the starting party: the hero is part of a new game's party (the Studio updates Party → Starting Members for you).
   • Recruitable in the world: an NPC with a "Join us?" dialog is placed in front of the camera, with a story flag that remembers the recruitment.
   • An enemy in the world: an encounter and a spawner or battle zone.
4. After Create, open the character sheet. Press Test in battle to play a few quick simulated battles and read the win rate.

The same one-click actions are available on any Character asset: right-click it, RPG Saga: Character Actions, then Add to Starting Party, Make Recruitable or Make Enemy. Undo removes what was placed in the level.

5.1.3 The character sheet

Double-click a Character asset to open its sheet: header (portrait, name, role, class, level, valid or not), buttons (Test in battle, Add to party, Make recruitable, Make enemy, Duplicate, Open generic editor) and tabs: General, Look (live preview), Class & stats (the stats at the starting level), Abilities, Equipment and In game. Simple / Advanced shows the essential fields or all of them. Only the fields that make sense for the role are shown (an enemy has no guest flag and no Add to party button, a hero has no loot table). The class and the look can be edited right on the sheet.

Characters and classes that come with the plugin are templates: the sheet shows a Create a copy in the project button, and only your character changes.

5.1.4 The fields of a character

5.1.5 The class

A class (URSEClassData) has:

• a Class Tag (Class.*), the class's identity;
• Stat Growth: for each stat a Base at level 1 and a Per Level value (Base + PerLevel × (Level − 1));
• Affinities (elemental weak, resist, immune, absorb) and Granted Tags (traits such as Trait.Move.Levitate);
• Allowed Equipment Types (Equip.Type.*; a parent tag allows all its children);
• Abilities: each ability with the level it unlocks at;
• an optional Command Menu layout and Growth Plan (see Progression);
• an optional Bag Size.

Stats not listed are zero unless a modifier adds them. Derived stats (Max HP computed from Stamina) follow the foundation's formulas (Game foundation and archetypes). An ability the class lists at level 1 is known from the start; later ones unlock when the character reaches that level.

5.1.6 Levels and experience

A character's level and experience are part of the party's state. The experience needed in total to reach level L is

ExperienceBase × (L − 1) ^ ExperienceExponent + ExperiencePerLevel × (L − 1)

unless an Experience Curve (a float curve of total experience by level) replaces the formula. Defaults: maximum level 99, base 15, exponent 2, per level 0. When a character gains experience, every level reached raises the stats from class growth, raises current HP and MP by the gain in their maximums, and unlocks the class abilities of that level. Experience from a battle is shared among the members still standing. Enemies give EnemyExperienceBase + EnemyExperiencePerLevel × (Level − 1) unless their character sets a reward. All of these are in Project Settings → RPG Saga Engine → Progression.

5.1.7 Party and roster

The party is the list of characters the player controls. Related notions:

• Starting Members: the new-game party (Project Settings → RPG Saga Engine → Party → New Game).
• Formation (classic battles): the members that fight in ATB and turn-based battles, in order. The rest are the reserve. By default the first members that can fight in classic battles fill it, up to ATB Party Size (Battle, default 4). The first change in the party menu makes it explicit. Secondary characters cannot join it.
• Rows: each character is in the front or back row (its default row, or the player's choice). The back row deals and takes less melee physical damage by default (magic and bows are not affected).
• Tactics roster: every member can be deployed in a grid battle, up to the number of deployment tiles.
• Vitals: each member's current resources, KO state and lasting statuses between battles.

The party menu (Formation page) is where the player changes these. In exploration, the visible party follows the leader in formation and the player can switch leader; see Exploration.

5.1.8 Recruitment, guests and leaving

Characters join and leave through story effects, dialogs and quests, or from Blueprint:

• Recruit with the effect Add Member (data) or the node Add Party Member (Blueprint). Main, Secondary and Guest characters all use it. It does nothing if the character is already a member.
• Guests are simply characters marked Guest: add them when the scene needs them and remove them afterwards. They come with their own equipment, fixed for their stay.
• Leave with Remove Member or Remove Party Member and a departure kind:
  • Permanent: the character leaves for good and its equipment returns to the inventory (guests always keep theirs);
  • Parallel Scenario: the character leaves for another storyline and will come back, keeping its equipment.
• Restore Party (Restore Party node) gives full HP and MP, removes KO and statuses, for everyone or one character.
• Set Level can start a recruit at the party's average or highest level plus an offset (a late joiner catching up), or at an exact level.
• Give Experience, Learn Ability and Forget Ability are effects too.

A recruit usually comes from an NPC (ARSENPC) whose interaction runs a dialog with the Add Member effect. Make Recruitable builds exactly that. Which characters are available can depend on story state: use conditions such as Member In Party and Member Not KO in dialogs, quests and puzzles.

5.1.9 NPC types

NPC types are archetypes (URSENPCArchetype) that create an NPC's interaction: Merchant, Quest giver, Recruiter, Innkeeper, Card player, Passer-by, Blacksmith, Elder, Priest and more, in /RPGSagaEngine/Data/Archetypes/NPCs. Pick one in 2. Archetypes → New NPC type or the library, then place the NPC (ARSENPC) in the level. NPC routines and barks are covered in Exploration.

5.1.10 Pacts

A Pact is the customization layer of main characters (who have a fixed class): an original summon system with affinities, abilities that extend the class, and a summon, a temporary unit the player controls, in every battle mode.

What a Pact (URSEPactData) gives its holder:

• Affinities and granted tags (a resistance, a status immunity);
• Abilities learned with Pact points, each with a point cost, an optional prerequisite ability, and an optional Replaces: a Pact ability that upgrades a class ability takes its place while learned;
• a summon ability (always available to the holder) that creates the summon character: a unit with its own class, stats and abilities, at the summoner's level or a level you set.

Rules:

• Only main characters hold Pacts. A character holds one Pact; a Pact is held by one character at a time. Guests keep a fixed loadout.
• Pacts change only outside battle.
• The party obtains Pacts from the story, optional bosses or puzzles.
• The summon costs Resonance (Resource.Resonance): a full bar, consumed. Resonance builds when the holder acts (Resonance On Act, default 15), when it takes a damaging hit (Resonance On Hit, 10) and with the share of max HP lost (Resonance Per Damage Percent, 0.5). The bar's size and its gain rules are the resource's definition in the attribute registry.
• In Tactics the summon stays on the grid for Summon Turns Tactics of its own turns (default 3) on free tiles near the summoner. In ATB it takes the summoner's place for Summon Turns ATB commands (default 3).
• If the summon is defeated before it expires the summoner suffers backlash: Backlash Damage Percent of its max HP (default 25) and optionally a status.
• Winning a battle earns Pact points for each Pact that fought: Points Per Victory (default 10) plus Points Per Enemy Defeated (default 2).

Create a Pact with Advanced tools → Create New → Pact: description, summoned unit and an existing summon ability.

5.2 How it works

5.2.1 From data to a unit in battle

URSECharacterData  ──►  class stat growth at the level
        │                + personal modifiers, affinities, traits
        │                + equipment, Pact, statuses, growth (added by their owners)
        ▼
FRSEAttributeSet (the unit's stats)  ──►  battle unit  ──►  presentation actor

URSECharacterData::InitializeAttributes(Level, OutAttributes) produces the class stats at a level plus the character's personal traits. Equipment, Pacts, statuses and progression add their own sources, aggregated in the order of operations you saw in chapter 3. A battle spawns units from the party's state (level, equipment, resources, Pact, progression) or from an encounter's enemy list, then runs them with no knowledge of actors.

5.2.2 The party state

URSEPartySubsystem owns the party's state for the whole game session (it survives level changes). The state (FRSEPartyState) holds: members, inventory and item containers, money, shop purchases, encounter-rate effects, vitals and equipment per character, the formation and ATB rows, owned Pacts with their holders and progress, learned and forgotten abilities per character, progression (level and experience), the growth state of the progression systems, and each member's battle hotbar order.

The state is read-only to screens: GetState() returns it, and changes go through party commands or through GetStateForApply() for the authority's own systems (battle results, loads, story effects), which marks the Party section changed so the write is never silent. The Party section is saved with the game and replicated in co-op.

Before a battle the director remembers the whole party state (SaveBattleSnapshot); a Retry after defeat puts the party back exactly as it was.

5.2.3 Commands

Party changes are commands on the command bus (Core concepts). The party commands include: Set Formation, Set ATB Row, Move In Formation, Set Battle Menu Order, Cast Field Ability, Use Field Item, Equip Item, Unequip Item, Bind Pact, Unbind Pact, Learn Pact Ability, Buy Item, Sell Item, Rest At Inn, Add Party Member, Remove Party Member, Restore Party, Learn Ability, Set Member Resource, Add Experience, Add Party Experience, Set Level, Give Pact, Award Pact Points, Give Item, Take Item, Add Money and Spend Money. Story-driven ones (adding members, experience, Pacts, items, money) are host-only in co-op; the player's own choices (equipment, formation, Pact binding) are open to every player, subject to the co-op rules (for example Guest Equipment).

5.2.4 Events

Subscribe instead of polling:

• OnMemberResourceChanged (character, resource, old, new) fires when a member's resource changes outside battle (healing items, inns, story effects). Battles report their own on the battle object.
• OnAbilityLearned (character, ability, learned) fires when a character learns or forgets an ability for good (story effects, scrolls, nodes).

5.3 Key classes and assets

5.4 Settings

Per-Pact numbers (Resonance rates, summon turns, backlash) live on the Pact asset. The full lists are in Appendix B.

5.5 Blueprint usage

The party library is under RPG Saga → Party (nodes take a hidden World Context). The most used nodes:

Example 1: a treasure room that recruits a hero and gives the party experience.

1. Event ActorBeginOverlap on your trigger volume.
2. Add Party Member (Character = DA_Char_Wren). Branch on the returned bool: False means she was already in the party.
3. Add Experience To Party (Amount = 200, Only Standing = true).

Example 2: show a level-up banner.

1. In your HUD widget, Event Construct → Get Party Subsystem.
2. Bind Event to On Ability Learned (your custom event shows "Character learned Ability").
3. After awarding experience elsewhere, read the Add Experience return value (Level Up Result): Old Level, New Level and New Abilities.

Example 3: bind a Pact outside battle.

1. Can Bind Pact (Character, Pact). On Ok, Bind Pact.
2. Otherwise show the refusal reason: Not Owned, Not Main Character, Guest Character, Bound To Other Character or In Battle.

Result enums to know: ERSEFormationResult (Ok, NotMember, TacticsOnly, Full, LastActiveMember, InBattle), ERSEEquipResult, ERSEPactBindResult, ERSEPactLearnResult.

In data, the same changes are story effects: Add Member, Remove Member (with a departure kind), Restore Party, Set Level, Give Experience, Learn Ability, Forget Ability, and conditions Member In Party, Member Not KO. The party library has no story effect for giving a Pact: use the node Give Pact in a Custom (Blueprint) effect (override On Execute), or call it from your own graph. See Appendix A.

5.6 C++ usage

Read party state through the subsystem. Send changes as commands so single player, host and guests all work:

#include "Characters/RSEPartySubsystem.h"
#include "Characters/RSEPartyCommands.h"
#include "Commands/RSECommandSubsystem.h"

void RecruitHero(UGameInstance* GameInstance, URSECharacterData* Hero)
{
	if (URSECommandSubsystem* Bus = GameInstance->GetSubsystem<URSECommandSubsystem>())
	{
		FRSECmd_AddPartyMember Command;
		Command.Character = Hero;
		const FRSECommandResult Result = Bus->Submit(Command);
		if (Result.Status != ERSECommandStatus::Applied)
		{
			UE_LOG(LogTemp, Warning, TEXT("Recruit refused (status %d)"), static_cast<int32>(Result.Status));
		}
	}
}

int32 GetHeroLevel(const URSEPartySubsystem& Party, const URSECharacterData& Hero)
{
	return Party.GetState().GetLevel(Hero);
}

Gate on resources and stats with the subsystem:

const float HP = Party->GetMemberResource(Hero, RSEGameplayTags::Resource_HP);
const float MaxHP = Party->GetMemberResourceMax(Hero, RSEGameplayTags::Resource_HP);
const float Attack = Party->GetMemberAttribute(Hero, RSEGameplayTags::Stat_Attack);

Extension points:

• A new party action is a new command struct derived from FRSEPartyStateCommand (override Validate, Execute and GetPermission) or from FRSECommand with a registered handler. Because it is a command, it works in co-op with no RPC code.
• Your own state goes in its own save section, not in the party state (Core concepts).
• Subscribe to OnMemberResourceChanged and OnAbilityLearned (both BlueprintAssignable) or, in C++, to FRSEPartyState::OnAbilityLearned().

5.7 Advanced

• Per-character data you can add. Personal Modifiers take any stat modifier operation (Add, Percent, Multiply, Override, Clamp Min, Clamp Max). Use Override for a scripted boss phase and Clamp Max for a curse.
• Presentation overrides. Presentation Overrides give a character its own look for an ability (a hero from a character pack swinging its own staff), and Attack Presentations with Attack Order (Random or Sequential) turn plain attacks into a combo. Presentation only: rules ignore them.
• Per-character inventory. When the inventory mode is Per Character, Bag Size on the character or class sets each member's bag. See Items, inventory and economy.
• Battle snapshots. SaveBattleSnapshot and RestoreBattleSnapshot give Retry. There is no saving or suspending during a battle.
• Quiet settles. Setup writes (level start effects, rules applied) are not loot. Wrap them in FRSEQuietSettleScope so containers settle without toasts.
• Co-op. In a session, each member is controlled by the companion AI, the host or a guest. Guests change only the equipment and Pacts of the member they play (host rule Guest Equipment). The visible party and delegated commands are in URSEPartyFieldSubsystem.
• Simulating parties. The battle simulator, Balance My Campaign and the Progression Designer build party members with a typical build for the progression system in use, so balance stays valid whichever you choose.
• Debug commands (development builds): RSE.Party.List, RSE.Party.Add <Character>, RSE.Party.Set <Character...>, RSE.Party.Restore [Name], RSE.Party.KO <Name>, RSE.Party.SetHP <Name> <HP>, RSE.Party.GiveExperience <Member|all> <Amount>, RSE.Party.SetLevel <Member|all> <Level>, RSE.Party.Levels.

5.8 Troubleshooting

5.9 See also

• Core concepts
• Game foundation and archetypes
• Progression
• Abilities and statuses
• Items, inventory and economy
• Story, dialog and quests
• Product pages: docs/product/studio.md (New character, character sheet), docs/product/editors-and-wizards.md, docs/product/starter-content.md; design notes docs/design/characters.md, docs/design/pacts.md.

6. Progression

In short: Progression is how your heroes grow. Every game has levels (stats from the class, abilities at their unlock levels). On top you choose one of three systems: Classic (levels only), Classic + Points (the player spends attribute and ability points) or Classic + Growth Board (the player opens nodes on a board). Four optional sources add more ways to learn: equipment mastery, teachers, learning from enemies and use growth. Everything is data, and generators fill it in from your classes.

6.1 Basics

6.1.1 Levels and the three systems

In every system, a class still learns its abilities at their levels and its stats still grow with each level (Characters and party). The other two systems add a layer the player builds.

Points are never lost: a character's available points are computed from its level and its plan (level grants + bonus points − spent points), so an old save, or a plan you rebalanced later, always gets the right amount. Spending is final unless your game allows a respec.

6.1.2 First working example

1. Open the Studio and go to 1. Game foundation → Progression system (or Project Settings → RPG Saga Engine → Progression Systems). Pick a system.
2. Classic + Points: nothing else is needed to try it. The starter hero classes come with a plan, and every other class uses the default plan (Default Plan).
3. Classic + Growth Board: open 2. Archetypes → Growth board, pick a class and press Generate Board. Open the result in the board editor and change anything you like.
4. Press Play, open the party menu, go to the Growth page and spend the points.

If the Growth page does not show, the game is using Classic. Pick another system, or let the player choose at New Game (see below).

6.1.3 Growth Plans

A Growth Plan (URSEGrowthPlan) belongs to a class (Class → Growth Plan) or to one character (Character → Growth Plan). A class without a plan uses Progression Systems → Default Plan. A plan holds:

• Point Grants: points per level for each currency (Progression.Points.*): At Start, Per Level, and Extra At Levels for milestones. The three built-in currencies are Progression.Points.Attribute, .Ability and .Board. Add your own currencies as tags under Progression.Points.
• Attributes (Classic + Points): the key attributes the player may raise. Per attribute: Value Per Point, Cost Per Point, Cost Increase Every N points by Cost Increase, Max Points and Max Points Per Level.
• Ability Catalog (Classic + Points): abilities the player can buy, each with Cost, Currency, Required Level, Prerequisites (abilities from any source) and story Conditions.
• Board: the class's Growth Board.
• Enemy Learning: rules for learning abilities from enemies (see below).

6.1.4 Growth Boards

A board is a set of nodes joined by edges. Each character starts on its start node (per character, per class, or the board's default) and can open any node next to an open one, if it has the points, the level and the story conditions.

Node kinds (ERSEGrowthNodeKind):

A node also has an Id, a Label, a Position, a Tier (0 common to 3 rare, drawn as a ring), a Cost, a Required Level, optional required class tags, a Region, and gate conditions and text.

Regions are themed parts of the board (offense, defense, magic, utility): nodes name their region, and the screen tints it and writes its name. Layout presets (ERSEGrowthLayoutPreset) arrange generated boards:

• Constellation: star clusters linked by long bridges (straight lines);
• Radial Wheel: spokes, rims and a sector per region (arcs);
• Tree / Roots: a trunk forking into a limb per region (curves);
• Grid Lattice: a spine with blocks above and below, right angles only;
• Hex Web: a hexagonal web with honeycomb regions, 60-degree angles;
• Auto: the preset for the class's archetype role (Role Layouts), or Fallback Layout.

Boards are clean by rule: no crossing edges, no overlapping nodes, no edge over a node (Progression Systems → Board → Layout Rules). Generated boards always pass. For boards you lay out yourself, Check Layout and asset validation list the problems.

Scope: Board Scope is Per Class (each class's plan names its board) or Shared (every character uses Shared Board, each from its own start node). Travel Cost Per Step makes each step from where the character stands to the node it opens cost extra points (0 = no cost).

Looks: each board names a Board Style (URSEGrowthBoardStyle): the words on screen (a "Constellation" of "Stars" paid in "Starlight" with an "Ignite" button, or "Roots", "Knots", "Sap" and "Grow", or "Circuit", "Sockets", "Charge" and "Wire"), colors per node kind (following the active UI style by default), node shapes, straight or curved edges, icons, glows and a layered backdrop. Three starter styles ship in /RPGSagaEngine/Data/Growth/Styles. Make your own to give your game its own identity.

The board editor: double-click a board. Add nodes from the right-click menu, draw links between nodes, move nodes freely, and edit the selected node in Details. The Issues tab lists unreachable nodes, missing abilities and other problems. Layout Preset generates the board again from its class in another preset.

In game: the player clicks a node (or presses Confirm) and a small menu opens next to it: Unlock with its cost, Details, Cancel. The member strip shows each member's portrait, name and points. Undo takes any step back for free while the page stays open.

6.1.5 Generators: content from your classes

The generators build balanced, editable progression from a class. The class's stat growth tells them what the class develops (its role), and its ability pool tells them what it can learn.

• Generate Point Tables (Generate Growth Point Tables): key attributes, points per level, prices and caps, and a catalog spread over the levels with learning paths.
• Generate Board (Generate Growth Board): a themed region per key attribute in the chosen layout preset (an entrance junction that forks into two rails, a loop, a side path on each rail, a level gate, the remaining abilities and the region's keystone), bridges between neighbouring regions, and the weakest abilities nearest the start.

They are deterministic: the same class, pool and seed always give the same result, so you can re-run them after changing the class, then edit by hand. The Studio fills the ability pool for you (abilities like the class's own) and uses the archetype's role (Role Emphasis) to favor the right stats. Starting values are in Progression Systems → Generator (Generator Defaults).

6.1.6 Equipment mastery

On a weapon or armor, add Mastery Abilities (an ability and the Points To Master). While the item is equipped the wearer can use those abilities. Every won battle gives mastery points (Mastery Points Per Victory plus Per Enemy, times the item's Mastery Rate). At the goal, the ability is learned for good and stays after the item is removed. The party menu shows the progress ("Riposte: 12 / 30"). The Studio's 3. Content → Weapon with mastery wizard makes such an item.

6.1.7 Teachers

A Teacher (URSETeacherData) lists offers. Each has the ability, the price (money, items, the learner's points), who may learn it (class tags or traits, level) and story conditions. An offer is hidden, or greyed out with the reason when Show When Locked is on, until its conditions hold. A teacher can also offer a respec for money.

• From a dialog: the effect Open Teacher opens the teacher's screen; Teach Ability gives one lesson; the condition Can Learn From Teacher checks the price first.
• The Studio's 3. Content → New teacher wizard makes one.

6.1.8 Learning from enemies

Add Enemy Learning rules to a class's plan, or let a trait do it for any character (Progression Systems → Trait Learning). A rule has a trigger, a chance per battle, an optional list of abilities or ability types, and whether the character must survive and the battle be won:

• Hit By: the character was damaged or affected by the ability.
• Seen: any enemy used it in the battle.

Never Learnable Types keeps attacks and monster-only actions out. Switch the whole feature off with Enable Enemy Learning.

6.1.9 Use growth

Turn on Progression Systems → Enable Use Growth. Abilities then rank up with use. Each ability uses its own Use Growth curve (URSEUseGrowthCurve) or the Default Use Growth curve: ranks reached after a number of battle uses, each with its power (percent of base) and cost (percent of base). The battle menus show the cost the character really pays. Exclude an ability with Exclude From Use Growth (summons, item abilities and story actions are never ranked). The starter set has DA_UseGrowth_Standard.

6.1.10 Respec and free undo

Respec Mode (Progression Systems → Respec):

A respec gives back the points spent on attributes, catalog abilities and board nodes, minus Respec Point Penalty (0.1 by default: 10%, rounded, per currency; 0 gives everything back). The Growth page says exactly how much before the player confirms. Lessons from teachers, mastery and use ranks stay.

Free undo: while the Growth page stays open, the player can take back the last steps (raise, learn, unlock, Auto) for free, one at a time, up to Max Undo Steps (default 50). Closing the page makes them final.

6.1.11 Choosing the system per game, or letting the player choose

The system is part of the rules, so each foundation preset sets its own (Game Foundation → Progression → Progression System). Turn on Player Chooses At New Game to ask the player when a new game starts. The offered systems (New Game Choices, all three when empty), their names and descriptions, and the question text are in the settings.

6.2 How it works

6.2.1 Points, never stored as available

Available(Currency) = LevelGrants(Level) + BonusPoints − SpentPoints

Level grants come from the character's plan (FRSEPointsGrant::GetTotalAt(Level)). Bonus points come from battles, story effects and items. The state per character (FRSECharacterGrowth) records bonus points, spent points (and the share a respec keeps), attribute points, bought abilities, unlocked node ids and the current node (for travel cost), mastery progress, ability use counters, respec count and points lost to respecs. It is saved inside the Party section (FRSEPartyState::Growth), so co-op replicates it with the party. Only the undo journal of the open page is not saved.

6.2.2 What each system adds to a unit

For a battle unit or the party menu, the progression contributes:

• stats as an attribute source (attribute points times Value Per Point, board Stat Boost and Keystone modifiers) in the usual order of operations;
• abilities (bought catalog abilities, board Ability and Passive nodes, mastered or learned abilities) alongside class, equipment and Pact abilities;
• ranks for use growth (power and cost multipliers) applied when the unit is built.

After each won battle, RSEGrowth::ProcessBattle awards battle points (Battle Points rewards, default 5 board points per victory), mastery points, enemy-learned abilities and use counters, and returns the rewards for the results screen.

6.2.3 Commands

Every spend is a party command that works for the host and for guests: Allocate Attribute Points, Buy Growth Ability, Unlock Growth Node, Respec Character, Learn From Teacher, Auto Allocate Growth, Undo Growth Step, Clear Growth Undo, Set Progression System and Award Growth Points. A guest builds only the character it plays (Co-op Rules → Guest Equipment); choosing the system and awarding points are host-only. Guests (temporary members) keep a fixed build.

6.2.4 Automatic allocation

Characters nobody builds by hand (AI-controlled members, autoplay) spend their points with the Allocation Policy. After each battle and level-up, AI-controlled members spend automatically (Auto Allocate AI Controlled). The Auto button on the Growth page uses the policy too. The battle simulator, Balance My Campaign and the Progression Designer simulate party members with a typical build for the system in use (every point spent by the policy, battle points estimated with Simulated Victories Per Level and Simulated Enemies Per Victory), so balance stays valid whichever system you choose.

6.2.5 The Progression Designer

"Does my game have the pace I want?" The Progression Designer plays your whole campaign in the battle simulator with a standard party and shows where the party ends up under- or over-leveled, where battles drag on, where players would have to grind and where battles are too easy. An advisor proposes values (experience curve, enemy experience, enemy and class stat growth) and applies them only when you confirm, with undo.

1. Make one progression zone per chapter (URSEProgressionZoneData): enemy level range, expected battles, target entry and exit levels, regular encounters, key battles.
2. Make a campaign (URSECampaignProgressionData): the zones in order, the standard party, targets and simulation settings.
3. Open RPG Saga Engine → Configurator → Tools → Progression Designer, pick the campaign, press Run projection, read the charts, then Run advisor. Tick the recommendations to keep and press Apply selected.

Zones also scale enemy levels in the game itself: a regular battle gets enemies at the party's level (plus offsets) inside the zone's range. Those rules (Scale Enemy Levels, Party Level Source, Enemy Level Offset, Overlevel Bias, Enemy Level Variance) are on the Progression page. The starter set includes a finished example, DA_Campaign_Starter. Full details are in docs/product/progression-designer.md.

6.3 Key classes and assets

6.4 Settings

Project Settings → RPG Saga Engine → Progression Systems (a rules-profile section). The properties that matter most, with their defaults:

Related pages: Progression (maximum level, experience curve, enemy levels), Growth UI (the Growth page and board screen), Progression Designer (Power Samples, default 20) and, in the editor, Progression Tools (value ranges the AI schema uses). Full lists are in Appendix B.

Data fields: Class / Character → Growth Plan; Ability → Use Growth, Exclude From Use Growth; Equipment → Mastery Abilities, Mastery Rate.

6.5 Blueprint usage

All nodes are in the category RPG Saga → Progression (hidden World Context). Reading:

Get Progression System, Get Available Growth Points (Character, Currency), Get Growth Currencies, Get Allocated Attribute Points, Is Growth Node Unlocked, Get Growth Node Cost, Get Growth Plan, Get Growth Board, Get Mastery Points, Get Ability Rank, Get Growth Options, Can Learn From Teacher, Describe Growth Result.

Changing (each returns a Growth Result: Ok, Invalid Arguments, Not Member, Wrong System, Not Available, Not Enough Points, Cap Reached, Missing Prerequisite, Level Too Low, Conditions Not Met, Already Owned, Not Adjacent, Respec Not Allowed, Missing Item, Not Enough Money, Nothing To Reset, In Battle, Guest Character):

Allocate Attribute Points, Buy Growth Ability, Unlock Growth Node, Respec Character, Learn From Teacher, Auto Allocate Growth, Set Progression System, Award Growth Points.

Editor tools (category RPG Saga → Progression → Generator): Get Growth Generator Defaults, Generate Growth Point Tables, Generate Growth Board, Get Growth Board Problems, plus fill-level estimates.

Example 1: give board points as a quest reward.

1. In your reward graph, Award Growth Points (Character = DA_Char_Hero, Currency = Progression.Points.Board, Amount = 3).
2. Branch on the result: anything other than Ok can be reported with Describe Growth Result.

In data, use the effect Award Growth Points in the quest's reward list instead.

Example 2: a custom "Spend all" button.

1. Auto Allocate Growth (Character).
2. Get Available Growth Points (Character, Currency = Progression.Points.Attribute) to refresh the label.

Story effects and conditions (data): Open Teacher, Teach Ability, Award Growth Points; Progression System Is, Has Growth Node, Can Learn From Teacher.

6.6 C++ usage

Read points with the RSEGrowth rules, and spend them through the library, which sends the matching party command (so it works for the host and for guests):

#include "Growth/RSEGrowth.h"
#include "Growth/RSEGrowthTags.h"
#include "Growth/RSEBlueprintLibrary_Growth.h"
#include "Characters/RSEPartySubsystem.h"
#include "Core/RSEGameplayTags.h"

void SpendOnAttack(UGameInstance* GI, const URSECharacterData& Hero)
{
	URSEPartySubsystem* Party = GI->GetSubsystem<URSEPartySubsystem>();
	const int32 Points = RSEGrowth::GetAvailablePoints(
		Party->GetState(), Hero, RSEGrowthTags::Points_Attribute);
	if (Points <= 0)
	{
		return;
	}
	// Sends the Allocate Attribute Points command and returns its result:
	URSEBlueprintLibrary_Growth::AllocateAttributePoints(GI, &Hero, RSEGameplayTags::Stat_Attack, 1);
}

A custom allocation policy (deterministic, so simulations stay reproducible):

UCLASS()
class UMyPolicy : public URSEGrowthAllocationPolicy
{
	GENERATED_BODY()
public:
	virtual int32 ChooseOption_Implementation(const URSECharacterData* Character, int32 Level,
		const TArray<FRSEGrowthOption>& Options) const override
	{
		// Prefer abilities over attributes; -1 stops spending.
		for (int32 Index = 0; Index < Options.Num(); ++Index)
		{
			if (Options[Index].Kind == ERSEGrowthOptionKind::Ability) { return Index; }
		}
		return Options.IsEmpty() ? -1 : 0;
	}
};

Set it in Progression Systems → Allocation Policy Class. The same class works as a Blueprint child (override Choose Option).

6.7 Advanced

• Your own currencies. Add a tag under Progression.Points (for example Progression.Points.Mastery), give it a Point Grant in a plan, and price nodes or catalog entries in it. Battle rewards (Battle Points) can award it, optionally only for one system (Only For System).
• Rules profiles. The system is part of the rules, so a profile can switch it per chapter or per game mode. Progression Systems is a profile section.
• Importing AI-written progression. The progression schema (rse.progression/1) describes a class's plan, board, mastery items, teachers and enemy learning in one JSON file. Configurator → Tools → Content Import → Export AI pack writes a prompt generated from your project; the importer checks the answer, shows a dry run and never deletes anything or changes the plugin's own assets. See docs/product/progression-ai-schema.md and Editor tools.
• Command line. UnrealEditor-Cmd <Project>.uproject -run=RSEProgression -Campaign=<asset> [-Advisor] [-Out=<dir>] [-Set=ExperienceBase=12,...] runs the Progression Designer headless (the -Set option projects what-if values without changing anything). -run=RSEContentImport -Source=<folder> [-DryRun] imports progression files.
• Performance. Boards are plain data. The board screen reads the style and the node list only while the Growth page is open.
• Networking. The state lives in the Party section; commands are validated by the host. Undo is also checked by the host.
• Balance. After changing a plan, re-run the Progression Designer: the power curves show whether a system pulls ahead too fast. Keep gates for story beats (a flag) and pacing (a level) so players cannot rush a branch.

6.8 Troubleshooting

6.9 See also

• Characters and party
• Game foundation and archetypes
• Abilities and statuses
• Items, inventory and economy
• Battle fundamentals for the battle simulator and Balance My Campaign
• Product pages: docs/product/progression.md, docs/product/progression-designer.md, docs/product/progression-ai-schema.md; design notes docs/design/progression-systems.md, docs/design/progression-designer.md.

7. Abilities and statuses

In short: An ability is anything a unit can do in battle: a sword strike, a spell, a heal, a thrown bomb. A status is a lasting effect on a unit: poison, haste, a shield, charm. Both are data assets. One ability works in every battle mode, with its own rules per mode. You build new content by filling fields and picking effects, not by writing code.

7.1 Basics

7.1.1 The words

7.1.2 Make your first ability

1. Open RPG Saga Engine → Studio → Content → New ability, or right-click a folder in the Content Browser and choose RPG Saga → Ability. The wizard walks through the same fields as the asset, and its last step shows the ability in action.
2. Give it a Description, an Ability Type tag (Ability.Type.Attack, Skill, Magic or Action: this decides which command of the battle menu lists it), an optional Element, and a Target Filter (enemies, allies, allies and self, self, all units).
3. Under Costs add what it consumes (for example Resource.MP, 8). Under Item Costs you can add ammunition (1 Arrow).
4. Under Effects press + and pick Damage. Choose the Kind (Physical, Magical or Fixed), the Power, and whether it can miss or crit. Add Apply Status next to it if you want, with a Chance.
5. Fill the rules for the modes you use. A grid battle reads Tactics Rules (range, area, Action Point cost), a classic battle reads ATB Rules (scope, row behavior, charge time). The turn-based mode uses the ATB rules too.
6. Give the ability to someone: add it to a class's ability list, to a piece of equipment's Granted Abilities, to a Pact, or teach it with a story effect (see Learning and forgetting abilities).
7. Press Test ability (below) to measure it without playing.

The plugin ships a full set of examples in /RPGSagaEngine/Data/Abilities/: DA_Ability_Strike, DA_Ability_Fire (area, elemental, costs MP), DA_Ability_Cure, DA_Ability_Raise (a revive), DA_Ability_ShieldBash (a use condition), DA_Ability_PoisonDart (a status), DA_Ability_TK_Overwatch (a reaction) and many more. Open them to see how a finished ability looks.

7.1.3 Test an ability without playing

Every ability sheet has a Test & preview tab and a Test ability button. The Studio wizard shows the same tools.

1. Pick the battle mode (Grid, Live, ATB or Turn), the caster (any character or an archetype) and the targets (a preset: one enemy, three enemies, an ally and two enemies, a boss, three allies).
2. Set the level, the seed and the number of runs. For abilities usable only at low HP, set the caster's HP %.
3. Press Test ability. Each run uses a fresh headless mini battle, so hundreds of runs take about a second. The report lists, per unit, how often it was affected, hits, misses, crits, damage and healing per use (lowest, highest, average), the real chance each status landed, what one use costs, the area it covers and a Step by step trace of the first use.
4. Copy as text puts the report on the clipboard.

The same seed always gives the same numbers, so you can change one value and compare. Above the table a 3D preview plays the ability's presentation (animation, effects, projectile, floating numbers) in a small private world, with Loop, speed and camera choices. Defaults for both are in Project Settings → RPG Saga Engine → Ability Test and Studio → Ability Preview.

7.2 How it works

An ability's life, in every battle mode:

1. A unit has a list of abilities, gathered from its class, equipment, Pact and the abilities it learned.
2. When the player (or the AI) picks one, the battle checks the use conditions, the costs (resources, item costs, Action Points in grid battles) and the mode's own rules (range, scope, ready state). A refusal carries a reason that the menu shows.
3. The battle resolves each effect in the Effects array. Effects that work per target run once per affected unit. Effects that move the user or change the field (leap, dash, teleport, zones, summons) run once per use before the per-target ones.
4. Every change becomes a battle event (damage dealt, status applied, unit moved, reaction triggered...). The presentation layer listens to those events to play animations and numbers. The rules never wait for the presentation.
5. After the action, queued reactions resolve (a counterattack, a guard), up to a depth limit that stops endless chains.

All randomness comes from one seeded stream per battle. The same seed and the same commands always give the same battle, in the editor, in the simulator and over the network.

7.2.1 Per-mode rules

Each mode block has a Power Multiplier so you can balance one mode without touching the others.

Area shapes for Tactics are Single, Diamond, Cross, Line, Cone, Ring, Rectangle and Mask (a hand-drawn pattern). Power can fall off with distance from the center, and an Arc trajectory flies over lower obstacles.

7.2.2 Effects you can pick

Pick effects in the Effects list; the display names below are what you see in the picker.

Position effects have a documented meaning in the classic modes too. A knockback becomes a row change, a swap exchanges rows, a spawned wall does nothing. The picker's tooltip and the validation tell you when an effect has no meaning in a mode.

7.2.3 Statuses

A status (URSEStatusData) is data too. The main fields:

• Status Tag: its identity (Status.Poison). Tags let abilities, conditions and the AI refer to it.
• Duration Turns: counted in the bearer's own turns. 0 means until removed.
• Stacking: Refresh restarts the duration, Ignore keeps the first application.
• Immunity Tag: a unit with this tag (from equipment, a class trait, a Pact) cannot receive the status.
• Persists After Battle and Removed By Damage.
• While Active: stat Modifiers, element Affinities and Granted Tags. Tags such as Status.Block.Move, Status.Block.Act and Status.Block.Turn stop moving, acting or the whole turn.
• Periodic: Periodic Timing (turn start or turn end) and a percent of max HP. Positive damages (poison), negative heals (regeneration).
• Toolkit: Polarity (Neutral, Buff, Debuff), Dispellable, Shield Absorbs (None, All, Physical, Magical) and Taunt.
• AI Value Scale: how much the AI values applying the status. 0 ignores it, 2 doubles it.
• Behaviors (control): see below.

Stat modifiers always combine in the same order: base, add, percent, multiply, override, clamp, then the attribute's own bounds. The result never depends on which status or item came first.

7.2.4 Control statuses

A status can change who decides what its bearer does. Add a Behavior under Control → Behaviors:

They work in every battle mode and the AI follows them. A party member under control is played by the AI until the status ends (by duration, a cure, damage if Removed By Damage is on, the unit falling, or the battle's end). When the last fighter of a side is charmed away, that side has lost. The starter content includes Confuse, Charm and Frenzy statuses with example abilities (Bewilder, Enthrall, Incite).

7.2.5 Use conditions

Use Conditions is a list of checks on the user. All must hold in every mode. The menus show a failed ability disabled with a reason: the ability's Use Conditions Text when filled in, otherwise the failing condition's own text. The AI and the simulator never choose a disabled ability.

Conditions about "the target" cannot go here, because no target is chosen yet. Validation reports them.

7.2.6 Item costs and ammunition

Item Costs consume items from the team's items on every use. The menu shows "1 Arrow (x12)". Without enough items the ability is disabled. Enemies ignore item costs unless Enemies Pay Item Costs is on in Ability Toolkit.

7.2.7 Reactions and passives

An ability with Passive ticked never appears in menus. Two lists make it useful:

• Reactions: each URSEAbilityReaction has a Trigger (Damage Taken, Attacked, Ally Damaged, Enemy Moved, Defeated, Kill, Turn Start, Turn End), a Source (who may trigger it), a Response ability, an Aim, a Chance, Max Per Turn and more. Enemy Moved is overwatch, grid only.
• Passive Modifiers: stat modifiers, affinities and tags applied while their conditions hold.

Reactions are queued and resolved after the action that caused them, up to Max Reaction Depth (default 1, so a counter is not countered).

7.2.8 Tier families

A URSEAbilityTierFamily asset lists abilities from the base tier up. The battle menu shows the family as one entry, and choosing it opens the tiers the unit knows, each with its own cost and power. A new family is one data asset.

7.2.9 Learning and forgetting abilities

A character can learn an ability for good outside its class progression. Learned abilities appear after class, equipment and Pact abilities, in every battle mode, and are saved.

• Learn Ability and Forget Ability are story effects (dialog choices, quest rewards, puzzles, interactions). The learner can be one character, every member, or members whose tags match.
• A manual is a consumable whose use ability has the effect Learn Ability, is usable in the field and targets an ally. See DA_Item_ManualBerserkSlash in /RPGSagaEngine/Data/Items/.

7.2.10 Presentation and action commands

How an ability looks (animation, effects, camera, sounds) is separate from what it does. The Presentation block points to a timeline asset; empty means a default from the approach (melee, ranged, in place) and the moment (normal or super move). See Camera and battle presentation.

An ability can also ask for a timed button press (Action Command): a ring closes and a Good or Perfect press adds a bonus, and enemy attacks can be blocked with a timed press. The windows and bonuses are on the ability; the global rules are in Project Settings → RPG Saga Engine → Action Commands.

7.3 Key classes and assets

7.4 Settings

Project Settings → RPG Saga Engine:

The full lists are in Appendix B. The asset types are in Appendix D.

7.5 Blueprint usage

Teach an ability from a Blueprint:

1. Event (for example On Interact) → Learn Ability (Character = DA_Char_Hero, Ability = DA_Ability_Fire).
2. Branch on the returned result to show a message if the character already knew it.

Related nodes in the party library (category RPG Saga | Party | Abilities): Forget Ability, Has Learned Ability, Get Learned Abilities, Get Member Abilities. The party subsystem has an On Ability Learned event.

Run the headless test from a script:

1. Make Ability Test Request (Ability, Mode tag).
2. Adjust the request (caster, targets, runs, seed).
3. Run Ability Test → Ability Test Report To Text → Print String.

Write a custom effect:

1. Create a Blueprint class with parent Custom (Blueprint) (URSEEffect_Custom).
2. Override On Apply (Battle, Source Id, Target Id, Target Tile, Power Multiplier). Inside, call the battle's nodes: Deal Damage, Heal Unit, Change Resource, Apply Status, Remove Statuses, Shift Turn.
3. Draw random numbers only with Roll Int and Roll Percent. They come from the battle's stream, so replays and the simulator stay exact.
4. Override Preview Damage to give the AI and the damage forecast an expected value. Without it the AI sees no value in the effect.
5. Tick Once Per Use if the effect should run once instead of per target.
6. Add your class to an ability's Effects list.

A custom reaction condition is a Blueprint subclass of Reaction that overrides Can Trigger. A custom passive overrides Is Active For. A custom use condition is a subclass of AI Condition: override Is Met and Get Requirement Text.

The full node list is in Appendix A.

7.6 C++ usage

A new effect in C++ is a subclass of URSEAbilityEffect. Override Apply and, so the AI can see it, AddToPreview.

UCLASS(meta = (DisplayName = "Drain Morale"))
class UMyEffect_DrainMorale : public URSEAbilityEffect
{
    GENERATED_BODY()
public:
    UPROPERTY(EditAnywhere, Category = "Morale", meta = (ClampMin = "0"))
    float Amount = 10.f;

    virtual void Apply(const FRSEAbilityContext& Context, int32 TargetId) const override
    {
        Context.Battle->ChangeResource(Context.SourceId, TargetId, MoraleTag, -Amount);
    }

    virtual bool AppliesOncePerUse() const override { return false; }

private:
    FGameplayTag MoraleTag;
};

The picker lists every concrete subclass with its DisplayName, so no registration is needed. Useful overrides: AddToPreview (what the AI and the forecast read), CheckRequirement (extra conditions beyond costs), ApplyInField (what the effect does from the party menu), AppliesOncePerUse, DescribeEffect (tooltip text) and ValidateInAbility (editor validation).

Run the headless ability test from C++:

FRSEAbilityTestRequest Request = URSEAbilityTestLibrary::MakeAbilityTestRequest(Ability, ModeTag);
Request.Runs = 200;
const FRSEAbilityTestReport Report = URSEAbilityTestLibrary::RunAbilityTest(Request);
UE_LOG(LogTemp, Log, TEXT("%s"), *URSEAbilityTestLibrary::AbilityTestReportToText(Report));

7.7 Advanced

7.7.1 Gameplay Ability System bridge (RSEGAS)

Teams that already use Unreal's Gameplay Ability System can keep it. The RSEGAS module is a bridge: the battle stays the source of truth for hits, damage and turns, and the bridge mirrors values in and out. RSECore never uses GAS types, and nothing happens until an actor has the component.

Setup:

1. Create an RSE GAS Attribute Map data asset. Add one row per value the battle should read or write: the RSE tag (Stat.Attack, Resource.HP), the GAS attribute, a Direction (In, Out or Both) and a Scale. With the included RSE GAS Sample Attribute Set, press Fill Sample Rows.
2. Optionally create an RSE GAS Status Map (statuses to loose tags and effects) and an RSE GAS Ability Map (an event tag or ability tags sent when an RSE ability is used).
3. On your character Blueprint, add the RSE GAS Bridge component. Set Character (the RSE character data asset) and the maps. If the Ability System Component lives elsewhere, call Set Ability System.

What flows:

• In: stats and resources at battle start, outside attribute changes while the battle runs, GAS tags to statuses.
• Out: resource changes as instant Gameplay Effects, statuses as tags and optional effects, battle events as Gameplay Events (tags such as Event.RSE.Damaged and Event.RSE.AbilityUsed), and with Restore After Battle the attributes return to their old values.

The component's options (Supply Stats, Apply Results To GAS, Mirror Statuses, Forward Events, Forward External Changes, Restore After Battle, Priority) are all on by default except Restore After Battle.

RSE abilities can also run your GAS content. In an ability's Effects list add Apply Gameplay Effect (GAS) or Activate Gameplay Ability (GAS). In a presentation timeline add the Gameplay Cue (GAS) step. These do nothing on units without a bridge or on a machine that is not the authority.

Export to GAS (editor, one way) generates Gameplay Effects and Gameplay Abilities from your statuses and abilities (RPG Saga Engine → Advanced tools → Content → Export to GAS..., or the RSEGASExport commandlet). Always start with a dry run. The report lists what GAS cannot hold (grid rules, reactions, control behaviors...). Defaults live in Project Settings → RPG Saga Engine → GAS Export.

7.7.2 Content from spreadsheets and AI

Abilities, statuses and their use conditions can be created and updated from spreadsheets (Configurator → Tools → Content Import), and they appear in the AI prompt packs. The effect type in a sheet is the display name without spaces, for example KnockbackPull(Distance=2). See Editor tools.

7.7.3 Network and performance notes

• The battle runs on the host; effects, statuses and reactions are deterministic, so guests see the same results (Co-op and online).
• Effects run on the authority only. GAS effects follow the same rule.
• Keep AddToPreview cheap. The AI calls it for every ability and target it considers.

7.8 Troubleshooting

7.9 See also

• Battle fundamentals, Grid Tactics and ATB and turn-based for the rules each mode adds.
• Items, inventory and economy for consumables whose use is an ability.
• Enemy AI and adaptive difficulty for how the AI values abilities and statuses.
• Product pages: docs/product/abilities.md, docs/product/gas-interop.md.

8. Items, inventory and economy

In short: One item system serves every battle mode and exploration. Items are data assets in four kinds (consumables, equipment, key items, documents). The party carries them in a shared grid or in per-character bags, and money, shops, inns, chests and loot tables are built from the same data and the same Conditions and Effects language as dialogs and quests.

8.1 Basics

8.1.1 The four kinds of item

All kinds share one asset type, so there is one ID space for saves and one place to look items up.

Fields every item has (URSEItemData):

• Description and an Icon (or Item Mesh, which the icon tools frame for you).
• Max Stack (0 means the project default, 99).
• Buy Price, Sell Price Override (-1 = automatic) and Sellable. A price of 0 means the item has no value: a shop can only sell it with a price override, and the party cannot sell it.
• Grid Size (cells), Rarity (Item.Rarity.* tag), Category (Item.Category.* tag) and Weight for the grid inventory.

8.1.2 Make your first consumable

1. RPG Saga Engine → Studio → Content → New item (pick a family such as potion, status cure or bomb), or make the data asset by hand in the Content Browser (Miscellaneous → Data Asset, class RSEConsumableData).
2. Set the Use Ability. Either pick an existing ability (a heal, a bomb) or make a new one. The ability's Tactics Rules give the item its range, area and Action Point cost in grid battles, and its ATB Rules give it a scope in classic battles. That is how a bomb has an area on the grid and hits a row in ATB.
3. Tick Usable In Battle (default on). To allow use from the party menu, open the use ability's Field Rules and tick Usable In Field.
4. Set Buy Price. Optionally add the item to a shop and a loot table.

The plugin ships examples in /RPGSagaEngine/Data/Items/: DA_Item_Potion, DA_Item_Ether, DA_Item_Bomb, DA_Item_Antidote, DA_Item_RevivalPlume, DA_Item_ManualBerserkSlash (teaches an ability), DA_Key_SpireKey (a key item), DA_Doc_FieldGuide (a document) and a full set of DA_Equip_* equipment.

8.1.3 Equipment

An equipment item has a Slot Type (Equip.Slot.*) and an Equipment Type (Equip.Type.*). Classes list the types they may use. While worn it gives:

• Modifiers (stat modifiers), Affinities (element weakness, resistance, immunity, absorb) and Granted Tags (traits such as status immunities, and the type tag itself, so a shield lets its wearer use shield abilities);
• Granted Abilities: abilities usable only while it is worn.

Other fields: Two Handed (weapons that also occupy the off-hand slot), Mastery Abilities and Mastery Rate (the item teaches an ability for good after enough use), Bag Size Bonus and Carry Capacity Bonus (a backpack in the per-character inventory), Appearance Part and Weapon Presentation (how it looks on the body, see Weapons), and Action Weapon for action battles.

The slots a character has are a list in Project Settings → RPG Saga Engine → Items → Equipment Slots. Each slot has an id (Weapon, OffHand, Accessory1...), a name, the slot type it accepts, and optional body part and attach settings for the paperdoll. You can start from an Equipment Slot Set preset (use Apply To Project), or let a Game Foundation preset write the list for you.

Equipment results are explicit. Equip returns Ok, Unknown Slot, Wrong Slot, Class Cannot Use, Not In Inventory, Locked (a guest's fixed equipment) or Blocked By Two Handed.

8.1.4 Documents and key items

A document shows its pages when the player reads it from the inventory. A key item is used on the thing in front of the player ("Use on door") or combined with another key item. The puzzles that react to them are in Exploration.

8.1.5 Money, shops, inns and chests

• Money is one currency with the name, symbol and format you choose.
• A shop (URSEShopData) lists stock. Each entry can override the price, limit the quantity forever, and appear only while story conditions hold ("after the smith joined").
• An inn restores the party for a price.
• A chest is an actor with items, money, an optional key and an "opened" flag saved with the story.
• Loot tables (URSELootTable) give enemies and encounters their drops.

Shops, loot tables and chests are plain data and actors, described below. A shop is opened by the Open Shop story effect, for example from an NPC's dialog.

8.2 How it works

8.2.1 The flow

Items (data) ──► Inventory (RSECore: stacks, grid layouts, containers)
                  │              │
 Party state ◄────┘              └──► Loot distribution rule ──► who receives what
 (money, equipment, shop stock)
Economy rules (RSECore) ──► Shop / Inn / Chest / Battle loot
Screens (RSE): inventory, shop, chest, reward feed

• RSECore holds the rules: stacks, equipment checks, prices, buying and selling, loot rolls, distribution. They are headless and tested.
• RSE holds the screens (inventory board, shop, party menu) and the world actors (chest, stash point).
• Every inventory change is a serializable command (FRSEInventoryCommand): Move In Grid, Equip, Unequip, Use Item, Sort Container, Discard, Transfer, Auto Distribute, Give Money. The host validates and applies it. That is why co-op works without extra code.

8.2.2 Inventory modes

Project Settings → RPG Saga Engine → Inventory Rules → Mode:

The mode can change at any time, in either direction. A profile or a Game Foundation preset can set it. Per Character to Shared merges every bag, the stash and the pending loot. Shared to Per Character distributes the items by the distribution rule (Migration: Distribute) or puts everything in the stash (All To Stash). Equipment worn never moves. Nothing is lost.

In Per Character, loot that nobody can carry waits in a Pending Loot tab until taken or distributed (Overflow), and you can add weight: Use Weight gives each member a Carry Capacity (base plus a stat plus equipment), with Overweight Rule Display Only or Block Adding.

8.2.3 Who receives loot

Everything the party gains passes one settle step with a source (battle, chest, pickup, quest, shop, story). A distribution rule only ranks the receivers. The framework fills the best receiver, then the others, then the stash, then the Overflow rule. Built-in rules:

A different rule can be set globally, per chest (Loot Rule) or per encounter. You can write your own (see Advanced).

8.2.4 Battle loot and money

On victory the rules roll the loot table of every defeated enemy, in battle order, then the encounter's own loot (Encounter Loot) and its Reward Items. Each entry rolls on its own, so several can drop. The dice come from a stream derived from the battle's seed, so the same battle always drops the same things. The simulator rolls loot exactly like the game.

One battle never gives more money than Battle Money Cap allows for the level of its strongest defeated enemy (a curve you edit). This keeps a late boss's loot table from paying a fortune when used on an early enemy.

8.3 Key classes and assets

8.4 Settings

Project Settings → RPG Saga Engine:

The complete lists are in Appendix B.

8.5 Blueprint usage

All nodes below are in the RPG Saga | Items and RPG Saga | Economy categories.

Give the player an item when an NPC dialog ends:

1. In the dialog, add the story effect Give Item (Item = DA_Item_Potion, Count = 3). No Blueprint needed. Use the Has Item and Take Item conditions and effects the same way.
2. From Blueprint instead: Event → Give Item (Item = DA_Item_Potion, Count = 3). The node returns how many were added, capped by the stack limit.

Check a key item before opening a door:

1. Has Item (Item = DA_Key_SpireKey) → Branch.
2. True: Take Item (if the key is used up), then open the door.

Open a shop and buy:

1. Dialog effect Open Shop (Shop = DA_Shop_Starter_Z1). The screen opens after the running dialog ends.
2. Scripted purchases: Can Buy (Shop, Entry Index) → Buy (Shop, Entry Index, Count). Both return a result: Ok, Not Enough Money, Out Of Stock, Unavailable, Inventory Full, Not Sellable or Not Enough Items. Get Buy Price, Get Stock Left and Get Max Buy Count feed a custom shop UI.

Money and inns: Get Money, Add Money, Spend Money, Get Inn Cost and Rest At Inn. In story data use the Has Money condition and the Give Money, Take Money and Rest At Inn effects. Gate the inn choice with Has Money.

Equipment: the party library offers Get Equipment, Get Equipped Item, Can Equip, Equip, Unequip, Get Equip Candidates and Preview Equip (the stats before and after).

React to changes: bind to the inventory subsystem's On Command Applied.

For a full list see Appendix A.

8.6 C++ usage

#include "Items/RSEBlueprintLibrary_Items.h"

// Reward the player and report what happened.
const int32 Added = URSEBlueprintLibrary_Items::GiveItem(this, PotionAsset, 3);

if (URSEBlueprintLibrary_Items::HasItem(this, KeyAsset))
{
    URSEBlueprintLibrary_Items::TakeItem(this, KeyAsset, 1);
}

const ERSEShopResult Result = URSEBlueprintLibrary_Items::Buy(this, ShopAsset, /*EntryIndex*/ 0, /*Count*/ 1);

Equipment changes go through the party library (URSEBlueprintLibrary_Party::Equip, which returns ERSEEquipResult). If you write your own inventory screen, send FRSEInventoryCommand structs through URSEInventorySubsystem::SubmitCommand. Never write the party state directly.

Extension points:

• URSELootDistributionRule: override RankTargets (a BlueprintNativeEvent) to decide who receives items.
• URSEInventoryPermissionPolicy: override CanIssue, CanChangeEquipment, CanIssuePartyCommand and CanUseContainer.
• A new item kind of behavior: make a consumable whose use ability has a Custom effect.

8.7 Advanced

8.7.1 Grid containers and stash tabs

The shared inventory is drawn as a grid. Stash Tabs is a list of container definitions (id, name, icon, grid size, filter). An item appears in the first tab whose filter accepts it, so every item always has a place. A filter matches item kinds and a gameplay tag query over rarity, category, slot and equipment type. A container with Max Height 0 grows as needed. A bounded container (a chest) leaves items it cannot fit unplaced. Sort Order lists the keys auto-sort compares (kind, rarity, category, equip slot, size, name).

8.7.2 Writing a distribution rule

Create a Blueprint class derived from RSE Loot Distribution Rule, override Rank Targets, and pick it in Inventory Rules → Distribution Rule. The input is the party state and a query (the items and their source). The output is a ranked list of containers. Do not fill containers yourself. The framework fills them in order and handles overflow.

8.7.3 Co-op

Each inventory change is a serializable command that the host validates and applies. Pickups To Picker In Coop sends what a player picks up to that player's member first. With Per Character inventory and the default policy, a guest may take items only from the bag of the member they play (see Co-op and online).

8.7.4 Save and migration

Inventory state, grid layouts, shop purchases and money are part of the party save section, so old saves load into the mode in use and distribute as described above. See Save and load.

8.7.5 Content from spreadsheets

Items, shops and loot tables import from spreadsheets (Configurator → Tools → Content Import) and appear in the AI prompt packs. See Editor tools.

8.7.6 Performance

The inventory board draws without per-frame rebuilds. It refreshes when a command is applied. Item icons can be a live 3D preview (Inventory UI settings, CVars RSE.Inventory.LivePreview, RSE.Inventory.PreviewScale, RSE.Inventory.PreviewRate). See Appendix C.

8.7.7 Development commands

In development builds: RSE.Items.Give, RSE.Items.List, RSE.Items.Reset, RSE.Economy.Money, RSE.Economy.OpenShop, RSE.Economy.Rest and RSE.Inventory.ForceStashAccess (stash everywhere). Appendix C lists the arguments.

8.8 Troubleshooting

8.9 See also

• Abilities and statuses for use abilities, manuals and item costs.
• Battle fundamentals for rewards and loot after a fight.
• Characters and party for equipment on characters and the party menu.
• Save and load and Co-op and online.
• Product pages: docs/product/starter-content.md, docs/product/faq.md.

9. Battle fundamentals

In short: Every fight in the plugin is an encounter: a data asset that names the battle mode, the enemies, the rules, the objectives and the rewards. The modes (grid Tactics, Free Tactics, ATB, turn-based, Action) share one core: units, abilities, damage, statuses, victory and defeat, rewards. This chapter covers that shared core, how encounters start, the battle mode override, battle sites, and the headless battle simulator that tests it all without graphics.

9.1 Basics

9.1.1 The words

9.1.2 Make your first encounter

1. Open RPG Saga Engine → Studio → World → New battle (see the Studio). Pick a battle mode, add enemies from your library, set levels and rewards, and let the wizard place the battle in the open level.
2. Or create the asset by hand: Miscellaneous → Data Asset → RSEEncounterData. Set Battle Mode, add entries to Enemies, and (for grid battles) lay them out with the Encounter Layout mode (below).
3. Put a trigger in the level: an RSE Encounter Trigger volume that points at the director (or at an RSE Encounter Site). Walk into it in Play.
4. Check the encounter with the headless simulator (below) before you tune it by playing.

The starter set in /RPGSagaEngine/Data/Encounters/ has a whole campaign of examples (DA_Encounter_Starter_Z1_Pack, _Elite, _Key, _Boss and so on for each zone).

9.1.3 What an encounter holds

Encounters hold no tile coordinates for the grid itself. The grid belongs to the map (see Grid Tactics).

9.1.4 Objectives

Victory and defeat conditions are small objects. The built-in ones:

• Team Defeated: every unit of a team is down.
• Character Defeated: one named character falls (a boss to kill, an escort to protect).
• Turns Elapsed: a team has taken a number of turns (survive, or a time limit).
• Team Reaches Tiles: any unit of a team stands on given tiles (reach the exit). Grid battles only.

Each has a Description the HUD shows as the objective text. Any of the victory conditions met means a win. A new condition is a Blueprint or C++ subclass of URSEBattleCondition that overrides IsMet.

9.1.5 Encounter Layout (grid and classic stages)

Instead of typing coordinates, use the Encounter Layout mode:

1. Select a Tactics Zone (bake its grid first) or an ATB Stage.
2. Press the Encounter Layout toolbar button, or choose RPG Saga Engine → Advanced tools → Encounter Layout Mode.
3. Pick an encounter, then Add Enemy and click a tile, Paint Deployment for the player's start tiles, or Add Field Object for walls and barrels.
4. Read the Issues list: an enemy on a blocked tile, two enemies on one tile, no deployment tile, a zone without a baked grid. Fix every error.

Keys: E/Q rotate, Delete removes, R switches an ATB enemy's row, Ctrl+Z / Ctrl+Y undo and redo (a whole brush stroke is one step). The mode edits only the encounter asset, so battles read exactly what you saw.

9.1.6 Battle zones and sites

The quickest way to place a battle in a level is RPG Saga Engine → Advanced tools → Make Battle Zone Here... (or right-click in the viewport → RPG Saga → Make Battle Zone Here). It builds a ready battle site from an area: a Tactics zone with its director, the encounter laid out, a trigger, and optionally a classic stage next to it. Run it again with the same name and it updates the site instead of making a second one. Several sites on one map work. See World building.

9.1.7 Rewards and results

On victory the party receives experience (split among members that took part), loot, money and any progression rewards (battle points, mastery, new abilities, ranks). Then:

• Screen (default for Tactics and classic modes): a results screen after a short delay, with a game-over screen on defeat.
• Feed (default for live battles): no blocking screen. Floating "+340 XP" texts appear over each character with an animated "level up" line, and a stack of notifications slides in at the side for items, money, Pact points, recruits, bestiary entries and quest changes. Exploration continues at once.

The style is set in Project Settings → RPG Saga Engine → Battle Flow UI → Results Presentation (Screen or Feed) and, for Free Tactics, in the Free Tactics settings. The look of the feed is a style asset (URSERewardFeedStyle) selected in Reward Feed. Providers (URSERewardToastProvider) decide what becomes a notification, and you can add your own. A battle that is lost with Defeat Continues Story ticked shows no game over: the fallen members get back on their feet (see the party settings' defeat recovery) and the game goes on.

9.2 How it works

9.2.1 Layers

URSEEncounterData  ──►  Director (RSE)  ──►  URSEBattle subclass (RSECore)  ──►  battle events  ──►  presentation (RSE)
(data)                  builds units,        Tactics / ATB / Turn / FreeTactics /     (damage, status,        animations, camera,
                        deployment, AI       Action: the rules, headless              turn, defeat...)        UI, sounds

URSEBattle is the common base. It owns the units, resources, damage, healing, statuses, reactions, objectives and the event stream. Each mode adds one subclass: URSETacticsBattle, URSEATBBattle (and URSETurnBattle derived from it), the Free Tactics and Action battles. Because the rules never touch actors or rendering, a battle can run headless for tests and simulation. The director turns battle events (ERSEBattleEventType: Turn Started, Ability Used, Damage Dealt, Status Applied, Unit Defeated, Reaction Triggered, Battle Ended and many more) into animations and UI.

9.2.2 The action pipeline

When a unit uses an ability or item:

1. The mode checks the command is legal (whose turn, resources, range or scope, use conditions, item availability).
2. Costs are paid (resources, items, Action Points in grids, charge time in ATB).
3. The ability's effects resolve, per target and once per use (see Abilities). Positional modifiers of the mode apply (flank and height in grids, rows in classic battles).
4. Damage, healing and statuses become events. Shields absorb, affinities scale, the unit may fall.
5. Reactions queue and resolve (counterattacks, guards, overwatch), up to Max Reaction Depth.
6. Objectives are checked after every state change. The battle ends with an outcome: Victory, Defeat or Fled.

9.2.3 Damage and hits

The formulas are data (Project Settings → RPG Saga Engine → Combat Formulas) and a rules profile can replace them. The defaults:

• Physical and magical damage = Power * Offense * DefenseFactor * Position * Variance. Offense is Attack (physical) or Magic (magical), DefenseFactor is DefenseConstant / (DefenseConstant + max(0, Defense)), so armor has diminishing returns and never makes a unit immune.
• Fixed damage (bombs) ignores stats, defense, position and variance.
• Then a critical hit multiplies the damage, a minimum damage applies, and the target's element affinity scales it.
• Hit chance = Attacker.Accuracy - Target.Evasion + HitBonus, clamped to the minimum and maximum hit chance.
• Healing from magic = Power * Attacker.Magic * Variance. Fixed and percent-of-max restores stay as authored.

Element affinities are Normal, Weak, Resist, Immune and Absorb. When several sources apply, Absorb wins, then Immune, then Resist. Weak and Resist together cancel. The multipliers are in Battle → Elements → Affinity Multipliers (defaults 1, 2, 0.5, 0 and -1, so absorb heals).

The offense and defense stats, the formulas and the attribute registry are part of the Game Foundation (see Game foundation).

9.2.4 Determinism

All randomness comes from one seeded stream per battle (loot dice come from a stream derived from the same seed). The same seed and the same commands give the same battle. Custom code must draw numbers with Roll Int and Roll Percent on the battle, never with the engine's global random functions.

9.2.5 Starting a battle

An encounter trigger is the usual start: a volume the player walks into (Repeat: One Shot or Repeatable), touching a roaming enemy, or a random encounter area while walking (see Exploration). The story effect Start Battle starts one from a dialog or a cutscene. Everything funnels into the exploration subsystem, which resolves the mode, finds the battle site and calls the right director.

9.2.6 The battle mode override

The content decides each encounter's mode. The battle mode override is a session setting that fights every encounter that allows it in a different mode. It exists for demo menus, test tools and showcase captures. A story game leaves it empty.

Set it:

It lasts as long as the game instance and is never saved. The encounter's side has three fields: Allow Mode Override (off for scripted battles that only work in one mode), Override Modes (the modes it may use; empty means every mode its data supports) and Mode Rules Profiles (a rules profile per mode).

A battle in another mode runs on a transient copy of the encounter: the mode set, the mode's rules profile applied, the same name (so ids, quests and bestiary entries stay the same). What each mode needs, and what happens when the encounter does not author it:

Technical values are in Project Settings → RPG Saga Engine → Battle Mode Override (overridable modes, Fall Back To Own Mode, fallback sizes). When an override cannot run, the encounter is fought in its own mode with a warning. A site's Log Mode Report button, or URSEBattleModeOverrideLibrary::GetEncounterModeReport, lists for every mode whether the encounter can run in it and which fallbacks it uses.

9.2.7 Encounter sites

ARSEEncounterSite holds one encounter's places for every mode: Tactics Director (its zone is the grid), ATB Director (its stage), the live area (Live Area Radius, Party Start) and an optional Action Area. Encounter triggers point at a site (Site), and the Start Battle effect and StartEncounter find the site of their encounter. Use it when one encounter should work in several modes.

9.3 Key classes and assets

9.4 Settings

Project Settings → RPG Saga Engine:

See Appendix B for the full lists.

9.5 Blueprint usage

From the RPG Saga | Battle library:

• Start Encounter (Encounter, Source): starts a battle as if the player walked in.
• Is In Battle, Get Current Battle, Get Current Encounter, Get Current Battle Outcome.
• Find Tactics Director, Find ATB Director.

Start a boss fight from a lever:

1. Event On Interact (a lever) → Start Encounter (Encounter = DA_Encounter_Starter_Z1_Boss).
2. Bind the exploration subsystem's On Encounter Ended to continue the story.

React to a battle event on a director: bind On Event Presented (it carries the battle event) to show custom numbers or play a sound.

Write a battle effect (for custom abilities): the battle nodes are Deal Damage, Heal Unit, Change Resource, Apply Status, Remove Statuses, Shift Turn, Defeat Unit, Scan Unit, Roll Int and Roll Percent, plus the getters Get Unit, Get Unit Ids, Get Unit Attribute, Get Unit Resource, Unit Has Status, Are Units Enemies and Get Outcome.

See Appendix A for every node.

9.6 C++ usage

Running a battle headless, as the simulator and the tests do:

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

while (!Battle->IsBattleOver())
{
    Battle->Advance(0.1f);
    for (int32 UnitId : Battle->GetReadyUnits())
    {
        // Choose a command (or let RSEATBAI::Act decide).
        Battle->IssueCommand(UnitId, Ability, TargetId);
    }
}
const ERSEBattleOutcome Outcome = Battle->GetOutcome();

To react to events without a director, bind to the battle's event delegate and switch on ERSEBattleEventType. A new objective is a subclass of URSEBattleCondition. A new kind of reward presentation is a URSERewardToastProvider.

9.7 Advanced

9.7.1 Rules profiles

A rules profile (URSERulesProfile) overrides chosen settings sections (Battle, Grid, Combat Formulas, Ability Toolkit, Turn-Based Battle, Inventory Rules, Economy, AI...) for one encounter, one mode, a chapter or the game. Set it on the encounter (Rules Profile), on a mode (Mode Rules Profiles), on a director (Rules Profile Override) or as the project default. Some properties are structure and stay global, such as tile size and the currency.

9.7.2 The battle simulator

The simulator plays whole battles with no rendering, AI against AI, many times with different seeds, and reports what happened. It is the fastest way to find a pushover or a brick wall.

Ways to run it:

• Configurator → Tools → Battle Simulator: pick the encounter, a rules profile (empty means as in the game), the number of battles, the party's level and the AI intelligence of each side, optionally a sweep (a parameter from a start to an end by a step). Run, then Open report.
• Console: RSE.Sim.Run <scenario.json> [Runs] (development builds).
• Command line: UnrealEditor-Cmd.exe MyGame.uproject -run=RSEBattleSim -Scenario=Config/BattleSim/MyScenario.json -unattended -nullrhi with optional -Out= and -Runs=.

A scenario is a small JSON file:

{
  "Name": "Zone1_LevelSweep",
  "Encounter": "/RPGSagaEngine/Data/Encounters/DA_Encounter_Starter_Z1_Pack",
  "Runs": 40,
  "Seed": 2000,
  "PlayerIntelligence": 0.8,
  "Sweep": { "Parameter": "PartyLevel", "From": 1, "To": 10, "Step": 1 }
}

Fields you will use most: Encounter, Mode, Party, PartyItems, RulesProfile, RulesOverrides, Runs, Seed, PlayerIntelligence, EnemyIntelligence, PartyLevel, EnemyLevelMultiplier, ProgressionZone, MaxTurns, MaxSeconds, Grid and Sweep. Sweep parameters include PartyLevel, EnemyLevelMultiplier, the two intelligences, EnemyAIProfile and Rules:<Section>.<Field>, for example Rules:Battle.CriticalMultiplier.

Each run writes results.csv (one row per battle), summary.json and summary.html to Saved/BattleSim/<date-time>_<scenario>/. Read the win rate (how hard the fight is), the median turns and the HP left (tempo and how close the wins are), the performance score (which way adaptive difficulty would push) and the damage per ability (the candidates to tune). A battle that reaches the turn or time guard is a Timeout. The same scenario and seed always give the same results.

Grid battles need a grid. The simulator uses the zone of the map that runs the encounter, a named zone, or a generated grid (Width, Depth, optional height noise). The values are in Project Settings → RPG Saga Engine → Battle Simulator (default runs 50, seed 1, intelligence 0.8, guards 400 turns and 1200 seconds).

9.7.3 Balance My Campaign

RPG Saga Engine → Advanced tools → Balance My Campaign... plays every encounter of every progression zone with the simulator, flags what is too easy, too hard, too long, a stalemate, a one-shot or an ability cliff, proposes the smallest data changes that fix it, verifies each proposal on the same seeds and applies the ticked ones as one undoable step. It needs a campaign asset (the one the Progression Designer uses). Each encounter's Balance Role picks its win-rate band. Assets with Balance Locked are never touched. The command line is -run=RSEBalanceCampaign -Campaign=/Game/.../DA_Campaign_Main, with -Analyze, -Apply and -FailOnFlags for continuous integration. Reports go to Saved/Balance/.

9.7.4 Networking

The host runs the battle. Guests send commands. Because the rules are deterministic and the state is serializable, this needs no extra code from you (Co-op and online).

9.7.5 Performance

Battle logic does no per-frame allocation in the formulas (they are compiled expressions). Presentation cost is your main budget. The RSE.Battle.Presentation.Speed CVar scales presentation timings and RSE.Battle.Presentation.ReduceEffects trims effects (Platforms and performance).

9.7.6 Debugging commands

In development builds: RSE.Battle.StartEncounter <Asset>, RSE.Battle.Start, RSE.Battle.Restart, RSE.Battle.AutoPlay 1 (the AI plays your party too), RSE.Exploration.Encounter [Filter | ATB | Turn | Tactics] and RSE.Encounter.Debug 1. Appendix C lists them with help text.

9.8 Troubleshooting

9.9 See also

• Abilities and statuses, Items, inventory and economy.
• Grid Tactics, ATB and turn-based, Free Tactics, Action battles.
• Enemy AI and adaptive difficulty, Exploration for random and visible encounters.
• Product pages: docs/product/encounter-editor.md, docs/product/random-encounters.md, docs/product/balance-tool.md.

10. Grid Tactics

In short: Grid Tactics is turn-based combat on a square grid laid over your live level. Tiles have height and terrain, units face a direction, and position matters: flanking, high ground, cover, line of sight. Turn order follows a per-unit charge counter (CT), and each turn is paid with Action Points (AP) that you spend on moving and acting in any order. Use it for story battles, bosses and any fight where where you stand matters.

10.1 Basics

10.1.1 The words

10.1.2 Set up your first grid battle

The fast way:

1. Open a level with open, mostly flat ground.
2. Choose RPG Saga Engine → Advanced tools → Make Battle Zone Here... (or right-click in the viewport → RPG Saga → Make Battle Zone Here). Pick an encounter. The tool traces the grid, picks deployment tiles, places the enemies, and adds a zone, a director and a trigger. Press Apply.
3. Play. Walk into the trigger. The world turns into a grid, you place your units on the blue tiles and start the battle.

The manual way (to learn what the tool does):

1. Place an RSE Tactics Zone (search "Tactics Zone" in Place Actors). Its origin is the corner of tile (0,0). The grid follows the actor's location and yaw.
2. Set Grid Width and Grid Depth (12 by 12 by default) and press Bake Grid in Details. Tiles that are too steep, or have no clearance above them, become unwalkable.
3. Place an RSE Tactics Battle Director. Set Zone to your zone and Encounter to an encounter asset. (Or leave the director to be found by a trigger or a battle site.)
4. Lay out the enemies and the deployment tiles with the Encounter Layout mode (see Battle fundamentals).
5. Add an RSE Encounter Trigger that points at the director. Play.

Fix a wrong tile with Tile Overrides on the zone (height, terrain, walkable), then Bake Grid again. Mark scenery the bake should ignore with the actor tag RSE.GridIgnore.

10.1.3 How a battle plays

1. Deployment. The player sees the deployment tiles, places the roster characters (click a blue tile or use the buttons Place, Withdraw, Auto Deploy) and presses Start Battle. Required characters must be placed. With free slots the game asks for confirmation. The encounter's Max Deployed Units (4 by default) limits how many.
2. Turns. The unit whose CT reaches the threshold takes a turn. It gets AP equal to its ActionPoints stat.
3. Move and act. Blue tiles show where the unit can walk. Hovering a tile draws the real path with its AP cost ("5 AP (3 left)"). Choose an ability and the range, the area and who it hits are previewed, with the hit chance, damage range and a KO marker. Moving and acting mix freely: move, attack, move again, as long as AP last.
4. End turn. The player picks the unit's facing. A turn that used no AP costs 60 CT, one that used them all costs 100, and partial use is in between, so a unit that does less comes back sooner.
5. Victory or defeat by the encounter's objectives. Then the results flow starts.

A fallen unit stays on the grid for KO Countdown Turns (3) of its own turns. Revive it in time or it leaves the battle.

A danger zone key toggles an overlay of every tile the enemies can hit on their next turn.

10.2 How it works

10.2.1 Data to rules to presentation

Level geometry ──Bake──► ARSETacticsZone.Grid (FRSETacticalGrid, saved in the level)
                                   │
URSEEncounterData ─► ARSETacticsBattleDirector ─► URSETacticsBattle (RSECore, headless)
                         (deployment, AI turns,        grid, CT, AP, movement, targeting,
                          presentation, input)         positional damage, zones, objects
                                   ▲                                │
                                   └────── battle events ◄──────────┘

URSETacticsBattle holds all the rules and runs without a world. The grid stays inside the battle, and at runtime nothing scans the level. An unbaked zone is baked once at the start of play with a warning (Bake If Empty At Runtime), but the right fix is to press Bake Grid in the editor and save the level.

10.2.2 Movement

• Four directions (North is +X, East is +Y). Heights are whole steps.
• A step is allowed when the target tile is walkable, its terrain is not impassable, the height difference fits the unit's jump (Stat.Jump up, jump plus Jump Down Bonus down) and no enemy stands there.
• The cost of a step is the terrain's Move Cost plus a height cost: Climb Cost Per Step (default 1) for each step up and Descend Cost Per Step (default 0) for each step down. Stairs (Terrain.Stairs) cancel the height cost.
• Units can pass through allies but not stop on them. Enemies block fully.
• Pathfinding is A* over the real costs. The AI uses the same queries.

Terrains are gameplay tags with rules in Project Settings → RPG Saga Engine → Grid → Terrain Rules: move cost, impassable, water, no climb cost, an Evasion Bonus and a Defense Bonus Percent for the unit standing there, and a display name. The starter terrains are Ground, Grass, Sand (cost 2), Swamp (3), Stairs, Shallow Water (2) and Deep Water (impassable).

Movement traits are tags a unit gets from its class, equipment, a Pact or a status:

10.2.3 Turn order and Action Points

CT fills every tick with the unit's Speed. At CT Threshold (100) the unit acts. After the turn it pays between Turn CT Cost Idle (60) and Turn CT Cost Full (100). The HUD shows the predicted order (PredictTurnOrder in the code). Statuses with Status.Block.Turn skip the turn, Status.Block.Move and Status.Block.Act stop one half. Turn manipulation effects change CT, and the Action Points effect adds or removes AP now or next turn (limited by Max Bonus Action Points).

10.2.4 Position and damage

Tactics adds three things to the shared damage rules:

• Facing. A hit from the side deals 1.25 times the damage (Side Damage Multiplier) with +10 hit chance (Side Hit Bonus). From behind it is 1.5 times with +25 (Back Damage Multiplier, Back Hit Bonus).
• Height. Damage changes by 10% per height step the attacker stands above the target (Height Damage Per Step), clamped between 0.7 and 1.5.
• Terrain. The target's tile gives it its evasion bonus and defense bonus.

All of this is in one breakdown (FRSETacticsPositionalBreakdown) used by the real hit, the AI's estimate and the forecast the player sees, so they always agree. The values are in Battle → Tactics → Positioning.

10.2.5 Targeting, shapes and line of sight

An ability's Tactics Rules decide what can be targeted: Min Range and Max Range (Manhattan distance in tiles), Vertical Tolerance (height difference), and Requires Line Of Sight. Line of sight is traced from an eye height above the tile surface (Line Of Sight Eye Height, 2 steps). Walls and tall objects block it. A Direct trajectory is a straight shot. An Arc (with Arc Height) flies over lower obstacles. Height Steps Per Range Bonus gives extra range from high ground.

The area is one of Single, Diamond, Cross, Line, Cone, Ring, Rectangle or Mask. A Mask is a hand-drawn pattern of rows separated by / or |, where X or # is a hit tile, O the center and @ a hit center. Area Centered On Caster makes the shape start at the user (a blast around you, a cone in front). Falloff lowers power with distance from the center.

10.2.6 Zones and field objects

Grid battles add two kinds of field content, both data assets:

• Tile zones (URSETileZoneData): an area effect that lasts a number of turns. It has Effects On Enter and Effects On Turn Start, a Trigger Filter, Extra Move Cost (the pathfinder pays it), Slippery (units slide), Trap (triggers once, optionally Hidden From Enemies) and Removes Zones (fire melts ice). Examples in /RPGSagaEngine/Data/Field/: DA_Zone_FireGround, DA_Zone_HealingSpring, DA_Zone_SpikeTrap.
• Field objects (URSEFieldObjectData): walls, barriers, crates, explosive barrels. They have HP, can block movement and line of sight, expire after a number of turns, and can explode, chaining to neighbors (up to Max Chain Explosions). Examples: DA_Object_StoneWall, DA_Object_ExplosiveBarrel.

Abilities create them with Create Zone and Spawn Object effects. Encounters can place objects from the start (Field Objects). Movement is evaluated tile by tile, so traps, zones, overwatch and sliding trigger on each tile.

10.2.7 Deployment

FRSEDeployment (RSECore, no world) holds the roster, the deployment tiles and the placements. CheckStart answers Ready, Not Full, Missing Required or No Units. AutoDeploy places required characters first, then the rest, putting short-range units on tiles closest to the enemy and long-range units behind. Units already placed never move.

10.3 Key classes and assets

10.4 Settings

Project Settings → RPG Saga Engine:

See Appendix B for every property.

10.5 Blueprint usage

Start a grid battle from a button:

1. Event (a menu button) → Find Tactics Director (Encounter = DA_Encounter_Starter_Z1_Skirmish).
2. Branch on Is Valid. True: Set Encounter, then Begin Encounter. If you want to skip deployment, tick Auto Deploy on the director and call Start Battle.
3. Bind On Event Presented on the director to show your own numbers, or use the shipped HUD.

Useful director nodes: Begin Encounter, Start Battle, Restart Encounter, End Encounter, Get Phase (Idle, Deployment, Battle, Finished), Get Battle, Get Battle Outcome, Is Awaiting Command, Is Playback Idle, Get Unit Actor, Get Last Rewards.

Rebake from a tool: the zone's Bake Grid and Clear Grid are callable in the editor, and RSE.Tactics.BakeZones rebakes every zone in the level in development builds.

The full node list is in Appendix A.

10.6 C++ usage

Move and attack in a headless grid battle (a test, a tool, an AI):

URSETacticsBattle* Battle = NewObject<URSETacticsBattle>();
Battle->Initialize(Grid, Spawns, /*Seed*/ 7);
Battle->StartBattle();

TArray<FRSEGridReachableTile> Reach;
Battle->GetActiveUnitReachableTilesWithCost(Reach);

if (Battle->MoveActiveUnit(Goal))
{
    const ERSEAbilityUseResult Result = Battle->UseAbility(Ability, Target);
    if (Result == ERSEAbilityUseResult::Ok)
    {
        Battle->EndTurn(ERSEGridDirection::South);
    }
}

ERSEAbilityUseResult explains refusals: Not Active Unit, Blocked, Unknown Ability, Not Enough Action Points, Not Enough Resources, Uses Per Turn Reached, Invalid Target, Item Unavailable, Requirement Not Met. For the player's UI use ForecastAbilityAt, GetTargetingTilesFrom and GetAreaPreviewFrom. They use the same path as the real resolution and never change the battle.

From a director, the same commands are CommandMove, CommandAbility, CommandItem, CommandEndTurn, DeployPlace and DeployWithdraw.

Extension points:

• A new effect that works on the grid: a subclass of URSEAbilityEffect that overrides PreviewDisplacement (to preview movement) and uses the battle's grid functions (ComputePush, ApplyPush, IsTileStandable).
• A new terrain: a gameplay tag under Terrain.* plus a row in Grid → Terrain Rules.
• A new objective: a URSEBattleCondition subclass.
• Your own unit actor: set the director's Unit Actor Class to a subclass of ARSEGridUnit.

10.7 Advanced

10.7.1 Terrain from the world

The bake traces straight down for every tile. A tile is walkable when the surface is flat enough and has clear space above. Surfaces that do not block pawns, pawns, objects narrower than Bake Min Surface Size and anything tagged RSE.GridIgnore are skipped. Combat roles on level actors (cover, obstacle, difficult terrain, high ground) can change tiles during the bake (see World building). The bake keeps the exact surface under each tile, so units, the path line and the highlights sit on the real ground even on slopes.

10.7.2 Grid visuals

Grid Visual Mode is Projected by default: one decal over the zone drawn from a small texture, which looks right on uneven ground and costs one draw call. Tiles draws instanced meshes. Projected needs a grid decal material. Without it the mode falls back to Tiles. You can show the grid only in battle (Show Grid Only In Battle) and play a reveal animation when the battle starts.

10.7.3 Rules profiles for tactics

Tile size and height step are global because levels are built for them. Everything else (costs, positioning, CT, KO countdown) can change per encounter through a rules profile. A boss can use a profile with no side bonus, a swamp level a profile with cheaper water.

10.7.4 AI

The AI plans on the same reachable tiles and costs. It scores flanks, height, line-of-sight blocking and danger tiles according to its intelligence value (see Enemy AI and adaptive difficulty). The director's AI Think Delay and Event Pause set the presentation pace.

10.7.5 Networking

The host runs the grid battle and guests send commands (FRSECmd family). The battle is deterministic, so every machine can mirror it (Co-op and online).

10.7.6 Performance

• The grid is data in the level. Nothing is scanned at runtime.
• The director has no per-frame cost beyond its presentation.
• The danger zone and the previews recompute only when the battle changes.
• Use Projected for live-map battles and keep the Combat Area free of clutter.

10.7.7 Development commands

In development builds: RSE.Tactics.ShowReach [Unit], RSE.Tactics.MoveUnit X Y [Unit], RSE.Tactics.BakeZones, RSE.Tactics.Demo approach|use|wait, RSE.Tactics.Deploy [start], RSE.Tactics.Preview style Classic|Modern|Default and RSE.Battle.AutoPlay 1. See Appendix C.

10.8 Troubleshooting

10.9 See also

• Battle fundamentals for encounters, objectives, rewards and the simulator.
• Abilities and statuses for Tactics Rules, area shapes and reactions (overwatch).
• Free Tactics for the same idea without a grid.
• World building for Make Battle Zone Here and combat roles.
• Camera and battle presentation.
• Product pages: docs/product/encounter-editor.md, docs/product/combat-roles.md, docs/product/world-tools.md.

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.

12. Free Tactics (Live)

In short: Free Tactics is a turn-based battle mode that is fought right on the exploration map, with free movement in meters instead of grid tiles. There is no loading screen and no battle map: enemies notice the party, the camera lifts into a tactical view, and everyone fights from where they stand. Use it for modern party-tactics fights: cover, height, surfaces, doors, summons and a battlefield you can break.

12.1 Basics

12.1.1 What the player sees

1. Being noticed. Enemies have a vision cone and hearing. A bar fills above their heads while they see or hear the party. When it is full, a ! appears and the battle starts. The bar empties again if the party gets out of sight. Sneaking makes the party harder to see and hear. Tall grass and shadows hide it even better.
2. How the battle opens. There are three openings:
   • They noticed you: normal initiative.
   • You reached them unseen (from behind, sneaking): a surprise round. The party acts first and the enemies lose their first turn.
   • They were waiting in ambush: the enemies act first and the party loses its first turn.
3. A turn. The active character sees a soft outline on the ground that shows how far it can walk. Pointing at the ground shows the path and its length. Pointing at a target shows the damage, the chance to hit and the chance of a critical hit, with cover, height and flanking already counted. Walking and acting happen in any order until the turn's budget is spent or the player picks End Turn. Commands that cannot be used right now are dimmed and say why.
4. Others join. Groups standing close to the fight join from the start. Enemies that walk past and notice the battle join at the start of the next round. Party members near the leader fight from where they stand.
5. Running away. Flee works when no enemy that can see the character is within the escape radius. Fled units keep their HP. When everyone still standing has fled, the battle ends as an escape.
6. The end. On victory, a banner lists experience, money and items, and the player keeps exploring from where they stand. On defeat, the Game Over screen offers Retry battle, which puts everything back as it was just before the fight.

12.1.2 Make a group fight in Free Tactics

1. Select an Encounter Spawner in your level.
2. In the Details panel, under Free Tactics, tick Free Tactics.
3. Optional: tick Ambush so the group attacks first when it notices the party.

Or open an Encounter asset and set its Battle Mode to Free Tactics. Every spawner that uses it, and every trigger that starts it, then fights in Free Tactics. See Battle fundamentals for encounters and the battle mode override. A camp that should stand guard instead of wandering needs a Roaming Behavior whose Idle is Stand; Detection Speed on the behavior makes a group notice faster or slower.

12.1.3 Try it in two minutes

Open /RPGSagaEngine/Examples/Maps/L_RSE_StarterExample, press Play, open the console and type:

RSE.FreeTactics.Setup 16

A camp with walls, crates and tall grass appears 16 m in front of you. Walk toward it, or sneak around and strike from behind for a surprise round. RSE.FreeTactics.Setup 16 ambush makes the camp lie in ambush instead. These test commands are not in shipping builds. The map /RPGSagaEngine/Examples/Maps/L_RSE_FreeTacticsInterior is a two-floor house with stairs, a balcony, ladders, doors, windows and a basement. See Appendix C for every console command.

12.1.4 Hide a spot in tall grass or shadow

Place a volume over the grass and add the actor tag RSE.TallGrass (or RSE.Shadow). How much each tag hides is set in Project Settings → RPG Saga Engine → Stealth → Concealment Tags. You can add your own tags there.

12.1.5 Keep something out of the battle area

The battle area is measured from your level when the fight starts: walls, rocks and crates become cover. Any actor tagged RSE.FreeTacticsIgnore is left out (foliage, decorations, effects). The combat roles you give your assets decide what counts as full cover, half cover, rough ground or nothing at all (see Enemy AI and adaptive difficulty for the Combat Role Configurator).

12.2 How it works

Exploration (enemy notices party, or a trigger / dialog starts an encounter)
  -> URSEFreeTacticsSubsystem gathers who takes part (the group, the called-for-help enemies, nearby party members)
  -> ARSEFreeTacticsDirector captures the area into a navigation snapshot (meters, floors, cover, doors)
  -> URSEFreeTacticsBattle (RSECore) runs the rules: turn order, budgets, commands, surfaces, objects, AI
  -> the director shows the battle's events (camera, overlay, HUD, effects) and turns input into commands
  -> victory / defeat / escape -> back to exploration, no transition

The rules run without a world. URSEFreeTacticsBattle is plain data and logic in RSECore, so the same battle runs in the headless battle simulator and in automated tests. The director in RSE only captures the area, presents the events and turns the player's input into commands.

Every decision is a command. A move, an ability, a flee, a door, a jump and End Turn are each one FRSEFreeTacticsCommand. The battle validates a command (ExecuteCommand) and either applies it or refuses it with an ERSEFreeCommandResult (not your turn, cannot reach, action rejected, cannot flee, cannot use door, cannot jump). Commands are plain serializable data, which is why the same battle can be saved, replayed and driven over the network.

Who decides is a Free Tactics Controller (URSEFreeTacticsController): the local player (a queued controller that waits for input), the companion AI or the enemy AI. You can swap controllers per team or per unit at any time.

Turn order is individual Charge Time by default (fast units act more often), with an optional team-based round mode. Turn budget is either one shared Action Point pool, or three separate budgets: movement in meters, an action and a bonus action (the default).

Determinism. Every random roll (a slip, a status) uses the battle's seed, so the same commands give the same battle.

12.2.1 Battle feel

A live battle should feel like a fight, not like a menu. The classic modes are not changed by any of it, and every piece can be turned off.

• The start. A ring spreads on the ground from the point where the party and the enemies met, time slows down for a moment, the enemies that noticed you turn toward the party and shout a short line, the HUD fades in and the music crossfades to the battle music. Nobody is teleported: a unit that stands where it cannot is nudged a few centimeters (Max Start Nudge).
• Every action at its pace. Each action plays in phases: wind-up (a spell charges with a magic circle and its area is marked on the ground), the action itself (a spell or shot flies to its target and the hit waits for it), impact (a flash, a few frames of hit-stop, the target flinches) and recovery. Defaults per kind of action (melee, ranged, spell, support, item) live in Battle Feel → Pacing, and a presentation asset or an ability can override them.
• Juice. Weapon trails, damage numbers tinted by element, looping effects while a status lasts, an optional impact shake and a camera that glides to the active character without close-ups.
• What the enemy is about to do. On an enemy's turn a small icon (attack, spell, heal, buff, debuff, item, summon, move, flee) shows over it for a moment before it acts, sometimes with a short line. The icons, colors and lines are in Battle Feel → Intent.

12.3 Key classes and assets

12.4 Settings

Everything is in Project Settings → RPG Saga Engine. The groups that matter for Free Tactics:

Defaults worth knowing (all in Free Tactics):

Every value is checked when you save (IsDataValid). For example the editor warns when the overlay material does not match the overlay style, or when the tactical camera's zoom limits are the wrong way round. See Appendix B for the full list.

12.5 Blueprint usage

12.5.1 Start a battle from a trigger or a dialog

1. Event (Box Trigger overlap, or a dialog effect) → Get RSE Free Tactics Subsystem (a world subsystem node).
2. Start Encounter Battle (Encounter = DA_Encounter_Camp, Opening = Normal, Enemy Actors = the enemies standing in your level, Source = Self).
3. Branch on the returned Boolean: false means a battle cannot start now.

Start Group Battle does the same for a visible group of an Encounter Spawner (Spawner, Group Index, Opening). The opening is ERSEFreeOpening: Normal, Player Surprise or Enemy Surprise.

12.5.2 Ask what is going on

• Is Battle Active and Get Active Director on the subsystem.
• On the director: Get Battle, Is Awaiting Player, Get Input Mode, Get Unit Actor, Get Unit Id Of, Get Unit Name, Is Entry Playing.
• On the battle: Get Round, Is Surprised, Can Flee Battle, Check Flee, Has Escaped, Get Door Count, Is Door Open.

12.5.3 Write your own controller

1. Create a Blueprint class from Free Tactics Controller.
2. Override Provide Command (Battle, Unit Id → Out Command, return value). Fill the command (for example Make Move style: Type = Move, Unit Id, Point) and return true, or return false to wait.
3. Optional: override On Command Rejected to react when the battle refuses a command.
4. On the battle, call Set Team Controller (a team tag) or Set Unit Controller (a unit id).

12.5.4 Change the battlefield from a script

• Create Surface Circle (Creator Id, Data = DA_Surface_Oil, Center, Radius, Duration Override) and Remove Surface.
• Spawn Object, Damage Object (a barrel taking damage can explode).
• Check Jump and Preview From Destination for custom UI.
• Toggle Door and, on an RSE Door actor, Set Locked and Set Open.

12.5.5 Presentation events

The director exposes On Event Presented, On Callout (a bark or an intent over a unit), On Notice and On Custom Menu Command. Bind them in a HUD Blueprint. See Appendix A for every node.

12.6 C++ usage

Drive a battle from code, for example from a custom controller:

UCLASS()
class UMyHoldPositionController : public URSEFreeTacticsController
{
	GENERATED_BODY()

protected:
	virtual bool ProvideCommand_Implementation(URSEFreeTacticsBattle* Battle, int32 UnitId,
		FRSEFreeTacticsCommand& OutCommand) override
	{
		// Never move: end the turn facing north.
		OutCommand = FRSEFreeTacticsCommand::MakeEndTurn(UnitId, 0.f);
		return true;
	}
};

// Somewhere that owns the battle:
Battle->SetUnitController(UnitId, NewObject<UMyHoldPositionController>(Battle));
const ERSEFreeCommandResult Result = Battle->ExecuteCommand(
	FRSEFreeTacticsCommand::MakeMove(UnitId, FVector(4.f, 0.f, 0.f)));

Start a battle from C++:

if (URSEFreeTacticsSubsystem* Free = URSEFreeTacticsSubsystem::Get(this))
{
	Free->StartEncounterBattle(Encounter, ERSEFreeOpening::PlayerSurprise, EnemyActors, this);
}

Extension points:

• URSEFreeTacticsController (C++ or Blueprint) for any decision logic.
• URSECoverProvider: subclass and set it in Free Tactics → Cover → Cover Provider. Or call SetCoverProvider on a battle.
• Command-bus integration: FRSEFreeTacticsCommand derives from FRSECommand, so it travels through the same bus as the rest of the plugin (see Co-op and online).
• Try the rules headless in the battle simulator: `` UnrealEditor-Cmd.exe YourProject.uproject -run=RSEBattleSim "-Scenario=Plugins/RPGSagaEngine/Config/BattleSim/FreeTacticsSkirmish.json" ``

12.7 Advanced

12.7.1 The battlefield

The ground itself takes part in the fight.

Surfaces. Fire, water, electrified water, ice, oil, poison, blood and steam lie on the ground as areas measured in meters and drawn on the real terrain. When two surfaces meet, or an attack of an element hits one, they react: fire on oil makes a bigger fire, lightning on water electrifies it, cold freezes water, fire melts ice, water puts fire out. Reactions can chain (burning oil reaches a barrel, the barrel explodes). The AI avoids harmful surfaces and likes to ignite oil or electrify the water its enemies stand in.

To make your own surface:

1. Create an RSE Surface Data asset (or duplicate one of /RPGSagaEngine/Data/Field/DA_Surface_*).
2. Give it a Zone Tag (for example Zone.Tar), a name, a color and a Look (Liquid, Fire, Frozen, Oil, Toxic, Electric, Vapor).
3. Fill in what it does: Effects On Enter, Effects On Turn Start, Duration Turns, Move Cost Multiplier, Slip Chance, Slip Status and the Visual.
4. Add its reactions in Project Settings → Free Tactics Field → Interactions: one row per pair (this surface + this element, surface or weather = that surface, or nothing to remove it).
5. Let an ability make it with a Create Zone effect.

Surfaces already lying in the level. Place an RSE Surface Spot actor over a ford, a puddle of oil or a marsh and set its Surface. Scale its box to the area (or tick Circle). When a battle starts, every spot inside the battle area lays its surface. Duration Rounds 0 keeps it for the whole battle, -1 uses the surface's own duration. Outside battles the spot does nothing and is not drawn.

Breakable and explosive objects. Give a mesh the combat role Destructible or Explosive. The role sets the hit points, and its Break Object (a Field Object Data asset) sets the explosion's damage and radius, the surface it leaves and the effects it plays. Examples: DA_Object_ExplosiveBarrel, DA_Object_Crate. A broken object stops being cover.

Pushes, jumps and falls. Shove and every Knockback effect push a unit back in meters: into a wall it takes collision damage, off a ledge it falls and takes damage by height (the Fall Damage curve). Jump is a command next to Move that crosses gaps and climbs low ledges; it costs movement or the bonus action, as you set in Free Tactics Field → Jumping. Leap, Dash, Teleport and Swap work in meters too.

Reading the battlefield. Pointing at a spot you can walk to shows cover shields on the side of each enemy it covers from, plus the hit and critical chance each enemy would have against you there. A line of fire shows green when clear, yellow through cover and red where a wall blocks it. Roofs, upper floors and tree canopies tagged with the combat role Overhead (or an actor tag from Cutaway Tags) are cut away while the camera looks under them.

12.7.2 Abilities in meters and Overwatch

An ability without its own Free Tactics rules is converted from its Tactics rules (1 tile = Meters Per Tile). To tune it, open the ability and turn on Free Tactics Rules → Override: Action Cost, Action Point Cost, Min and Max Range, vertical tolerance, line of sight and trajectory (direct or arc), area shape (single, circle, cone, line), radius, falloff, uses per turn and whether it ends the turn.

Overwatch (a stance) is set in the same struct. Tick Overwatch → Enabled on an ability: using it puts the unit on watch until its next turn. The first enemy that enters, or moves within, its watch Range is answered at once with the Response ability at Damage Factor (0.7 by default). By default it spends the rest of the turn and ends it. Overwatch is how reactions come into the live mode while Opportunity Attacks stays off.

If you turn Opportunity Attacks on, a unit that walks out of an enemy's melee reach provokes a strike. The traits Trait.Reaction.OpportunityAttack and Trait.Reaction.NoOpportunityAttack (on a class, character, equipment or status) decide for their unit whatever the setting says.

12.7.3 Summons

Summons appear where the summoner points. The ground shows every legal spot (within Summon Placement Range, standable, with room for the creature, not on anybody, in the summoner's sight). A refused spot says why. A big creature takes more room: set Summon Footprint Radius on the Pact, or Footprint Radius on the Summon Units effect.

12.7.4 Inside buildings

The battle map is measured with every floor of every spot, so units can fight on a balcony over the yard, a bridge, a basement.

• Stairs made of separate steps: tag each step RSE.Floor. Ramps and wide stairs need no tag.
• Ladders: place an RSE Ladder, move its Bottom Point and Top Point widgets onto the two floors it joins.
• Doors: place an RSE Door. In exploration the player opens it with the interact button. In battle a unit next to it opens or closes it (Open Door / Close Door). A closed door blocks the way and line of sight; a locked one does not open. Enemies open a door when it is the only way to the party.
• Windows: a gap in a wall that units can see and shoot through but not walk through. A glass pane that should block the way but not the view takes the tag RSE.Window.
• Interior Volumes: place an RSE Interior Volume over each building, cave or room. Inside it the exploration camera moves closer (or, with Fixed Angle, keeps a fixed rotation for a classic pre-rendered room look). A battle that starts inside measures only the volume (plus Battle Area Margin) and uses the volume's Battle Camera. The highest Priority wins where volumes overlap.

Each floor needs its own collision (one slab per actor or per component): one mesh holding several floors is read as its top floor only.

12.7.5 The visible party

Outside battle the party walks behind the leader in formation. Switch Leader and Party Command are input actions in Project Settings → Exploration. Party Command opens a radial menu of orders (Search here, Open / unlock, Guard here, Come to me, Stay, Scout ahead). Each order is a Party Command Data asset (requirements, chance of success with a bonus for preferred classes, effects on success and on failure, the noise of a failure, texts), added in Project Settings → Party Field → Commands. Members keep a loose place that drifts, close up in corridors, stroll and play idle animations when the leader stands still. That comes from a Follower Profile asset (formation values and a weighted list of idle behaviors with cooldowns). Add a behavior by adding an entry, or by subclassing RSE Idle Behavior (URSEIdleBehavior) in Blueprint. RSE Idle Spot actors give them benches and walls to use.

In Blueprint, the party field subsystem offers Cycle Leader, Set Leader, Follow, Stay, Refresh Followers and Toggle Command Menu.

12.7.6 The exploration camera

Outside battle the party is seen from above at a tactical angle, and the same camera runs the battles, so a fight starts with the camera simply taking over. Zoom, tilt, turn and pan are all player-controlled (and rebindable in Options). Walls and trees fade only where they hide a character:

• materials with the fade function show a soft dithered circle around the hidden character;
• any other mesh turns into a ghost (M_RSE_CameraOcclusionGhost) while it covers enough of a character;
• hiding is the last resort.

To add the exact fade to your own materials, select them in the Content Browser, then right click → RPG Saga: Add Camera Occlusion Fade (and RPG Saga: Remove Camera Occlusion Fade to undo). The tool changes only materials under Camera Occlusion → Opt In Content Roots (/Game/ by default) and keeps backups in Saved/RSE/CameraOcclusionBackups/. Tag an actor RSE.NoFade to keep it from ever fading, and RSE.Ground for ground meshes. Place an RSE Exploration Camera (Level) actor to give one level its own camera style or limits (a town can keep the classic close third-person camera while the rest of the game uses the tactical one). In Blueprint, Get Camera Style, Set Camera Style and Clear Camera Style on the exploration camera subsystem switch it live. See Camera and battle presentation.

12.7.7 Co-op

Free Tactics is host-authoritative. The host's battle owns the rules; guests present the host's events and send commands for the units they play. Settings in Project Settings → Free Tactics (Co-op):

• Companion Units: party units that no player plays are commanded by the AI (default) or by the host.
• Turn Timeout Seconds (45 s) and Turn Timeout Action: when a guest does not answer in time, the host takes over (default), the AI plays the turn, or the battle waits.
• Guest Playback Wait Max, Catch Up Backlog, Catch Up Playback Rate: the host waits for guests to show the events so far, but never longer than the limit; a guest that falls behind plays the backlog faster.
• Pull In Far Players: players farther than Party Join Radius are brought next to the leader with a short fade.
• Reconnect Retakes Unit At Once: a player who reconnects gets their unit back immediately, or watches until the battle ends.

Single-player games read none of this. See Co-op and online.

12.7.8 Performance notes

The navigation snapshot cell size (Snapshot Cell Size, 0.25 m) trades path detail against memory and capture time; raise it for large battle areas. Max Search Cells guards path searches. The AI samples AI Candidate Positions per decision, so lower it on weak hardware. Nothing in the mode needs Tick outside an active battle.

12.8 Troubleshooting

12.9 See also

• Battle fundamentals for encounters, rewards and the simulator.
• Grid Tactics for the grid mode that shares abilities and Action Points.
• Enemy AI and adaptive difficulty for how enemies choose.
• Exploration for stealth, encounters on the map and reinforcements.
• Co-op and online for the network model.
• Product pages in docs/product/: free-tactics.md, combat-roles.md, coop.md.

13. Action battles

In short: Action battles are fought live. The player swings a sword, rolls, guards, parries, aims a gun or casts a spell, and the enemies do the same, all on the party, classes, abilities, items and statuses you already built for the other modes. Use it for a sword game, a shooter, or a hybrid. The fight happens where the party stands (in a bounded arena or in the open), alone or in co-op.

13.1 Basics

13.1.1 What an action battle is

An encounter is an action battle when its Battle Mode is Action (Battle.Mode.Action). Nothing else about the encounter changes: enemies, levels, rewards, loot and story effects are the same fields as in any other encounter. Start it like any battle: a story effect that starts an encounter, or an Encounter Trigger with its Action Encounter set (walk in and the battle starts where the party stands).

Every action battle is framed one of two ways (a rule of its rules profile):

Bounded fits arenas, bosses and set pieces. Open fits roaming enemies in a living world. Victory and defeat use the same objectives as every other mode. Defeat shows the game over screen, and Retry puts everyone back where they stood. There is no saving during a battle, as in every mode.

13.1.2 Three presets

All numbers of the mode are one settings section, Action Battle, and also a section of every rules profile. Three presets set every number to a starting point (Apply Preset on the section, or one of the shipped rules profiles):

The Game Foundation can also start a project as an action game: the presets Action: Swords and Action: Shooter (Studio → Foundation) turn the Action mode on, write the matching preset into the Action Battle rules and make Action the mode new battles start with. See Game foundation and archetypes.

13.1.3 Your first action battle

1. In RPG Saga Studio, open World → New Action Battle.
2. Pick a preset, a bounded area (with its radius) or an open fight, the enemies, and optionally a weapon per class.
3. Press Simulate. The real-time AI plays quick headless battles on both sides and tells you how fair the fight is (Easy, Fair, Hard, Very hard).
4. Press Create. The wizard makes the Action encounter, plus a small rules profile if the framing or the area differs from the preset. It can place an Encounter Trigger in front of the camera.
5. Play. The example map /RPGSagaEngine/Examples/Maps/L_RSE_ActionArena has a Melee, a Shooter and a Hybrid encounter.

If a character has no weapon, everyone punches: link an Action Weapon from the character's equipment, or set a Default Weapon in the rules.

13.1.4 Default controls

All keys are remappable in Project Settings → Action Battle (Presentation) → Input, or give your project its own Input Mapping Context.

13.2 How it works

Encounter (Battle Mode = Action) starts where the party stands
  -> URSEActionBattleSubsystem::StartEncounterBattle spawns the director
  -> ARSEActionBattleDirector builds a URSEActionBattle (RSECore) and binds each character
  -> input -> URSEActionControlsComponent -> FRSEActionCommand -> URSEActionBattle::ExecuteCommand
  -> the battle steps at a fixed rate (Step Seconds): phases, stamina, poise, cooldowns, projectiles
  -> hits are claimed by the presentation (animation windows, traces, projectile actors); the host validates every claim
  -> events -> URSEActionCombatComponent plays montages, effects and hit reactions; the HUD follows

The simulation is separate from the picture. URSEActionBattle in RSECore advances in fixed steps (StepSeconds, 1/30 s by default), so a seed replays exactly and the battle can run headless in the simulator and in tests. The presentation in RSE moves characters, plays animation, claims hits and draws the HUD.

Every action has phases. Windup (telegraphed), Active (it can hit now), Recovery. Dodges have i-frames. Guarding reduces damage and drains stamina, and a block that runs out of stamina is a guard break. A parry is a timed guard that staggers a melee attacker. Poise absorbs hits until the unit staggers.

Hits are claimed, then checked. The character's attack opens a hit window (from an RSE Action Hit Window animation notify state, or from the action's own timing). The presentation claims what the attack touches. The battle accepts a claim only if the action exists, it is inside the active window (plus a latency tolerance), within reach (plus a tolerance), and only once per victim. This is the same check that keeps co-op honest.

Abilities in real time. Every ability you already have works at once. Without its own Action rules, an ability gets derived rules from its other data: self abilities stay on the caster, allies are healed or buffed directly, enemies within a tile or so are melee, enemy areas become areas (tiles times meters per tile), everything else is a projectile. Damage, element, statuses, shields, reactions and costs remain the ability's shared data, so the same effects resolve in every mode. Statuses run on a per-unit clock (Seconds Per Turn is "one turn").

Ability pacing is one big choice (Ability Pacing in the rules): Cooldown (each ability has a cooldown), Gauge (hits dealt, hits taken and parries fill segments, abilities spend them) or Resource Only (MP and similar, no cooldowns).

13.3 Key classes and assets

The shipped weapons live in /RPGSagaEngine/Data/Action: Sword, Dagger, Greatsword, Rifle, Pistol, Shotgun, Bow, Staff and Gunblade. Make your own by duplicating one. The Studio never edits the shipped ones.

13.4 Settings

Defaults worth knowing (Action Battle rules):

Every number is validated (URSEActionRules::Validate). See Appendix B for the full list.

13.5 Blueprint usage

13.5.1 Start an action battle from a script

1. Event (Box Trigger overlap, or a dialog effect) → Get RSE Action Battle Subsystem.
2. Start Encounter Battle (Encounter = a Battle Mode = Action encounter, Enemy Actors = the enemies standing in the level, Source = Self).
3. Branch on the returned Boolean.

For no-script setups, place an Encounter Trigger and set its Action Encounter. The trigger's validation warns if a Tactics or ATB director is also set, or if the encounter's mode is not Action.

13.5.2 Ask what is going on

• On the subsystem: Is Battle Active, Get Active Director.
• On a character's RSE Action Combat component: Find Action Combat (static, from an actor), Is In Action Battle, Get Unit Id, Get Director, Is Hit Window Open, Get Muzzle Location, Get Character Mesh.
• On the player's RSE Action Controls component: Find Action Controls (from a player controller), Is Action Input Active, Get Controlled Unit, Get Lock Target, Get Soft Target, Is Aiming, Is Guarding, Get Selectable Abilities, Get Selected Ability.

13.5.3 Drive the controls yourself (custom input, touch, scripted scenes)

• Press Input (Input = Light Attack, Heavy Attack, Aim, Guard, Parry, Dodge, Lock On, Next Target, Previous Target and so on, Pressed = true or false).
• Add Look (Yaw Degrees, Pitch Degrees), Toggle Lock On, Lock On Unit, Switch Target.
• Issue Party Order (Order = Free, Follow, Attack My Target, Hold Position, Defend Me), Cycle Party Order, Switch Character.

13.5.4 React to what happens

Bind On Action Event on the RSE Action Combat component (one battle event about this character: it acts, it is hit, it guards...), On Hit Claimed (a hit of this character's attack was claimed), or On Battle Event on the director. A Blueprint character that wants to play its own animations turns Play Action Anims off and plays montages from On Action Event.

13.5.5 Add hit windows to your animations

In a montage or animation, add an RSE Action Hit Window notify state across the frames where the weapon is dangerous. Without it, hits come at the action's timing, which still works but ignores the animation.

13.6 C++ usage

Start a battle and read a character's combat state:

if (URSEActionBattleSubsystem* Action = URSEActionBattleSubsystem::Get(this)) // via the world
{
	Action->StartEncounterBattle(Encounter, EnemyActors, /*Source*/ this);
}

if (URSEActionCombatComponent* Combat = URSEActionCombatComponent::FindActionCombat(Character))
{
	if (Combat->IsInActionBattle() && Combat->IsHitWindowOpen())
	{
		// A custom effect while the weapon is dangerous.
	}
}

Feed input to a custom pawn without the stock input mapping:

if (URSEActionControlsComponent* Controls = URSEActionControlsComponent::FindActionControls(PlayerController))
{
	Controls->PressInput(ERSEActionInput::Dodge, true);
	Controls->PressInput(ERSEActionInput::Dodge, false);
}

Extension points:

• A Blueprint or C++ child of ARSEActionBattleDirector (set in Action Battle (Presentation) → Flow → Director Class) adds its own reactions to the stock presenter.
• A child of ARSEActionProjectileActor (Hits → Projectile Class) gives projectiles their own mesh, trail and impact.
• An ability can use custom logic classes as in every mode (see Abilities and statuses).
• Subclass URSEWeaponPresentationBase data (an action weapon's Weapon Presentation) to change how a weapon looks when it swings or fires (see Weapons).

13.7 Advanced

13.7.1 Weapons and combos

A weapon is a RSE Action Weapon Data asset, linked from an equipment item (Action Weapon on the item). Units without one use the rules' Default Weapon; units with neither fight with their basic attack and derived rules.

A weapon has:

• a Light Combo and a Heavy Combo (URSEActionComboData): chains of Steps. Each step names an ability, a Power Multiplier, Windup, Active Time and Recovery, a Combo Window (pressing Attack inside it chains the next step; pressing a little early is buffered), a Cancel Window Start (dodge or guard may cancel from there), Stamina Cost, Poise Damage, an optional own Hitbox and a Montage Section name. A combo can Loop;
• Fire Modes for ranged weapons: delivery (hitscan or projectile), ability, fire interval, burst count, automatic, pellets per shot (shotguns), base spread, spread per shot, recoil, magazine size, reload time, an Ammo Item, range with falloff, projectile speed, radius, gravity and pierce. The Light input fires when a weapon has no light combo, and the Heavy input likewise;
• Can Block and Can Parry permissions, and an optional Block Damage Multiplier override;
• a Weapon Presentation (soft reference), and a Melee Hitbox.

13.7.2 Per-ability real-time rules

On an ability, Action Rules → Override lets you set the delivery (melee, projectile, hitscan, area, direct, self), the hitbox, windup, active time, recovery, cancel window, cooldown, stamina, gauge cost, poise damage, reach, projectile speed, radius, gravity, homing and pierce. Leave it off and the derived rules from the rules asset's Derived Ability Rules apply (melee range 2.2 m, windup 0.35 s, recovery 0.45 s, a cooldown from a base plus the resource cost).

13.7.3 The AI

Enemies, and companions nobody plays, are driven by URSEActionAIController: one real-time AI with the same intelligence dial (0 to 1) as the other modes. It thinks on a throttled cadence (0.6 s at intelligence 0 down to 0.25 s at 1, staggered across units), scores options with the shared utility brain plus real-time terms (travel time, windup to interrupt, stamina reserve), samples where to stand (rings, distance, danger, flanking, cover, line of sight, retreat, the combat area), and has a reactive layer that answers telegraphs and incoming projectiles with a parry, a block or a well-timed dodge. The reaction chance runs from 5 percent at intelligence 0 to 90 percent at 1, and reaction time and timing error follow it. Combat roles act in real time: tanks intercept and guard, snipers keep their range, controllers disable first, supports heal and buff, berserkers press. See Enemy AI and adaptive difficulty.

13.7.4 Party orders

Companions follow live orders: Free, Follow, Attack My Target, Hold Position, Defend Me. The order wheel opens on G (or keys 1 to 5). Switch Character hands control to another member, and the one left behind is driven by the AI with its order. Orders go through the command bus, so Co-op Rules → Companion Orders decides who may order whom.

13.7.5 Camera and feel

The camera has three profiles (Combat Camera, Aim Camera, Lock On Camera) with a collision probe and a trauma shake, blended over Camera Blend Seconds. Feel settings give hit-stop (their own time only, never the world's, so co-op is safe), shake on hits dealt, taken and heavy, dodge afterimages, bursts for hit, block and parry, a muzzle flash and a shot color. See Camera and battle presentation.

13.7.6 Finishers

A kill or stagger by a player can play a finisher, a paired animation between attacker and victim from the Animation & FX Library's paired clips. Players choose Off, Sometimes or Always in Options → Finishers. It never changes who wins and is skipped when no pair fits. See Character visuals and animation.

13.7.7 Co-op

The host runs the battle. Guests see it live and claim the hits of their own character. Hit claims are validated by the host (the action, the active window plus a latency tolerance, the reach plus a tolerance, once per victim). The tolerances, the position history length and the mirror rate are rules (Network section of Action Battle), and a guest's predicted dodge is smoothed rather than snapped (Dodge Reconcile settings). Action encounters stay live in co-op; they are never converted to turn-based. See Co-op and online.

13.7.8 Make a sword game or a shooter

A sword game:

1. Foundation preset Action: Swords.
2. Give each class a weapon: duplicate Sword, Dagger or Greatsword, tune the combo steps, link it from an equipment item.
3. Build an animation style in the Animation & FX Library, apply it to your characters, then run Dress My Abilities so combo, dodge, block and parry clips fill the action animation slots.
4. New Action Battle: Melee, bounded area, enemies, Simulate until it reads Fair, Create.
5. Tune the feel: parry window, dodge i-frames, poise, stamina.

A shooter:

1. Foundation preset Action: Shooter.
2. Choose Rifle, Pistol, Shotgun or Bow. Set Ammo Item on the fire modes for a limited reserve.
3. Put cover in your level (the simulator scatters its own from Sim Cover Count).
4. New Action Battle: Shooter, an open fight for roaming enemies, Simulate.
5. Tune aim assist, lock-on range and HUD layout.