17. World building

In short: a handful of editor tools turn an empty stretch of your map into playable content: a battle site, a populated zone, buildings you can walk into, interiors built from your own asset packs. Test rooms prove the framework works, and the World Partition support keeps saves, locks and battles correct in big streamed worlds. Use this chapter when you stop testing in a grey box and start building your real maps.

17.1 Basics

17.1.1 The tools at a glance

All the placement tools work the same way: choose an area, press Preview (nothing changes, markers and a report show what would happen), then press Apply. Apply is one undo step, and running a tool again on the same place or with the same group name replaces its earlier result instead of doubling it.

17.1.2 Your first battle site

1. Open your level and point the viewport at the ground where the battle should be.
2. Open the tool: in the Studio, World → New battle zone; or right-click the viewport and choose RPG Saga → Make Battle Zone Here; or Modes → RPG Saga: World Tools for the panel with every option.
3. Set the area. Drag a rectangle on the ground (left-drag while the mode is open), or click a point and pick a Size Preset (Small 8 × 8, Medium 12 × 12, Large 16 × 16, Wide 20 × 12 tiles). Use Camera Focus and Use Selection Bounds are the other two ways.
4. Pick an encounter, or a progression zone to generate an enemy group from its encounter pools.
5. Press Preview. Green tiles are walkable, dark ones blocked, blue ones are deployment tiles, red markers are enemies (the arrow is their facing), orange marks the classic stage. Problems get a pink cross.
6. Press Apply. Press Ctrl+Z if you do not like it.

You get, in the Outliner folder BattleSites/<Site>: a baked Tactics zone, its battle director (waiting for its trigger), the encounter layout (deployment tiles and enemies written into the encounter), an optional trigger over the deployment tiles, and an optional classic battle stage on flat, clear ground nearby. Give the site a name: running the tool again with the same name updates it.

17.1.3 Your first populated zone

1. Open World → Populate a zone.
2. Pick a progression zone, the area, optionally a Populate Rules asset (Content Browser → Add → Miscellaneous → Data Asset) and a shop for the trader.
3. Preview shows one labeled marker per placement and its distance from the Player Start.
4. Apply places them in the folder Populate_<Zone>. Press Re-roll and Apply again until you like the layout: each Apply first removes what the previous run of the same zone placed.

17.1.4 Your first building you can enter

1. Open Modes → RPG Saga: World Tools → Building Analyzer and press Preview. Every building is outlined in the color of its proposed mode with its door and the reason.
2. Correct any proposal in Mode Overrides or Template Overrides, then Apply.
3. Open the new interior asset's template map, replace the placeholder props (tagged RSE.InteriorPlaceholder) with your own, and put your NPCs on the RSE Interior Slot markers.
4. Play and walk to the door.

17.2 How it works

17.2.1 Battle sites and the grid on the live map

A battle zone is an ARSETacticsZone placed on your level as it is. Bake Grid traces the real ground under every tile (exact height and slope, besides the whole-step height the rules use). Units, the turn marker and every highlight stand on the measured surface. The tool previews with the same trace as Bake Grid, so what you see is what you get. Anything a character cannot stand on is skipped: surfaces that do not block pawns (grass), pawns, objects narrower than Bake Min Surface Size, and anything tagged RSE.GridIgnore.

Grid Visual Mode (Project Settings → RPG Saga Engine → Tactics Zone, overridable per zone):

• Projected (default): one decal paints the grid and all highlights onto the level. One draw call, follows slopes and steps. Needs the deferred renderer.
• Tiles: an instanced flat mesh per tile on the measured surface. For forward or mobile renderers.

Several battle sites can share a map: the player's controller switches to the site whose battle starts. When a battle starts, a unit standing off the grid or on a blocked or taken tile moves to the nearest free walkable tile, with a log warning.

17.2.2 Populate rules

