28. Troubleshooting and FAQ
In short: most problems show up in Validate All Data and in the Output Log. This chapter collects the common symptoms with their causes and fixes, answers the questions people ask first, and lists the logs and debug console variables that help you look inside. Each chapter also ends with its own troubleshooting table for problems specific to its system.
28.1 Basics
28.1.1 Where to look first
- RPG Saga Engine → Validate All Data. It checks every setting, rules profile and data asset. Read the Message Log (RPG Saga Engine Validation). Most content problems name the asset that is wrong.
- The Output Log (Window → Output Log). Framework messages come from categories that start with
LogRSE. Filter onRSE. - The chapter for the system you are using. Its Troubleshooting section lists what that system does wrong most often.
- Support. Use the Support link on the plugin's Fab page. Include the Output Log and the Validate All Data results.
28.1.2 Turn up the logging
The framework has a log category per domain. Set one to verbose from the console, for example Log LogRSEBattle Verbose, or in DefaultEngine.ini. Categories you will reach for: LogRSECore, LogRSESave, LogRSECommands, LogRSEExploration, LogRSEBattleStart, LogRSEBattleFlow, LogRSEAI, LogRSEDialog, LogRSEQuests, LogRSEPuzzle, LogRSEEncounter, LogRSETravel, LogRSEPerf, LogRSEPlatform, LogRSEOnline, LogRSENet, LogRSEContentImport, LogRSETranslate.
Debug console variables, all named RSE.*. The ones most worth knowing:
| Variable or command | Shows |
|---|---|
RSE.Commands.Log 1 | Every command the bus processes |
RSE.Net.LogTraffic 1 | Every state section and command sent over the network |
RSE.AI.Debug 1 | The AI's option scores |
RSE.Narrative.Trace 1 | Effects as they run |
RSE.Quests.Trace 1 | Quest evaluation |
RSE.Dialog.LogConditions 1 | Which dialog conditions held |
RSE.Dialog.ShowNodeIds 1 | Node ids in the dialog box |
RSE.Time.Trace 1 | Time of day changes |
RSE.Interaction.Debug 1 | Interaction targeting |
RSE.Encounter.Debug 1 | Roaming enemies and random battle checks |
RSE.NPC.Debug 1 | NPC schedules and behaviour |
RSE.Difficulty.Log 1, RSE.Difficulty.Override <value> | Adaptive difficulty changes, and a forced value |
RSE.Battle.AutoPlay 1 | The AI plays the party too, for watching a battle |
RSE.Battle.Presentation.Speed <n> | Battle presentation speed |
RSE.Seed.World <n> | Fix the world seed to reproduce a run |
RSE.Input.Device Gamepad|Keyboard | Force the prompts to a device without a controller |
RSE.Language <culture> | Switch language while playing |
RSE.Save.SimulateFault NoSpace|Corrupt|SignedOut|Failed | Make saving fail to see the messages |
RSE.Visual.DeckPreview 1 | Preview the Steam Deck profile |
The complete list is Appendix C. Debug commands are not in Shipping builds.
28.2 How it works
A quick map of where each kind of problem lives:
| The problem is about | Look in |
|---|---|
| A value that is wrong or a rule that behaves oddly | Settings (Project Settings → RPG Saga Engine), then a rules profile that overrides it for this zone or boss |
| A thing missing or invalid in your content | The data asset, and Validate All Data |
| Something that does not start (a battle, a dialog, a puzzle) | The conditions and effects on it, and the Output Log of its system |
| A guest in co-op sees something different | State sections and commands. See Co-op and online |
| A look or an animation | The look and body preset, the character pack importer, the Animation & FX Library |
| A tool that does nothing | The open level, the selected actor, the Output Log, or Advanced tools menu entry |
28.3 Key classes and assets
Nothing to create here. The assets named below are the ones most often at fault.
| Asset | Why it matters when something is wrong |
|---|---|
| Encounter | A battle needs its mode, its enemies and a matching zone or stage in the level |
| Tactics Zone | Needs a baked grid |
| Rules profile | Can silently override a value you thought was global |
| Character (Look, Body preset) | Missing body presets show as grey capsules |
| Foundation and Game Terms | The words and stats everything else uses |
28.4 Settings
- Project Settings → RPG Saga Engine → Features: switch a system off (or on). A disabled system's menus, pages and nodes disappear, which is a common reason for "my X is missing".
- Project Settings → RPG Saga Engine → Commands: Log Refused Commands is on by default.
- Project Settings → RPG Saga Engine → Options → Default Language and Languages.
- Editor Preferences → Plugins → RPG Saga Studio: whether the Studio opens at startup, and Show advanced tools everywhere.
28.5 Blueprint usage
Two Blueprint habits that save hours:
- Print what the framework sees. Bind to a subsystem event (for example On Quest Started or On Encounter Ended) and Print String the argument. It tells you whether the framework fired the event at all.
- Check feature and authority first. Is Feature Enabled (RPG Saga|Features) and Has Game Authority (RPG Saga|Commands) explain many "it works in the editor but not for the guest" cases.
28.6 C++ usage
Use the logging the framework uses. Define a category per domain and write to it, so your messages sort with the rest:
DECLARE_LOG_CATEGORY_EXTERN(LogMyBounties, Log, All);
UE_LOG(LogMyBounties, Warning, TEXT("Bounty %s has no target tag."), *GetNameSafe(Bounty));Add a debug switch as a console variable named for your domain, outside Shipping builds:
static TAutoConsoleVariable<int32> CVarBountyDebug(TEXT("MyGame.Bounties.Debug"), 0, TEXT("1 = log every bounty check."));28.7 Advanced
28.7.1 Reading a bug report
Ask for: the engine version and the plugin version; the Output Log; the Validate All Data results; whether it happens in a fresh project that has only the plugin and the starter content (if not, it is your content); whether it happens in single player and in co-op; and the exact steps. The scripted runners help you reproduce: RSE.Dev.Script <file> plays a list of console commands, and RSE.Rooms.<Name> plays a test room.
28.8 Troubleshooting
28.8.1 Installing and starting
| Symptom | Cause and fix |
|---|---|
| The plugin does not load, there is no RPG Saga Engine menu | It is not enabled: Edit → Plugins, search RPG Saga, tick it, restart. The plugin is for Unreal Engine 5.8 and the editor and game run on Windows (Win64). The Output Log (LogPluginManager, RSE) names the module that failed. |
| "Missing or built with a different engine version" or "would you like to rebuild?" | The copy has no compiled binaries for this engine (a zip, or a copy from another machine). Install it from Fab with Install to Engine (it comes compiled), or rebuild: the project must be a C++ project and you need Visual Studio 2022 with Game development with C++. |
| Two copies of the plugin | It must be installed once, in the engine or in your project's Plugins. Remove one and restart. |
| The Studio does not open at startup | Don't show at startup is ticked, or the editor started with -NoRSEStudio, or it runs unattended. Open it with the Studio toolbar button. |
| I cannot find a tool that the documentation mentions | The menu is short. Everything else is under RPG Saga Engine → Advanced tools, and some tools appear only where they apply. Tick Show advanced tools everywhere. |
| I cannot see the plugin's assets | Content Browser Settings → Show Plugin Content. They are under RPG Saga Engine Content. |
| An asset is read-only, or the Studio says Create a copy in the project | Plugin assets are templates. The Studio never edits them in place. Press Create a copy in the project. |
| Validate All Data warns that a plugin asset was "changed locally" | Undo the change (or reinstall the plugin) and make your own copy instead. |
28.8.2 Characters and art
| Symptom | Cause and fix |
|---|---|
| Characters are grey shapes or capsules | The plugin ships no Epic content, so characters name a body preset your project must define. Run RPG Saga Engine → Advanced tools → Install UE Mannequin Kit (or tick Install Mannequin Kit in the New RPG Project wizard). Files already in your project are never overwritten. |
| Missing packs, references to assets that are not there | Third-party packs are not included. Validate All Data lists the assets with missing references. Add the pack again in the same folder, or run the character pack importer and the Animation & FX Library on the packs you have. Running them again updates the same assets. |
| A character from my own model is invisible, tiny or twisted | Set Target Height, check that the mesh is a rigged skeletal mesh, and use the pack importer with a tuned profile for unusual bone names. Rigs exported in meters are corrected automatically. See Character visuals and animation. |
| No portraits or icons | The plugin ships no rendered portraits. After installing a body, run Generate Portraits & Icons once. It needs a renderer. |
| A weapon sits wrongly in the hand | Fit it with the weapon tools. See Weapons. |
28.8.3 Battles
| Symptom | Cause and fix |
|---|---|
| The Tactics grid does not show | The zone is not baked: select it and press Bake Grid (and again after you change the level under it). The default Grid Visual Mode is a decal that needs the deferred renderer: with the forward or mobile renderer set it to Tiles. The grid shows only during a battle. Tiles missing under grass or small rocks is intended. Tag an actor RSE.GridIgnore to leave it out on purpose. |
| Walking into a battle site does not start the battle | The site needs a trigger, and its director needs an encounter. A Tactics encounter needs a Tactics zone, and an ATB or turn-based one an ATB stage, in the level. Only one battle runs at a time. Save the level and play again: an unsaved new encounter asset is lost if the editor closes. |
| A unit starts on the wrong tile, or the log warns that a unit moved | The encounter was laid out for another zone, or the zone was baked again afterwards. The battle moves the unit to the nearest free walkable tile. Fix it in Encounter Layout Mode. |
| Battles are too easy or too hard | Use Test in battle, the Estimated difficulty step of New battle, and Balance My Campaign. The AI adapts its intelligence, not its stats. Set per-zone or per-encounter limits if needed. |
| A battle does not use the mode I expected | A mode override or a co-op conversion is in effect. Check the encounter, the rules profile and Co-op Conversion. See Battle fundamentals. |
| Saving is refused | Saving is blocked in battles, scenes, dialogs and inside volumes marked "no saving". Save points and the save item work everywhere else. |
28.8.4 World and maps
| Symptom | Cause and fix |
|---|---|
| Map generation fails or the map is empty | Generate Map and the Portrait & Icon Studio render the level, so they need a GPU renderer. In the editor it just works. From the command line add -AllowCommandletRendering and do not use -nullrhi, or pass -NoCapture to write only the map data. "The level cannot be rendered here" means exactly this. Save the level first. |
| The explorer falls through a bridge or floor | The mesh has no collision the character can stand on. Give it collision, or put an invisible walkable surface over it. A safety net (Exploration → Fall Recovery) puts an explorer back where it last stood on solid ground, and Blueprint can react with On Explorer Recovered. |
| Populate Zone places nothing, or everything in one corner | It needs a progression zone with enemies and a walkable area. With a navmesh only reachable places are used. If the level has none, Apply adds a Nav Mesh Bounds Volume (or press Add NavMesh Volume). Nothing is placed on or near a Tactics zone or a classic stage. |
| A door, chest or lever does nothing | Check its conditions and effects, the interaction library settings and RSE.Interaction.Debug 1. See Exploration. |
28.8.5 Text and languages
| Symptom | Cause and fix |
|---|---|
| The game shows English although I chose another language | The game starts in English until the player picks a language or you pass -culture=xx. The list offers only cultures with a compiled translation. Packaged games need the cultures in Packaging → Localizations to Package. |
| Editor or menu texts are English only | The plugin ships in English. Translate its own target with Translate with AI. See Localization. |
| A screen shows the wrong word for "Party", "Magic" or "Lv" | The vocabulary comes from Game Terms. A fixed word you typed does not follow the terms. Use {Term.<Id>}. |
| The translation import refused my file, or the compile failed | The report lists each problem with its id. A missing placeholder or plural form is an error. A broken {Placeholder} fails the compile. |
28.8.6 Performance and platforms
| Symptom | Cause and fix |
|---|---|
| The game does not use the Steam Deck settings | The Deck profile is missing from your project's Config/DefaultDeviceProfiles.ini. See Platforms and performance. -dp=SteamDeck forces it on any PC. |
| Text is too small on the Deck | Built-in screens never draw below UI Theme → Minimum Font Size. In your widgets use the theme fonts. |
| Meshes look blocky on the Deck | Nanite is off in the Deck profile. Give heavy meshes LODs. The content budget warnings point at the worst offenders. |
| Low quality still has heavy shadows | Project Settings → Rendering → Shadow Map Method is overriding scalability. Put it back to the default. |
| An Android or iOS build fails | Mobile is not verified, and the descriptor allows Win64 only. |
28.8.7 Co-op and online
| Symptom | Cause and fix |
|---|---|
| The online service is not available | The provider's subsystem is not loaded: the engine plugin is not enabled, DefaultPlatformService is not set, Steam is not running, or the game started with -nosteam. With Fallback To LAN on, the game uses LAN. |
| LAN finds nothing | Same subnet, and the firewall must allow UDP for the beacon port 14001 and the game port 7777. |
| The host is running a different version | Set the same Game Version on both builds. |
| My system works for the host but not for guests | Its state is not a state section, the owner never marks it changed, or its actions are not commands. See Co-op and online. |
28.9 FAQ
What is RPG Saga Engine? A framework for role-playing games in Unreal Engine 5.8: grid tactics, free-movement live tactics, active-time, turn-based and real-time action battles on the same characters and abilities, plus exploration, time and weather, living NPCs, dialog, quests, puzzles, items, shops, saves, maps and an adaptive enemy AI. You build your game with editor tools and data.
Do I need C++ or Blueprints? No for a complete game made from the built-in systems. Blueprints are for what the framework does not do (a custom condition, effect, AI rule, interactable or screen). C++ source is included for programmers. See Extending the plugin.
Where do I start? Installation and your first project: install, open the Studio, make a character, make a battle, play it. Leave the Studio's Explanations on Beginner.
What kind of games can I make? Classic menu battle RPGs, tactical RPGs on a grid, hybrids that use both, and free-movement turn-based tactics on the live map. The foundation presets start you in a genre (JRPG Classic, Tactics, Dark Fantasy, Sci-fi RPG, Post-apocalyptic, Steampunk, Empty).
Can one game use several battle modes? Yes. Every encounter names its own mode, and the same party, classes, abilities and items work in all of them. Each ability has rules per mode.
Is there multiplayer? Co-op, yes: two to four players for exploration, story and live battles, on LAN, Steam and Epic Online Services through one interface. Limits: Steam and EOS were tested on a local network only, four-player sessions under bad network conditions and hosting on a Steam Deck are not tested, and grid Tactics and ATB battles become live battles in co-op. Competitive PvP is not in this release. See Co-op and online.
Which platforms and engine versions? Windows (Win64) for the editor and the game, with the Steam Deck as the minimum hardware target. Unreal Engine 5.8. Mobile (touch controls, phone UI) and consoles are not supported yet. See Platforms and performance.
What content is included? A complete, balanced starter set (classes, heroes, abilities, items, enemies, zones, shops and battles in every mode), an example map and main menu, starter content for each foundation preset, archetypes and placeholder battle animations for the UE5 mannequin. No third-party art.
Can I use character packs from a store? Yes. The character pack importer, New Character from Mesh and the Animation & FX Library make them usable in a few clicks. A model with no animations borrows the mannequin's, retargeted.
Can I change the starter content? Yes, through copies: plugin assets are templates, and the Studio makes a copy in your project when you edit one.
Do I have to use the Studio? No. It is a friendly layer over ordinary data assets. Use any asset directly, the Configurator, Project Settings, spreadsheets, Blueprints or Python. Everything stays in sync because it is the same data.
Can I write content in spreadsheets, or with an AI assistant? Yes. Content Import creates and updates every kind of data from CSV or JSON, with a dry run first, and never deletes anything. The AI workflow exports prompts generated from your own project. See Editor tools.
How do I balance my game? Every battle can be simulated without graphics. Use Test in battle, the difficulty estimates in the Studio, Balance My Campaign for the whole campaign, and the Progression Designer for levels, experience and money.
How does adaptive difficulty work? There is no difficulty menu. The enemy AI's intelligence moves slowly with how the player did over several battles. Stats and rewards never change, and each zone, battle or boss can set limits.
How do saves work? Save points in the world, plus an optional consumable that saves almost anywhere (not in battles, scenes, dialogs or no-save areas). A save holds the party, inventory, story flags, quests, position, world state and the AI's difficulty value. See Save and load.
Can I replace the game's screens? Yes. Every screen has a widget class in the settings. Make a Widget Blueprint on the screen's data and set it there. See User interface.
Is the game localizable? Yes. Every text is localizable, the player chooses the language in the options, and the plugin ships in English only. Use Translate with AI to add languages. See Localization.
Will a plugin update overwrite my work? No. Your content and settings live in your project. The plugin's assets are templates you copy, and the plugin's defaults apply under your settings, so anything you changed wins.
Can I sell a game made with it? Yes, under the Fab license you bought. Your packaged game includes the framework in compiled form. The plugin and its source cannot be redistributed or resold as a tool or template.
Is any included content from other companies? No. Everything that ships in the plugin was made for it. Engine content (the mannequin, basic shapes, fonts) is referenced or copied from your own engine installation. See Docs/ThirdPartyNotices.md in the plugin.
28.10 See also
- Core concepts: validation, settings and the console variables.
- Editor tools: Validate All Data, the Studio and the Configurator.
- Co-op and online and Platforms and performance.
- Glossary.
- Appendix C.
- Product pages:
docs/product/troubleshooting.mdanddocs/product/faq.md.