Companion System

v2.0.0

Example Workflows

Production-ready implementation patterns for common use cases

RPG Party System

A classic RPG party with up to 3 companions following in V-formation, each with unique commands.

Scene Hierarchy:
├── Player (Character + CompanionOwnerAdapter)
├── CompanionManager (+ CompanionRemember)
└── (Companions spawn at runtime)

ScriptableObjects:
├── Definitions/
│   ├── Warrior_Companion.asset      (CompanionDefinition)
│   ├── Mage_Companion.asset
│   └── Healer_Companion.asset
├── Profiles/
│   ├── MeleeFollowProfile.asset     (InnerRadius: 3, RunSpeed: 6)
│   └── RangedFollowProfile.asset    (InnerRadius: 5, RunSpeed: 5)
├── Commands/
│   ├── Cmd_Attack.asset
│   ├── Cmd_Defend.asset
│   └── Cmd_Heal.asset
└── Settings/
    └── CompanionSettings.asset       (MaxActive: 3, Formation: VShape)

GC2 Trigger Setup

Recruit Party Member

Trigger: On Interact (NPC) → Summon Companion (Warrior_Companion) → Set Companion State (Following). The companion spawns behind the player and begins following.

Issue Battle Command

Trigger: On Key Press (1/2/3) → Issue Command (Cmd_Attack). Commands validate against the CompanionDefinition's CommandSet — a Healer silently ignores Attack commands.

Wait Here / Follow Me

Trigger: On Key Press (H) → Group Set State (Waiting). Press again → Group Set State (Following). Use Any Companion In State condition to toggle.

Pet / Familiar System

A single pet that follows the player, visits interest points when idle, and responds to simple commands.

ScriptableObjects:
├── Definitions/
│   ├── Cat_Pet.asset
│   ├── Dog_Pet.asset
│   └── Bird_Pet.asset
├── Profiles/
│   └── PetFollowProfile.asset        (InnerRadius: 1.5, WalkSpeed: 2)
├── IdleProfiles/
│   └── PetIdleProfile.asset          (IdleDelay: 3, EnableInterestPoints: true)
└── Settings/
    └── CompanionSettings.asset        (MaxActive: 1, Formation: Line)

Key Configuration

Idle Behavior

Set IdleDelay: 3s and enable Interest Points. Place CompanionInterestPoint components on objects like food bowls, beds, or toys. The pet will wander to them when the owner stands still.

Owner Awareness

OwnerAwarenessBehavior makes the pet look at the owner while idle and react to sprinting (matching speed with a brief delay for a natural feel).

Stats Bridge: Enable the Stats Bridge to add hunger, happiness, and other needs with automatic decay. Use the FeedCompanion instruction to restore needs.

Combat Companions

Companions that fight alongside the player using CPS Vitals, Abilities, and the Target system. CPS manages following and state — combat AI runs in GC2 State Machines on the companion prefab.

Architecture Pattern

CPS manages when a companion follows vs. fights. The companion prefab's GC2 State Machine handles how it fights. Use Issue Command (Cmd_Attack) to hand control to the combat state machine, and return to Following when combat ends.

Combat Entry / Exit

  1. Enemy in range → Target Nearest (faction: Enemy)
  2. Issue Command (Cmd_Attack) — Brain → Commanded state
  3. Companion's GC2 State Machine runs (pursue, attack, ability loop)
  4. Enemy dies → Clear Target → Companion Follow
  5. Companion resumes following the owner

Ability Loop (in companion's State Machine)

  1. Condition: Has Target + Target In Range (melee range)
  2. Condition: Can Use Ability (slot 0) → Use Ability (slot 0)
  3. If GCD active, play idle combat animation (GC2 Play Animation instruction)
  4. Condition: Companion Is Dead → exit combat, trigger death sequence

Health Management

Wire the On Companion Damaged and On Companion Death events to UI updates and game logic:

  • On Damaged → flash health bar, play hurt animation
  • On Death → play death VFX, disable combat state machine, wait for revive
  • Condition: Companion Health ≤ 25% → trigger emergency heal ability
Trait Synergy: Assign traits at companion creation to differentiate build roles. A Warrior companion with a Rare "Shield Wall" trait might reduce incoming damage, while an Epic "Battle Fury" trait lowers GCD when health drops below 30%.

Bonding & Traits Progression

A progression loop where bonding unlocks new traits, abilities, and dialogue. This pattern works for any game type — RPG companions, pets, dating sims, or management games.

Passive Bond Accumulation

Bond accumulates automatically via proximity (PassiveBondPerMinutein CompanionPersonality). No scripting required — the player simply spending time with a companion advances the relationship.

Active Bond Gains

  • Completing commands → BondPerCommand (set in CompanionPersonality)
  • Visiting interest points → BondPerPOI
  • Player-triggered events → Modify Bond instruction (+/− amount)

Tier-Up Trigger Flow

Use the On Bond Tier Changed event to drive progression:

  1. Event: On Bond Tier Changed
  2. Condition: Bond Tier ≥ Loyal
  3. Instruction: Assign Trait (Trait_LoyalBond)
  4. Instruction: Set Ability (slot 1, Ability_LoyalSkill)
  5. Play a tier-up VFX, trigger a short cutscene, or open a dialogue sequence

Random Trait at Recruitment

Give each companion a random personality at the moment they join the party:

  1. Event: On Companion Summoned
  2. Condition: Has Trait (any) — negate it (skip if already has traits)
  3. Instruction: Assign Random Trait (TraitPool_Default)
  4. Instruction: Assign Random Trait (TraitPool_Combat) — second roll from a different pool
Trait Incompatibility: Always run Can Add Trait before assigning when traits could conflict. The condition checks RequiredTrait, MinBondTier, and IncompatibleTraits in one pass — no manual validation needed.

Escort Mission

An NPC follows the player through a level. Uses CPS for following without needing custom pathfinding code.

  1. Create a CompanionDefinition for the escort NPC
  2. Use a FollowProfile with tight InnerRadius (1.5m) and low TeleportRadius (15m)
  3. On mission start: Summon Companion
  4. On mission end: Recall Companion
  5. Use Is Companion Active condition to check if NPC is still with player