Populate Zone places these kinds: random encounter areas, enemy spawners with patrol points, chests (money and loot by level, higher the farther from the Player Start, each with its own Opened flag), a save point near the Player Start, a trader NPC, and optional signposts and zone exits. The Populate Rules asset sets, per kind, a count (plus more per 100 m² up to a maximum), a minimum spacing, and a band of path distance from the Player Start. Kinds keep a distance from each other and from what is already in the level, stay away from Tactics zones and classic stages, and obey a total density cap.

Placement follows the navmesh when the level has one, so every placement is reachable. Without one, Apply adds a Nav Mesh Bounds Volume over the area and builds it. The seed decides everything: the same seed gives the same layout.

17.2.3 Populate Interactions and the living world tools

Populate Interactions places the interaction library: signposts at crossroads (their arms named after the point of interest down each road), danger warnings where a road enters a dangerous zone, chests, fires, lanterns and notes beside roads, and gathering nodes, remains and shrines in the wilds. Roads are RSE Road spline actors (any actor tagged RSE.Road also counts). Without roads, the navmesh paths between points of interest are used. Each interactable kind has a Placement block that says where it may go, its weight, spacing and density.

The living world tools are four more entries of the Tool list in the World Tools mode:

• Populate NPCs: people who live in the area, with a schedule or a wander radius, bark pools, appearances and names.
• Place Caravan Route: a road between stops, along the navmesh or straight, looped or back and forth.
• Populate Destructibles: clusters of barrels, crates and pots where the interaction library would put them.
• Traversal Analyzer: samples the ground and proposes ladders, climbs, vaults, jumps and swim volumes. Untick a proposal's Accepted to skip it.

17.2.4 Buildings

Every building is entered in one of three ways, set on one actor placed at its door, RSE Building Entrance (ARSEBuildingEntrance):

• Real Door: the building has a walkable inside in the level. An RSE Door opens by itself when the party comes close, and an RSE Interior Volume inside brings the camera closer. Door Access can lock it behind opening hours, a key or story conditions.
• Separate Interior: nothing is behind the door. Interacting (or, with Enter On Touch, walking into the doorway) blacks the screen out for a moment and the party stands in a separate small map loaded far from the playable area. The interior's RSE Interior Exit brings the party back to the entrance's Exit Point.
• Decor: no access, optionally a line when examined (Decor Text).

The entrance finds its real door in order: a door actor next to the building, a socket of the building's mesh named with a door word ("Door", "Entrance_Front"), a door-shaped opening found by probing the facade with rays, and last the Assumed Door Side. Detect Door (button on the entrance) runs the same search. To place an entrance yourself, move and turn it so its arrow points out of the building, set Door Width and Door Height, and tick Keep Placement: the analyzer then leaves it alone. Place Exit Point puts the exit on walkable ground in front of the door, on the navmesh when there is one.

An Interior Data asset (URSEInteriorData) describes where the door leads: the map, the template, the entry point (an RSE Arrival Point id such as Entry, or an actor tag), the blackout time, Closed Phases (for example night), a Key item, story Conditions, and the texts shown when closed or locked. The ready templates (DA_InteriorTemplate_Inn, _House, _Shop, _Smithy, _Temple, _Cellar, plus Tower, Manor and Workshop) live in /RPGSagaEngine/Interiors/Templates.

Interior Rules (on the template, overridable per interior, else Buildings → Default Rules) decide how a visit behaves:

While the screen is black the exposure is set at once, so the eye never fades slowly from a sunny street into a lit room.

17.2.5 Generated interiors

Set Interior Data → Generation → Enabled and the interior is built under the blackout by one RSE Generated Interior actor in the generated-interior map (Buildings → Generated Interior Map). Inputs:

A floor is a hub (hall, common room, landing) with rooms around it, joined by stairs that hug a wall. Floors above the one you stand on are hidden (cutaway). Programs, themes and furniture are data assets under /RPGSagaEngine/Data/Interiors. Preview Interior on the actor builds any interior in the editor.

