Project: Catalyst AI

Technical Design Document

Confidentiality Notice

This document contains proprietary and confidential information belonging to DevRight Studios. It is intended solely for the informational use of the recipient. Unauthorized copying, distribution, or disclosure of the contents of this document is strictly prohibited.

1. Executive Summary

The Catalyst AI system is a next-generation, modular artificial intelligence framework designed to be built directly into the core project. Its primary goal is to power the dynamic, believable, and consequential non-player characters (NPCs) and companions of our flagship MMO survival RPG.

This document outlines the technical architecture and implementation plan. Our core strategy deviates from traditional, monolithic AI systems by embracing a modern, data-driven, and highly performant approach. We will leverage three key pillars:

  1. Actor-Component Model: For a clean, reusable, and encapsulated code structure. All AI functionality will be built as modular components.
  2. State Trees: For all high-level decision-making, providing a visually scriptable, debuggable, and exceptionally fast logic core.
  3. Gameplay Tags & Smart Objects: To create a world rich with interactive opportunities and a clear, data-driven "contract" between AI capabilities and their behaviors.

This approach will produce AI that is not only intelligent and reactive but also highly optimized for the demands of a large-scale, networked open world, while being accessible for designers to craft unique behaviors.

2. Core Architecture & Philosophy

The design of the Catalyst AI system is guided by three principles: performance, designer accessibility, and scalability. It is an integrated system, not a plugin.

Actor-Component Foundation

All AI agents are built upon a modular Actor-Component model. The base AIActor class is a lightweight container. Its functionality is defined by the components attached to it, such as a HealthComponent or MovementComponent. This promotes reusability and avoids monolithic classes.

StateTree-Driven Logic

The "brain" of every AI agent is a State Tree asset, executed by an AIBehaviorComponent. This moves the core logic from opaque, hard-coded systems into a visual, graph-based asset that designers can easily understand, modify, and debug.

An Interaction-Rich World

We will not make our AI omniscient. Instead, we make the world "smarter." By placing Smart Objects throughout the level, we create a global database of interaction points. An AI doesn't need to find a chair; it asks the system, "Where is the nearest available Smart Object with the AI.Interaction.RestingSpot tag?" This is fundamentally more scalable and performant.

Data-Driven Capabilities via Gameplay Tags

The "contract" between an AI's abilities and its decision-making logic is managed by a hierarchical Gameplay Tag system. A component grants an ability (e.g., TeleportComponent) and adds the corresponding tag (e.g., AI.Ability.CanTeleport) to its owner. The State Tree then checks for this tag before attempting to execute the action, ensuring a robust and error-free connection between logic and capability.

Interactive Infographic (Click to Expand)

Gameplay Simulation

AI Ally

Logic Loop

AI BRAIN
State Tree
WORLD
PERCEPTION
COMMAND
ACTION
TAG CHECK

Scenario Log:

Click "Run Scenario" to begin simulation...

3. Core Component Breakdown

This section details the initial set of C++ components that form the AI's "toolbox." Each component is a self-contained unit of functionality.

Component Name
Responsibility
Key Interactions
AIPerceptionComponent
The AI's senses.
Detects actors and Smart Objects. Reports findings to the Behavior and Targeting components.
AITargetingComponent
Manages threat and targets.
Maintains an "aggro list" and provides the current target to the State Tree.
AIMovementComponent
Executes movement commands.
Interfaces with the pathfinding system to move the actor based on requests from the State Tree.
AIBehaviorComponent
The central brain.
Hosts and executes the State Tree asset, orchestrating all other components.
AICombatComponent
Manages combat abilities.
Holds a list of available skills, manages cooldowns, and executes attacks on command.
CompanionLogicComponent
Specialized companion logic.
Handles permadeath risk assessment, social behaviors, and player command interpretation.

4. Appendix: Detailed Use Case

Use Case: `Companion Takes Cover When Wounded`

  1. Sensing: The player's companion takes damage. The HealthComponent updates its current health and broadcasts an event.
  2. Evaluation: The companion's AIBehaviorComponent is running a State Tree. An evaluator node, FStateTreeEvaluator_HealthCheck, constantly monitors the health value.
  3. Transition: The State Tree has a transition from its `FollowPlayer` state to a `FindCover` state. This transition is guarded by a condition: "Does my actor have the tag Status.IsWounded?" The Health Component adds this tag when health drops below 40%. The transition fires.
  4. Action: The `FindCover` state activates. It runs a task that asks the AIPerceptionComponent to find the nearest Smart Object with the AI.Interaction.CoverSpot tag.
  5. Execution: The perception component finds a low wall tagged as cover. The task commands the AIMovementComponent to move to that location. The companion's animation system might blend into a "limping" or "cautious" run.
  6. Resolution: Once at the cover spot, the State Tree transitions to a `HoldCover` state, where it will stay until its health is restored or a new, higher-priority event (like a direct player command) occurs.
TDD COMPLETION: ACTION ITEMS REQUIRED

The core architecture is defined. The following systems must be designed and documented to complete the TDD:

  • 1. Data & Workflow: Define the structure of **AI Archetype Data Assets** and the design of the **Loot Table** system.
  • 2. Performance & Scale: Specify the **AI LOD system** (tick rates, logic simplification) and the strategy for **Spawning & Object Pooling**.
  • 3. Debugging & Tooling: Detail the required **on-screen debug displays** and confirm the integration of visual logging tools for State Trees.
  • 4. System Interconnects: Document the data flow for the **Companion Command System** and the API for the global **Faction & Reputation System**.