RaRa Systems Documentation Overview - robblofield/Tomebound-Docs GitHub Wiki

RaRa Games System Architecture Guide

System Structure and Naming Conventions

All reusable game systems developed under RaRa Games must adhere to a consistent folder structure and naming convention to ensure clarity, maintainability, and reusability across projects.

Folder Structure

Each system should be contained in a top-level folder with the format:

[RaRa_<SystemName>System]

Inside that folder:

  • Scripts/

    • <SystemName>Data/ — Contains all Data and Profile ScriptableObjects.
    • <SystemName>Runtime/ — Contains all runtime logic classes (System, Manager, etc.).
    • <SystemName>Utils/ — Contains all helper/utility scripts (Utility).

  • Scriptable Objects/

    • Stores actual SO assets created for the system (organized as needed).

  • Editor/

    • Contains editor scripts like custom inspectors or EditorWindow tools.

Script Naming Convention

All scripts must follow this format:

RaRa_<DescriptiveTitle><ScriptType>.cs

Script Types and Responsibilities

Type Description
Manager Top-level coordinator that ensures the signal chain is functional and can communicate across systems.
System Runtime logic that performs core functions.
Data Shared library-style ScriptableObject containing system-wide data.
Profile Entity-specific ScriptableObject (e.g., one per character, level, etc.).
Utility Helper scripts with no direct scene dependencies.
EditorWindow Custom UI used to configure or operate the system in-editor.

All scripts must be prefixed with RaRa_ to denote studio ownership.

Example System: Objective Tracking System

System Purpose: Track current game objectives, their completion criteria, individual item counts, and display progress via UI.

Folder and Script Structure

[RaRa_ObjectiveTrackingSystem]/
├── Scripts/
│   ├── ObjectiveTrackingData/
│   │   ├── RaRa_ObjectiveLibraryData.cs         # Data: Global objective definitions
│   │   └── RaRa_ObjectiveProfile.cs             # Profile: One per mission or level
│   ├── ObjectiveTrackingRuntime/
│   │   ├── RaRa_ObjectiveManager.cs             # Manager: Coordinates system-level communication and integrity
│   │   └── RaRa_ObjectiveTrackingSystem.cs      # System: Tracks progress and logic updates
│   ├── ObjectiveTrackingUtils/
│   │   └── RaRa_ObjectiveProgressUtility.cs     # Utility: Calculates percentages, formats progress strings
├── Scriptable Objects/
│   └── [Various instances of ObjectiveProfile and LibraryData SOs]
├── Editor/
│   └── RaRa_ObjectiveTrackingEditorWindow.cs    # EditorWindow: UI for designers to manage objectives

Script Responsibilities

Script Name Type Responsibility
RaRa_ObjectiveLibraryData Data Holds the catalog of all objectives and criteria used across the game.
RaRa_ObjectiveProfile Profile Stores a list of objectives for a specific level/mission.
RaRa_ObjectiveManager Manager Coordinates with other systems and ensures correct initialization.
RaRa_ObjectiveTrackingSystem System Tracks progress, updates counts, and notifies listeners (e.g., UI).
RaRa_ObjectiveProgressUtility Utility Calculates percentage complete and formats text for UI display.
RaRa_ObjectiveTrackingEditorWindow EditorWindow Provides designers with an editor interface for editing profiles/data.

System Flow Diagram (Objective Tracking System)

flowchart TD
    A["Objective Library Data"]
    B["Objective Profile"]
    C["Objective Manager"]
    D["Objective Tracking System"]
    E["Objective Progress Utility"]
    F["Objective Tracking Editor"]
    G["UI Renderer / HUD"]

    A --> D
    B --> D
    D --> E
    D --> G
    F --> B
    C --> D
    C --> G
Loading

This structure and naming approach ensures every system remains modular, decoupled, and easy to onboard for new developers or across projects.

Summary

This document should have presented a comprehensive understanding of how you should structure systems for RaRa Games projects, including both the philosophy behind the architecture and the practical rules that enforce it.

🎯 Core Principles

  • Modularity: Systems are self-contained and can be dropped into multiple projects.
  • Separation of Concerns: Clear distinctions between data, logic, UI, utilities, and editor tools.
  • Scalability: Folder and naming structures are standardized to support growth and onboarding.
  • Studio Ownership: Prefixing with RaRa_ asserts tool ownership and avoids namespace clashes.

📁 System Structure

  • Top-Level Format: [RaRa_<SystemName>System]

  • Key Subfolders: Scripts (with internal separation), Scriptable Objects, and Editor.

  • Scripts Categorized By Role:

    • Data and Profile: ScriptableObjects for static or instance-specific data
    • System: Executes core runtime logic
    • Manager: Oversees integration and coordination across systems
    • Utility: Reusable logic not tied to scene or object hierarchy
    • EditorWindow: Custom Unity tooling

🧠 Naming Convention

  • RaRa_<DescriptiveTitle><ScriptType>.cs — readable, unique, and meaningful

📊 Diagram Support

  • Mermaid flowcharts help to show how each component interacts, emphasizing decoupling, manager-level coordination, and UI endpoint reporting. If you can, always include a diagram in your documentation
⚠️ **GitHub.com Fallback** ⚠️