Each Furniture asset (URSEFurnitureData) names its tags, its mesh, its Front (the mesh axis it faces) and a placement rule: Against Wall, Corner, Center, Around Anchor, On Anchor, Wall Mounted, Ceiling or Free. The generator keeps doorways, stairs and each piece's front clearance free and checks that everything stays reachable. Check Furniture on the actor flags pieces facing the wrong way, off their wall, overlapping, blocking a door or unreachable.

Furniture with an interactable becomes a world interactable: fireplaces and lanterns, wardrobes, chests, beds (rest), books and letters (read, backed by lore entries), workstations (shop counter, anvil, altar) and hidden stashes. Program roles (innkeeper, cook) become NPC Places named <Interior>.<Role>, and the interior's Inhabitants put your story NPCs there.

17.2.6 Interior kits: your own packs

The Interior Kit Wizard points the plugin at the folders of a modular environment pack and builds interiors out of that pack's own pieces. You keep your packs where they are: nothing is copied, renamed or moved, and the plugin never ships them.

1. Sources: add the pack's folders and choose the language packs for the words read in names.
2. Scan: every mesh is measured (size, pivot, door and window holes found with rays) and classified. Results are cached, so a second scan of an unchanged pack takes seconds.
3. Kits: one card per kit shows the module (wall width), floor tile, wall height and thickness. Orange numbers mean pieces disagree: type the right value. Merge into, Split by Folder, Split Off Selected and Exclude Kit fix a wrong grouping.
4. Review: a table of every mesh with its kind, confidence, front, placement, interaction and kit. The Why panel explains each decision. Bulk edit with Set Kind, Set Front, Rotate Front 90, Set Placement, Set Interaction, Set Kit, Ignore, Accept. Your corrections are remembered and survive a new scan. The wizard prefers asking to guessing: low-confidence rows and unsure fronts are marked needs review.
5. Preview: a sample two-storey house built from the kit's real pieces. Click a wrong piece to fix it right there.
6. Create: writes DA_InteriorKit_<Kit>, DA_Furniture_<Kit>_<Mesh> and DA_InteriorTheme_<Kit> (with substitutions by kind). Dry Run reports without writing. Create is idempotent and keeps your hand edits unless Overwrite Manual Edits is on.

With a kit, the layout snaps to the kit's grid and the interior is built from the pieces: plain, door, window and corner walls, floor and ceiling tiles, door frames and leaves, stairs, railings, trims. A piece the kit lacks, or one that would have to stretch more than the allowed limit, becomes a box in the kit's material with a note in the log: an interior is never broken. Stairs and railings may stretch more than walls (Kind Stretch). Single-sided interior walls show their finished face to the larger room.

17.3 Key classes and assets

17.4 Settings

All in Project Settings → RPG Saga Engine. The full list is in Appendix B.

• World Tools: size presets, the walkable share a site needs, deployment tile count, generated group size, enemy spacing and area, the stage search, default Populate rules, preview colors.
• Tactics Zone: Grid Visual Mode, the projected grid's look and the bake rules.
• Buildings: default rules, blackout seconds, the generated interior map, door detection widths, exposure behavior, and Generation → Modular → Build (Build With Kit, Use Corner Pieces, Face Larger Room, Kind Stretch, Preload Timeout).
• Interior Kits: the taxonomy, output folder, scan speed, review thresholds (Review Threshold 0.6, Front Review Threshold 0.25), the kinds a complete kit should have.
• World Partition: see the next section.

17.5 World Partition

The framework works on World Partition maps. Saves, quests, locks, chests, doors, NPC places and battles survive a cell unloading and loading again, because state lives in the framework's world-state subsystem under a State Key, not in the actor.

Start on World Partition: the New RPG Project wizard has a World Partition option under Maps. For an existing map use File → Convert Level, then Fix State Keys.

