Helper Cats System

Deck-based helper system providing passive bonuses and triggered effects during gameplay.

Overview

Helper cats are collectible cards. During gameplay, they provide:

Type	Behavior
Reactive	Trigger on specific conditions (cake combos)
Passive	Always-on multiplier bonuses
Active	Player-activated abilities with cooldowns

Key Classes

HelperCatData

Location: Assets/_Game/Scripts/Data/HelperCatData.cs

ScriptableObject defining a helper cat:

public class HelperCatData : ScriptableObject
{
    public string catName;
    public HelperCatEffectType effectType;  // Reactive, Passive, Active
    public List<CakeComboData> triggerCombos;
    public float scoreMultiplier;
    public int bonusPoints;
    public bool HasActiveAbility;
    // ...
}

HelperCatsManager

Location: Assets/_Game/Scripts/Managers/HelperCatsManager.cs

Runtime gameplay coordinator:

Method	Purpose
OnCakeDelivered()	Process reactive effects per cake
OnOrderCompleted()	Process order completion effects
GetPassiveMultiplierBonus()	Sum all passive bonuses
OnChainBroken()	Reset combo state
SetDeckFromGameRun()	Initialize with deck data

CafeDeckData

Location: Assets/_Game/Scripts/Data/CafeDeckData.cs

Current deck configuration:

public class CafeDeckData
{
    public List<HelperCatData> HelperCats;

    public List<HelperCatData> GetReactiveHelperCats();
    public List<HelperCatData> GetPassiveHelperCats();
    public List<HelperCatData> GetActiveHelperCats();
    public void AddHelperCat(HelperCatData cat);
}

PersistentHelperCatManager

Location: Assets/_Game/Scripts/Managers/PersistentHelperCatManager.cs

Manages owned helper cats across sessions (persistent service):

• Tracks all owned helper cats
• Survives scene transitions
• Syncs with save data

Active Abilities

Location: Assets/_Game/Scripts/Systems/ActiveHelperCats/

Active abilities have cooldowns and player-triggered effects:

public interface IActiveHelperAbility
{
    void Activate(OrderingCat target);
    float Cooldown { get; }
    bool IsReady { get; }
}

Components:

• ActiveHelperCatsController - Main ability controller
• AbilityVisualHandler - Visual effects per ability
• Individual abilities in Abilities/ folder

Combo System

Helper cats trigger via CakeComboData:

Combo Type	Description
SPECIFIC_CAKE	Match exact cake type
COUNT	N cakes of a type in a row
SEQUENCE	Specific cake order
SET	Any combination of required cakes
PATTERN_COUNT	Flexible pattern matching

Example combo:

// Triggers when 3 chocolate cakes delivered in a row
new CakeComboData {
    type = ComboType.COUNT,
    requiredCount = 3,
    cakeCategory = CakeCategory.Chocolate
}

Effect Application

// ComboEffect accumulates bonuses
public class ComboEffect
{
    public int baseScoreToAdd;
    public float multiplierToAdd;
    public float orderTimeToAdd;  // Time extension
}

Meta Progression: Unlock on Star Completion

Helper cats can be unlocked as rewards for completing star levels for the first time.

Configuration

In game_config.json, each star level has an unlockHelperCats array of ScriptableObject asset names:

{
  "starLevelNumber": 1,
  "unlockHelperCats": ["BabyHelperCat", "CatOfGreedHelperCat"]
}

Unlock Flow

1. Player completes all days in a star run
2. WorkDayProgress.CompleteStarLevel() adds a StarCompletionRecord
3. GameRunStateManager.OnWorkDayProgressCompleted() calls HelperCatUnlockService.ProcessStarLevelUnlocks()
4. Service checks if this is the first completion (GetCompletionCount == 1)
5. Resolves cat IDs via HelperCatDatabase.GetHelperCatByAssetName()
6. Adds new cats via PersistentHelperCatManager.AddHelperCat()
7. Saves the game and returns the list to the victory screen

Key Classes

Class	Location	Purpose
HelperCatUnlockService	Systems/Progression/	Static service: resolves + unlocks cats
HelperCatDetailUI	UI/	Reusable modal popup (icon, name, description, flavor text)
VictoryScreenUnlockedCatEntry	UI/	Small card for victory screen grid

UI

• Victory Screen: Shows unlocked cats section when cats are newly earned
• Management Panel: “View” button on each card opens HelperCatDetailUI modal
• Detail Modal: Shows cat icon, name, description, flavor text, and effect type

Adding Unlock Rewards

1. Add the helper cat asset name to unlockHelperCats in the star level config in game_config.json
2. The asset name must match the ScriptableObject file name in HelperCatDatabase
3. Optionally fill in flavorText on the HelperCatData ScriptableObject for the detail popup

Adding New Helper Cats

1. Create HelperCatData ScriptableObject in Assets/_Game/Data/HelperCats/
2. Configure trigger combos and effects
3. Add to HelperCatDatabase
4. For active abilities: implement IActiveHelperAbility
5. Test via HelperCatsManagerTests