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.