Stable keys. Every object that keeps saved state (triggers, spawners, random encounter areas, traps, locks, interactables, building entrances) has a Save Key property. You do not type it: the editor assigns one when you place, paste or duplicate the object. Map Check (Build → Check for Errors) warns on a missing key and errors on a duplicate. Fix State Keys (RPG Saga Engine → Advanced tools → World, or the console commands RSE.StateKeys.Check and RSE.StateKeys.Fix) repairs the whole level, loading unloaded actors in batches. Run it after converting a map, after importing actors, and before shipping. Without a key the framework derives one from the level path and actor name, which works until you rename the actor.

Streaming and battles. Always-loaded by design: battle directors, Tactics zones, ATB scenes, zone volumes and arrival points. Put them in the persistent level. A battle keeps the cells around it loaded until it ends (Keep Battle Cells Loaded, Battle Streaming Margin, Min Battle Streaming Radius).

Data layers. Use runtime data layers for parts of the world the story changes. The effect Set Data Layer State (Unloaded, Loaded, Activated) and the condition Data Layer State drive them without code. The state is saved and applied again after a load.

Interiors. The interior level instance loads at Interior Origin, off the map. The door's cells stay loaded while the party is inside (Keep Exterior Loaded Inside, Exterior Streaming Radius). A save made inside restores the party inside. Do not make an interior map a World Partition map.

Limits. A Level Instance placed more than once shares its actors' keys. References between actors in different cells do not survive streaming; use a key, a tag or a soft reference. World Partition support covers single player and co-op hosts.

17.6 Test rooms

A test room is a small map built to exercise one area of the framework, with a smoke test: a short script that plays the room and fails when something does not happen. Rooms ship in /RPGSagaEngine/Examples/TestRooms, built from engine shapes only.

• Interactions: every interactable kind of the interaction library.
• Traversal: ladder, drop, vault, river, rope, zip-line, chasm jump and rope swing.
• Interiors: a generated two-storey house built from two kits (Timber and Station), and a shed with a real door. RSE.Rooms.Interior kit Station switches the house's entrance between the kits.
• ActionArena: the action-combat arena with three encounters and launcher presets.

Open a room from RPG Saga Engine → Advanced tools → World → Test Rooms (Open, or Open + Play), or while playing with RSE.Rooms.Go <RoomId> (RSE.Rooms.List lists them). Run the tests in Session Frontend → Automation: RSE.Rooms.<RoomId> per room and RSE.Rooms.Definitions for validity.

The battle launcher (F10, or RSE.Rooms.Launcher; RSE.Rooms.LauncherKey changes the key) tries battles in any room: an encounter, a mode override, a party, a rules profile, AI intelligence per mode and a seed. Start, Restart same seed, Restart new seed and Auto-play (RSE.Battle.AutoPlay) are its buttons. Console equivalents: RSE.Rooms.Launch <EncounterAssetName> [Mode] [Seed] [auto] and RSE.Rooms.Restart. These are development tools and are not available in Shipping builds.

Make your own room: build a small level, create an RSE Test Room Definition data asset named DA_Room_<Name>, fill Room Id, Map, Description and Smoke Script, then run RSE.Rooms.<Name>. Each script line is a console command or a word of the dev-script runner: wait <seconds>, waituntil <state> [timeout], assert <state>, assertnot <state>, shot <name>. States include battle, exploration, dialog, inside, outside, viewfloor:<N>, used:<label> and hassave. Write the script by playing: every console command you type in the room is a line of the script.

17.7 Blueprint usage

World tools are editor-only. Use them in editor utility Blueprints (or Python) under the category RPG Saga | World Tools: Plan Battle Site, Apply Battle Site, Make Battle Site, Write Encounter Layout, Check Tactics Zone, Plan Populate, Apply Populate, Populate Zone, Plan Populate Interactions. For a quick scripted battle site:

1. Editor Utility Blueprint, Make Battle Site (Request = a filled RSE Battle Site Request: site name, center, size, encounter).
2. Check the result's problems list; the result carries the plan's problems when it did not apply.

Runtime nodes you reach for:

• RPG Saga | World Partition: Set Data Layer State and Get Data Layer State on the RSE World Streaming Subsystem; Begin Battle Streaming and End Battle Streaming if you start battles yourself.
• RPG Saga | Buildings on RSE Building Entrance: Get Mode, Get Interior, Get Door, Get Exit Transform, Get Door Width, Get Door Height. On the RSE Interior Travel Subsystem: Is Inside, Are Battles Blocked.

Example, a bridge that appears after a story event: Event BeginPlay → Get RSE World Streaming Subsystem → Set Data Layer State (Data Layer = DL_Bridge, State = Activated). Better still, use the Set Data Layer State effect in a quest or dialog so the story drives it and the state saves.

17.8 C++ usage

// Walk into a building from code (host side).
if (URSEInteriorTravelSubsystem* Travel = URSEInteriorTravelSubsystem::Get(this))
{
    FText Why;
    if (!Travel->Enter(*Entrance, Pawn, /*bInstant=*/false, &Why))
    {
        UE_LOG(LogTemp, Log, TEXT("Door refused: %s"), *Why.ToString());
    }
}

// React when a World Partition cell streams in.
if (URSEWorldStreamingSubsystem* Streaming = URSEWorldStreamingSubsystem::Get(this))
{
    Streaming->OnLevelShown.AddUObject(this, &AMyActor::HandleLevelShown); // void(ULevel&)
}

Extension points: subclass ARSEBuildingEntrance in Blueprint for a custom prompt or sound; add new furniture, program and theme assets for new interior content; add a piece kind to an interior kit as a Gameplay Tag plus a taxonomy row. Python can run the placement tools headless (unreal.RSEInteractionPlacementLibrary.populate_interactions, unreal.RSELivingWorldToolsLibrary, unreal.RSEKitLibraryFunctions).

17.9 Advanced

• Command lines. UnrealEditor-Cmd MyGame.uproject -run=RSEWorldTools -Map=/Game/Maps/L_Town -BattleSite -Center=X,Y,Z -Tiles=W,D -SiteName=Gate [-Save | -SaveAs=<copy> | -DryRun] runs a tool in a build script (-Populate -Zone=<zone> -Area=... for Populate). It returns 1 when a tool reports an error. -run=RSEKitScan -Paths=/Game/PackA,/Game/PackB -Out=Saved/pack.csv [-Create -Output=/Game/Interiors] scans packs and creates kit assets; -Golden=labels.csv compares the result with your own labels.
• Map generators in Python. RSE World Build Library (unreal.RSEWorldBuildLibrary) offers Create Landscape (a heightmap of little-endian uint16 heights plus per-layer weightmaps), Find Or Create Layer Info and Add Instances (a hierarchical instanced mesh component with optional cull distances and collision), run headless with -run=pythonscript.
• Converting older themes. Right-click a theme in the Content Browser → RPG Saga: Convert Legacy Kit makes a kit asset from its four meshes and measures the wall.
• Substitutions. A theme's Substitutions swap pieces by kind (every bed becomes one of this pack's beds, weighted). Programs and interaction sets keep asking for kinds; the theme decides which pack answers. Give a replacement the tag it replaces so chairs, residents and the checker still find it.
• Performance. Entering a kit-built interior preloads the kit's meshes in the background during the blackout (up to Preload Timeout). Every floor and mesh type is one instanced component. Skip Keep Exterior Loaded Inside when memory is tight; the way out then waits under the blackout until the door's cells have streamed back in (at most Exit Stream Wait Seconds).
• Networking. Interiors and World Partition streaming run on the host. See 22-networking.md.

17.10 Troubleshooting

17.11 See also

• 14-narrative.md for the effects and conditions that drive data layers and locked doors.
• 15-exploration.md for interactions, travel and save points.
• 09-battle-tactics.md and 08-battle-common.md for the zones, encounters and battle modes the sites use.
• 25-editor-tools.md for the Studio and the wizards.
• Product pages: docs/product/world-tools.md, buildings.md, interior-kits.md, test-rooms.md, world-partition.md.