26. Editor tools

In short: you build a game with RPG Saga Engine in the editor, not in code. RPG Saga Studio is the front door, the Configurator holds every setting, the Create New wizards and visual editors make content, Content Import reads spreadsheets, and a set of testing tools (battle simulator, Balance My Campaign, test rooms, the battle launcher) keep the game honest. This chapter is the map of all of them.

26.1 Basics

26.1.1 The menu

The RPG Saga Engine menu in the editor's menu bar is short on purpose:

Some tools appear only where they apply. The Encounter Layout toolbar button shows when a Tactics zone or an ATB stage is selected. Populate Zone Here shows when you right-click something in the viewport. Character actions show on Character assets. To see everything everywhere, tick Show advanced tools everywhere in the Studio.

First step for almost any problem: run Validate All Data and read the Message Log. It names the asset that is wrong.

26.1.2 RPG Saga Studio

The Studio is the table of contents of your game. One window shows every step, organized in four layers from the bottom up:

A green First steps panel at the top lists nine steps for a new project and ticks them by itself as the project shows they are done: install the mannequin, choose a foundation, choose a UI style, play the starter slice, create a character, create a battle, scan an asset pack for interiors, translate with AI, and read the Getting Started guide.

Start at any layer. The starter set already fills the layers below.

Explanations. The switch in the Studio's top right corner sets how much help you see: Beginner (the default, a "Why it matters" panel on every page), Normal (tooltips and ? buttons) or Expert (bare fields). The help texts live in a data table (Studio → Help Table), so you can rewrite them for your team or translate them.

Your first character. Content → New character is a wizard of seven steps with a live 3D preview: who it is (Hero, Recruitable unit or Enemy), what to start from (an archetype is recommended), how it looks, which class, what it can do, where it appears, and a summary. Create stays disabled until every problem is fixed, and the reason is written at the bottom of the window. At the end press Test in battle: a notification shows the win rate of a few simulated battles, with a link to the full report. No level needed.

Archetypes. Content made from an archetype follows it: every field you did not change comes from the archetype. An inherited field is greyed with from archetype X, and a field you changed has Reset to archetype. When you save an archetype that content follows, a notification offers Review changes: an update list shows each asset and what would change, with your own values marked as kept. Nothing changes by itself.

Plugin templates. Everything shipped under /RPGSagaEngine is a template. The Studio never edits it in place, because a plugin update would replace your changes. Press Create a copy in the project and the copy goes next to your asset and your asset switches to it. The Studio's wizards always create assets in your project folders.

Character sheets and asset sheets. Double-clicking a Character, Ability, Item or Archetype opens a sheet: header, buttons (Test in battle, Add to party, Make recruitable, Make enemy), tabs, Simple / Advanced, and a ? by each field. Right-click an asset for RPG Saga: Open Sheet or RPG Saga: Open Generic Editor. The generic editor is always there.

26.1.3 The Configurator

One window with every setting of the framework. It replaces navigating the Project Settings sections one by one.

• Top bar: each map in Test Maps has Open and Play buttons (Play starts a Play In Editor session without changing the edited level).
• Left tree: Settings groups every settings class by domain. Rules Profiles lists the profile assets, with their inheritance (for example Default, then Boss). Tools holds the Battle Simulator, Content Import, the Progression Designer and other tools.
• Right panel: the selected section's details. Changes are written to the config file at once, like Project Settings. Reset section to defaults and Open in Project Settings are here too.
• Bottom: validation. It runs IsDataValid on every settings section and rules profile, and optionally on every data asset. Click a problem to jump to its row.

A rules profile is a data asset that overrides some rules (battle, grid, AI and so on) for one zone, battle or boss, or for the whole game. Create one with New profile, add overrides section by section, and set a default. A profile with a parent inherits everything it does not override.

26.1.4 Create New wizards

A wizard is a short form that makes a valid, ready-to-use data asset in your project. Open one from the Content Browser (right-click a folder, RPG Saga, then the type), from Advanced tools → Create New, or from Configurator → Tools → Create New.

The name is the asset's id (letters, digits, underscores). The folder is proposed from Content Import → Types, so wizards and the importer agree on where content lives. New assets can only go into your project's content, not the engine or the plugin. Create checks the asset with the same validation as saving, and if anything fails nothing is left behind.

26.1.5 New RPG Project

