RaRa_UpgradeSystem - robblofield/Tomebound-Docs GitHub Wiki

RaRa_UpgradeSystem – Overview Documentation

System Purpose

The RaRa_UpgradeSystem manages all aspects of upgrades in Tomebound, including:

  • Permanent upgrades earned through progression (Core Upgrades)
  • Temporary upgrades found during runs (Upgrade Cards)
  • Retained gear brought into runs once unlocked (Loadout Items)

This system enables:

  • Asymmetrical builds and decision-making
  • Long-term character growth through Core Fragments
  • Designer-friendly tools for building new upgrades
  • Clean separation of runtime logic, data, and editor tooling

Upgrade Types

Core Upgrades (Permanent)

  • Unlocked between runs using Core Fragments
  • Two types:
    • Stat Boosts (e.g., +Max Health)
    • Skill Unlocks (e.g., Double Dash)
  • Persist permanently across all future runs
  • New upgrades are revealed progressively as players advance

Upgrade Cards (Temporary)

  • Drafted after levels, found in chests, or purchased from merchants
  • Three types:
    • Stat Boosts
    • Equipment Items (e.g., trinkets with effects)
    • Skill Unlocks (e.g., Arcane Sight: reveal secrets for 5 rooms)
  • Assigned to one character only β€” encouraging unique builds per lizard wizard

Loadout Items (Retained Gear)

  • Unlocked by defeating district bosses for the first time
  • Each victory unlocks a new Loadout Slot
    • 1st: Weapon
    • 2nd–4th: Items, Talismans, Trinkets, etc.
  • Players select gear from previously discovered Upgrade Cards to bring into new runs
  • Loadout items reference existing UpgradeCardProfiles and do not store new data
  • Gear effects can include stat modifiers, unique abilities, or passive buffs

Folder & File Structure

[RaRa_UpgradeSystem]/
β”œβ”€β”€ Scripts/
β”‚   β”œβ”€β”€ UpgradeData/
β”‚   β”‚   β”œβ”€β”€ RaRa_CoreUpgradeProfile.cs
β”‚   β”‚   β”œβ”€β”€ RaRa_UpgradeCardProfile.cs
β”‚   β”‚   β”œβ”€β”€ RaRa_CoreFragmentData.cs
β”‚   β”‚   └── RaRa_LoadoutItemProfile.cs
β”‚   β”œβ”€β”€ UpgradeRuntime/
β”‚   β”‚   β”œβ”€β”€ RaRa_UpgradeManager.cs
β”‚   β”‚   β”œβ”€β”€ RaRa_CoreUpgradeSystem.cs
β”‚   β”‚   β”œβ”€β”€ RaRa_UpgradeCardSystem.cs
β”‚   β”‚   └── RaRa_LoadoutUpgradeSystem.cs
β”œβ”€β”€ Scriptable Objects/
β”‚   β”œβ”€β”€ CoreUpgradeProfiles/
β”‚   β”œβ”€β”€ UpgradeCardProfiles/
β”‚   β”œβ”€β”€ CoreFragmentData/
β”‚   └── LoadoutItemProfiles/
β”œβ”€β”€ Editor/
β”‚   β”œβ”€β”€ RaRa_UpgradeCardInspector.cs

Script & SO Responsibilities

Script / SO Name Type Responsibility
RaRa_CoreUpgradeProfile Profile (SO) Defines a permanent Core Upgrade: stat boost or skill.
RaRa_UpgradeCardProfile Profile (SO) Defines a temporary Upgrade Card: includes type, rarity, effects.
RaRa_CoreFragmentData Data (SO) Tracks spendable Core Fragments for each player profile.
RaRa_LoadoutItemProfile Profile (SO) References a previously earned UpgradeCardProfile used in retained loadouts.
RaRa_UpgradeManager Manager Oversees coordination between all upgrade systems (Core, Cards, Loadout).
RaRa_CoreUpgradeSystem System Applies and tracks Core Upgrade unlocks via Core Fragments.
RaRa_UpgradeCardSystem System Handles draft logic, card assignment, and temporary effect application.
RaRa_LoadoutUpgradeSystem System Validates loadout item equip rules and applies effects at run start.
RaRa_UpgradeCardInspector Editor Custom Inspector to preview and configure Upgrade Cards.

System Flow Diagram

flowchart TD
    %% Scriptable Objects
    A1["RaRa_CoreUpgradeProfile"]
    A2["RaRa_UpgradeCardProfile"]
    A3["RaRa_CoreFragmentData"]
    A4["RaRa_LoadoutItemProfile"]

    %% Runtime Systems
    B1["RaRa_UpgradeManager"]
    B2["RaRa_CoreUpgradeSystem"]
    B3["RaRa_UpgradeCardSystem"]
    B4["RaRa_LoadoutUpgradeSystem"]

    %% Editor Tools
    C2["RaRa_UpgradeCardInspector"]

    %% Game Systems
    D1["Reward Draft UI"]
    D2["Chest Loot"]
    D3["Merchant UI"]
    D4["Upgrade Menu"]
    D5["Combat / Puzzle / Traversal"]
    D6["Loadout Equip UI"]

    %% Relationships
    A1 --> B2
    A2 --> B3
    A3 --> B1
    A4 --> B4

    B1 --> B2
    B1 --> B3
    B1 --> B4

    C2 --> A2

    B3 --> D1
    B3 --> D2
    B3 --> D3
    B2 --> D4
    B4 --> D6

Design Pillar Alignment

Pillar System Support
Player-Directed Variety Upgrade choices after every level + loadout customization
Dual-Character Synergy Cards assigned to one lizard; unique builds per character
Balanced Challenge Each upgrade type touches combat, platforming, and puzzle performance
Modular Progression & Replay Core Fragments + unlocks = long-term build personalization