Advanced tools → New RPG Project... (or the Studio card Set up the project) prepares a project in one step. You choose a content root, a genre preset (JRPG with ATB, turn-based by rounds, turn-based timeline, Tactics only, or Hybrid), a UI theme and visual style, game modes and input contexts, languages, the maps to create, a starter party and optional starter content, and whether to install the mannequin kit. The right side shows the plan: every asset it will create and every setting it will change. Apply creates the starter party, a dialog, battles, a main menu map and a first map, then writes the project settings into your Config/Default*.ini files. Nothing is written into the plugin.

26.1.6 Visual dialog and quest editors

Double-click a Dialog or Quest asset.

• Dialog editor. A graph with a green Dialog Start node. Right-click to add a Line, Choice, Branch, Effect, Cue, Jump or End. Drag from a pin into empty space to add a connected node. Find searches ids, lines and speakers. Issues lists every validation problem. Auto Layout arranges the graph. Import Script / Export Script use the screenplay format of the content pipeline. Play from Here plays the dialog in Play In Editor from the selected node.
• Quest editor. Quest Start, Stage nodes with objectives, and Outcome nodes (success green, failure red). Each transition is an output pin labelled with its conditions. A stage with no transitions continues to the next stage in the list. Right-click a stage for Make Start Stage. Import JSON / Export JSON read and write the quest as a content row.

Node positions and comments are saved as editor-only data. They never change how the dialog plays and are not in cooked builds.

26.1.7 Character actions

Three one-click actions on a Character asset, from its right-click menu (RPG Saga: Character Actions), the sheet or the generic editor:

Undo removes what was placed in the level. A second run makes new assets with a free name and never overwrites yours.

26.2 How it works

26.2.1 Content Import: spreadsheets in, data assets out

Write content in spreadsheets (CSV) or JSON, and import it. The pipeline creates or updates the data assets, never deletes anything, and an export followed by an import changes nothing.

Open Configurator → Tools → Content Import:

1. Choose the Sources: a folder, or files separated by ;.
2. Press Dry run. The report lists every asset that would be created or updated, field by field, and every problem with its file, line and column.
3. Fix the sheets, and run the dry run again until it shows no errors.
4. Press Apply and confirm.

File rules: one sheet per type, named after the type (Abilities.csv, Classes.csv); UTF-8; the separator is detected from the first row; the first row is the header and the Id column is required; lines starting with # are comments; long lists go in child sheets (Classes.Abilities.csv, Shops.Stock.csv, Encounters.Enemies.csv, Quests.Stages.csv). Dialogs are written as screenplays (<Id>.dialog.txt). Export, Write templates and Write example produce a starting point.

The same from the command line, for example in a build pipeline:

UnrealEditor-Cmd MyGame.uproject -run=RSEContentImport -Source=<folder> -DryRun
UnrealEditor-Cmd MyGame.uproject -run=RSEContentImport -Source=<folder>
UnrealEditor-Cmd MyGame.uproject -run=RSEContentImport -Export=<folder> [-Format=csv|json|bundle]

The exit code is 0 only with no errors.

26.2.2 The AI workflow

Because all content is data, an AI assistant can write it. Export AI pack writes, from your project, one folder per content type with a PROMPT.md (the task, the exact output format, every column, the valid values from your project, your balance ranges, real examples and a self-check list), an empty template CSV and a strict JSON schema. Four extra packs cover Translate, Balance, Campaign and Logic review.

1. Export AI pack, then Open AI pack folder.
2. Open Abilities/PROMPT.md, write your request under Your request, paste the whole prompt into an AI chat.
3. Save the answer as Abilities.csv in an empty folder. (Several sheets in one answer are separated by === FILE: Quests.csv lines; save it as one .txt file.)
4. Dry run, read the report, fix with Copy fix prompt if needed (it lists the errors and quotes the bad rows), then Apply.

Nothing reaches your project until you press Apply. New gameplay tags are allowed only under the roots in New Tag Roots (story flags, class, status and so on). Elsewhere an unknown tag stays an error, because those tags mean something to the engine. See Localization for the Translate pack.

26.2.3 Battle simulator

The battle simulator plays battles with no graphics and no level, AI against AI, in a fraction of a second. Test in battle on a sheet, the Estimated difficulty step of New battle and How hard is it? in New enemy all use it. It is also in Configurator → Tools → Battle Simulator, and from the command line: -run=RSEBattleSim -Scenario=<file.json> [-Out=<dir>] [-Runs=N].

26.2.4 Encounter Layout and the Gallery map

Select a Tactics Zone (with a baked grid) or an ATB Stage, then press the Encounter Layout toolbar button. The mode lets you add enemies from a palette, move them, paint deployment tiles and drop field objects directly in the level, with an Issues list that checks the layout after every edit. Keys: E / Q rotate, Delete removes, R moves an enemy to the other row, Esc returns to Select, Ctrl+Z / Ctrl+Y undo and redo (a whole brush stroke is one step). For Action encounters the mode draws the combat area around the encounter trigger.

Drag a Character asset into a level to get a Character Preview: its look, idle animation, and its class, stats at a preview level and abilities in Details. Convert to NPC turns it into a talkable NPC.

A Gallery map shows everything your project contains, row by row. The plugin does not ship one. Build your own with unreal.RSEGalleryBuilder.build_gallery_map("/Game/MyGame/Maps/L_Gallery") or the Build Gallery Map Editor Utility function.

26.2.5 Balance My Campaign

Checks a whole campaign's difficulty in one click. It plays every encounter of every progression zone with the simulator, flags what is off, proposes the smallest data changes that fix it, verifies each proposal, and applies the ones you tick as one undoable step.

1. You need a campaign asset (RSECampaignProgressionData, the one the Progression Designer uses): zones in order, each with its encounter pool and key encounters, target levels, and the standard party. Optional Alternative Parties test other compositions.
2. Advanced tools → Balance My Campaign... → pick the campaign → Run.
3. Read the flags and the proposals, tick the ones you want, press Apply selected. Save the changed assets when you are happy. Edit → Undo reverts the whole apply.

What it flags: too easy or too hard (win rate outside the band of the encounter's kind: normal, elite, key, boss, ultra), too long or too short, timeouts (stalemates), one-shots, ability cliffs (an enemy class learns an ability inside a zone's level range), class outliers, and boring or grindy zones. It never touches assets with Balance Locked ticked, the party's own characters, enemies shared with encounters outside the campaign, or classes outside the standard set, unless you allow it. The same data, options and seed always give the same result. Every run writes Saved/Balance/<date-time>_<campaign>/report.md and report.json. Bands and step sizes are in Project Settings → RPG Saga Engine → Balance.

From the command line:

UnrealEditor-Cmd MyGame.uproject -run=RSEBalanceCampaign -Campaign=/Game/MyRPG/Data/Progression/DA_Campaign_Main
    [-Analyze] [-NoIterate] [-Iterations=3] [-Runs=40] [-Seed=6800] [-Apply] [-FailOnFlags]

-FailOnFlags exits with code 2 while the standard party still has flags: a gate for "the campaign stays balanced".

26.2.6 Test rooms and the battle launcher

A test room is a small map that exercises one area of the framework, with a smoke test that plays it and fails when something does not happen. Rooms are data assets of type RSE Test Room Definition (DA_Room_<Name>): Room Id, Map, Description, Smoke Script, Timeout Seconds, Presets and Needs Network. The plugin ships rooms for interactions, traversal, interiors and the Action arena, under /RPGSagaEngine/Examples/TestRooms.

• Open one: Advanced tools → World → Test Rooms (Open or Open + Play), or in play RSE.Rooms.Go <RoomId> and RSE.Rooms.List.
• Run the tests: in Session Frontend → Automation, run RSE.Rooms (one test per room) or RSE.Rooms.Definitions.
• Smoke scripts: one line each. A line is a console command or wait <seconds>, waituntil <state> [timeout], assert <state>, assertnot <state>, shot <name>. States include battle, exploration, results, dialog, scene, ready, freebattle, playerturn, action, inside and outside. Run a script by hand with RSE.Dev.Script <file> (no spaces in the path).
• Make your own room: build a small level, create an RSE Test Room Definition named DA_Room_<Name>, fill the fields, run RSE.Rooms.<Name>. Write the script by playing: every console command you type is a script line.

The battle launcher (F10 in a running game, or RSE.Rooms.Launcher) starts any encounter in any mode with a chosen party, rules profile, AI intelligence and seed, with Restart same seed, Restart new seed and Auto-play. It is a development tool and is not in Shipping builds. In Blueprint use Start Battle, Restart Battle and Set Auto Play on the RSE Battle Launcher Subsystem.

26.2.7 The controller report

docs/product/controller-report.md is a screen-by-screen audit of gamepad-only play: front end, menus, battle modes, exploration. Each screen is marked Pass (test), Pass (review), Fixed or By design. It is kept true by automated tests (RSE.UI.Navigation.*, RSE.Input.GamepadCoverage, RSE.CommonUI.ActionBarBindings). Use it as a checklist when you add a screen of your own: focus on open, D-pad and stick navigation, confirm, back, tab switching, scrolling, and no pointer-only actions. See Platforms and performance.

26.3 Key classes and assets

Commandlets in RSEEditor: RSEContentImport, RSEBalanceCampaign, RSEBattleSim, RSETranslate, RSENewProject, RSEMapGenerate, RSEWorldTools, RSEPortraitStudio, RSECharacterPack, RSEKitScan, RSECinematic and the progression commandlet. End a command line with QUIT_EDITOR when using -ExecCmds.

26.4 Settings

See Appendix B for every property and default.

26.5 Blueprint usage

The editor tools are also nodes, for Editor Utility Blueprints and Python. Categories under RPG Saga:

• Character Actions (RPG Saga|Character Actions): the three actions above.
• Balance (RPG Saga|Balance): Balance Campaign, Analyze Campaign, Apply Balance Changes, Get Balance Summary, Write Balance Report.
• Encounter Layout (RPG Saga|Encounter Layout): Move Enemy, Add Enemy, Paint Deployment, Validate and more.
• Translate (RPG Saga Engine|Translate): see Localization.

Example: balance every night from an Editor Utility Blueprint.

1. Get Asset the campaign and make an RSE Balance Options struct (tick Iterate).
2. Analyze Campaign (Campaign, Options) → keep the RSE Balance Result.
3. Get Balance Summary → print it.
4. Write Balance Report (Result, an empty directory uses the default folder).

The same in Python:

import unreal
campaign = unreal.load_asset('/Game/MyRPG/Data/Progression/DA_Campaign_Main')
options = unreal.RSEBalanceOptions()
options.iterate = True
result = unreal.RSEBalanceLibrary.balance_campaign(campaign, options)
print(unreal.RSEBalanceLibrary.get_balance_summary(result))
unreal.RSEBalanceLibrary.apply_balance_changes(result)   # one undoable transaction

These calls block until the run ends. The window runs the same job in small time slices, so the editor stays usable.

26.6 C++ usage

Editor code lives in RSEEditor, which depends on RSECore and RSE. To add your own tool, put a module of type Editor in your project, depend on RSEEditor only if you need its helpers, and register your own menu entries with the engine's UToolMenus. A new settings class appears in the Configurator without further work:

UCLASS(Config = Game, DefaultConfig, meta = (DisplayName = "My System"))
class UMySystemSettings : public URSEDeveloperSettings
{
    GENERATED_BODY()
public:
    UPROPERTY(Config, EditAnywhere, meta = (ClampMin = "0")) float Radius = 500.f;
#if WITH_EDITOR
    virtual EDataValidationResult IsDataValid(FDataValidationContext& Context) const override;
#endif
};

The class comment becomes the description in the Configurator. Until you put the class in a group (Project Settings → Editor → RPG Saga Engine Configurator → Groups) it sits under Other. The test RSE.Editor.Configurator.EveryClassHasGroup fails for a class with no group. See Extending the plugin.

26.7 Advanced

• Studio commands for scripts. RSE.Studio.ExportTemplateManifest writes the list of shipped data assets that Validate All Data compares against. RSE.Studio.Screenshot <Hub|NewCharacter|Sheet|AssetSheet|Page|PropagationDemo> <File.png> [...] renders a Studio page to a picture without a window (needs a renderer: -RenderOffscreen, not -nullrhi). The file path must not contain spaces. -NoRSEStudio keeps the Studio closed at startup.
• Quiet automation. The Studio never opens by itself when the editor runs unattended, in a commandlet or in automation.
• Commandlet rendering. Generate Map and the Portrait & Icon Studio render the level, so from the command line add -AllowCommandletRendering and do not use -nullrhi.
• CI recipe. In a nightly build: -run=RSEContentImport -Source=... -DryRun (content), -run=RSEBalanceCampaign ... -FailOnFlags (balance), -run=RSETranslate ... -Import -Policy=reject (translations), and the automation tests (RSE.*).
• Point wizards at your own templates (Wizards) once you have a style, so every new class, ability or item starts from it.
• Use Play from Here constantly while writing dialogs. It starts the conversation at the selected node.

26.8 Troubleshooting

26.9 See also

• Introduction and Installation and your first project.
• Core concepts: validation, the Configurator and settings.
• Characters and party, Abilities and statuses, Battle fundamentals: what the wizards create.
• World building: world tools and test rooms in context.
• Localization: Translate with AI.
• Extending the plugin.
• Product pages: docs/product/studio.md, docs/product/editors-and-wizards.md, docs/product/encounter-editor.md, docs/product/balance-tool.md, docs/product/ai-workflow.md, docs/product/test-rooms.md, docs/product/controller-report.md.