Perks Module

The perks system provides 50+ gameplay-modifying perks with a clean three-layer architecture for maintainability and deterministic replay.

Architecture Goals

Original fidelity — Hook order and side effects match native flow

Navigability — One perk = one file with all its logic

Deterministic auditability — Stable RNG consumption and dispatch order

Three-Layer Design

Perks are split into three concerns:

Metadata Layer

Perk IDs, selection logic, availability checksLocation: src/crimson/perks/*.py

Implementation Layer

One module per perk with all its runtime logicLocation: src/crimson/perks/impl/*.py

Runtime Layer

Hook contracts, dispatch orchestration, canonical registryLocation: src/crimson/perks/runtime/*.py

Package Structure

src/crimson/perks/
  ├── ids.py                   # Perk ID enum
  ├── helpers.py               # Perk state queries
  ├── availability.py          # Offer gating logic
  ├── selection.py             # Selection UI state
  ├── state.py                 # Runtime state
  ├── impl/                    # Perk implementations
  │   ├── instant_winner.py
  │   ├── final_revenge.py
  │   ├── evil_eyes_effect.py
  │   └── ...                  # 50+ perk files
  └── runtime/                 # Dispatch system
      ├── manifest.py          # Canonical registry
      ├── hook_types.py        # Hook contracts
      ├── apply.py             # Apply-time dispatcher
      ├── effects.py           # Frame effects dispatcher
      └── player_ticks.py      # Player tick dispatcher

Perk Implementation

Each perk exports a HOOKS declaration:

src/crimson/perks/impl/instant_winner.py

from crimson.perks import PerkId
from crimson.perks.runtime.hook_types import PerkHooks
from crimson.perks.runtime.apply_context import ApplyContext

def apply_instant_winner(ctx: ApplyContext) -> None:
    """Instant Winner: Win immediately."""
    # Set win flag
    ctx.state.instant_win = True

# Export hooks
HOOKS = PerkHooks(
    perk_id=PerkId.INSTANT_WINNER,
    apply_handler=apply_instant_winner,
)

Hook Types

Defined in src/crimson/perks/runtime/hook_types.py:

class PerkHooks(msgspec.Struct):
    perk_id: PerkId
    apply_handler: ApplyHandler | None = None
    world_dt_step: WorldDtStep | None = None
    player_tick_steps: list[PlayerTickStep] | None = None
    effects_steps: list[EffectsStep] | None = None
    player_death_hook: PlayerDeathHook | None = None

Apply Handler

Runs immediately when perk is picked:

from crimson.perks.runtime.apply_context import ApplyContext

def apply_bandage(ctx: ApplyContext) -> None:
    """Bandage: Heal 1-50 HP."""
    heal_amount = (ctx.rand() % 50) + 1
    
    for player in ctx.players:
        if player.health > 0:
            player.health = min(100, player.health + heal_amount)

World Dt Step

Transforms frame delta time (e.g., Reflex Boost):

from crimson.perks.runtime.hook_types import WorldDtStep

class ReflexBoostDtHook(WorldDtStep):
    def apply(self, world: WorldState, dt: float) -> float:
        # Check if any player has active Reflex Boost
        reflex_timer = max(
            player.reflex_boost_timer
            for player in world.players
        )
        
        if reflex_timer <= 0:
            return dt
        
        # Scale down time (slow motion)
        return dt * 0.3

Effects Step

Global per-frame effects:

from crimson.perks.runtime.effects_context import EffectsContext

def evil_eyes_effect(ctx: EffectsContext) -> None:
    """Evil Eyes: Damage creatures near cursor."""
    if not perk_active(ctx.players[0], PerkId.EVIL_EYES):
        return
    
    aim_pos = Vec2(ctx.players[0].aim_x, ctx.players[0].aim_y)
    
    for creature in ctx.creatures.active_creatures():
        dist = distance(creature.pos, aim_pos)
        if dist < 100:
            creature_apply_damage(
                creature,
                damage=2.0 * ctx.dt,
                damage_type=DamageType.PERK,
            )

Player Tick Step

Per-player tick hooks:

from crimson.perks.runtime.player_tick_context import PlayerTickContext

def angry_reloader_tick(ctx: PlayerTickContext) -> None:
    """Angry Reloader: +25% speed while reloading."""
    if not perk_active(ctx.player, PerkId.ANGRY_RELOADER):
        return
    
    if ctx.player.weapon.reload_active:
        # Speed boost already applied in movement code
        pass

Player Death Hook

Triggered on player death:

from crimson.perks.runtime.hook_types import PlayerDeathHook

class FinalRevengeDeathHook(PlayerDeathHook):
    def apply(self, world: WorldState, player: PlayerState) -> None:
        """Final Revenge: Explode on death."""
        if not perk_active(player, PerkId.FINAL_REVENGE):
            return
        
        # Spawn explosion
        spawn_explosion(
            world.state,
            pos=player.pos,
            radius=200,
            damage=100,
        )

Runtime Manifest

The canonical registry in src/crimson/perks/runtime/manifest.py:

src/crimson/perks/runtime/manifest.py

from crimson.perks.impl import (
    instant_winner,
    final_revenge,
    evil_eyes_effect,
    # ... all perk modules
)

# Parity-critical dispatch order
PERK_HOOKS_IN_ORDER: list[PerkHooks] = [
    instant_winner.HOOKS,
    final_revenge.HOOKS,
    evil_eyes_effect.HOOKS,
    # ... all perk hooks in native order
]

# Derived registries (preserve order)
PERK_APPLY_HANDLERS: dict[PerkId, ApplyHandler] = {
    hook.perk_id: hook.apply_handler
    for hook in PERK_HOOKS_IN_ORDER
    if hook.apply_handler is not None
}

WORLD_DT_STEPS: list[WorldDtStep] = [
    hook.world_dt_step
    for hook in PERK_HOOKS_IN_ORDER
    if hook.world_dt_step is not None
]

PLAYER_DEATH_HOOKS: list[PlayerDeathHook] = [
    hook.player_death_hook
    for hook in PERK_HOOKS_IN_ORDER
    if hook.player_death_hook is not None
]

Order matters! Changing hook order affects RNG consumption and can break replay parity.

Dispatch Integration

Apply-Time Dispatch

src/crimson/perks/runtime/apply.py

def perk_apply(
    perk_id: PerkId,
    state: GameplayState,
    players: list[PlayerState],
) -> None:
    """Apply perk on selection."""
    
    # Increment perk count
    players[0].perk_counts[perk_id] += 1
    
    # Mirror to other players (co-op)
    for player in players[1:]:
        player.perk_counts[perk_id] = players[0].perk_counts[perk_id]
    
    # Run apply handler
    handler = PERK_APPLY_HANDLERS.get(perk_id)
    if handler is not None:
        ctx = ApplyContext(
            state=state,
            players=players,
            rand=state.rng.rand,
        )
        handler(ctx)

Frame Effects Dispatch

src/crimson/perks/runtime/effects.py

def perks_update_effects(
    state: GameplayState,
    players: list[PlayerState],
    creatures: CreaturePool,
    dt: float,
) -> None:
    """Run all perk effects hooks."""
    
    ctx = EffectsContext(
        state=state,
        players=players,
        creatures=creatures,
        dt=dt,
        rand=state.rng.rand,
    )
    
    # Always run bonus timers first
    update_player_bonus_timers(ctx)
    
    # Run all effects steps in order
    for step in PERKS_UPDATE_EFFECT_STEPS:
        step(ctx)

Perk Examples

Instant Effects

# Breathing Room: Kill all enemies
def apply_breathing_room(ctx: ApplyContext) -> None:
    for creature in ctx.creatures.active_creatures():
        creature.health = 0
        creature.active = False

Stat Modifiers

# Haste: Check in player_update
if perk_active(player, PerkId.HASTE):
    base_speed *= 1.2  # +20% movement speed

Continuous Effects

# Radioactive: Damage nearby enemies
def radioactive_effect(ctx: EffectsContext) -> None:
    for player in ctx.players:
        if not perk_active(player, PerkId.RADIOACTIVE):
            continue
        
        for creature in ctx.creatures.active_creatures():
            dist = distance(player.pos, creature.pos)
            if dist < 80:
                creature.health -= 5.0 * ctx.dt

Import Boundaries

Import Rules:

impl/ must NOT import selection or availability
runtime/ must NOT import selection or availability
Registration happens ONLY in runtime/manifest.py

Testing

Guard tests ensure architecture integrity:

tests/test_feature_hook_registries.py

def test_perk_hooks_have_unique_perk_ids():
    perk_ids = [hook.perk_id for hook in PERK_HOOKS_IN_ORDER]
    assert len(perk_ids) == len(set(perk_ids))

def test_effects_steps_prefix_invariant():
    # update_player_bonus_timers must be first
    assert PERKS_UPDATE_EFFECT_STEPS[0].__name__ == "update_player_bonus_timers"

Next Steps

Gameplay System

How perks affect gameplay

Deterministic Pipeline

Where perks run in the tick

Crimson Module

Game logic overview

Parity Status

Current parity state

Architecture

Core Systems

Modules

Parity

Architecture Goals

Three-Layer Design

Package Structure

Perk Implementation

Hook Types

Apply Handler

World Dt Step

Effects Step

Player Tick Step

Player Death Hook

Runtime Manifest

Dispatch Integration

Apply-Time Dispatch

Frame Effects Dispatch

Perk Examples

Instant Effects

Stat Modifiers

Continuous Effects

Import Boundaries

Testing

Next Steps

Gameplay System

Deterministic Pipeline

Crimson Module

Parity Status

Build docs developers (and LLMs) love

Architecture

Core Systems

Modules

Parity

​Architecture Goals

​Three-Layer Design

​Package Structure

​Perk Implementation

​Hook Types

​Apply Handler

​World Dt Step

​Effects Step

​Player Tick Step

​Player Death Hook

​Runtime Manifest

​Dispatch Integration

​Apply-Time Dispatch

​Frame Effects Dispatch

​Perk Examples

​Instant Effects

​Stat Modifiers

​Continuous Effects

​Import Boundaries

​Testing

​Next Steps

Gameplay System

Deterministic Pipeline

Crimson Module

Parity Status

Build docs developers (and LLMs) love

Architecture Goals

Three-Layer Design

Package Structure

Perk Implementation

Hook Types

Apply Handler

World Dt Step

Effects Step

Player Tick Step

Player Death Hook

Runtime Manifest

Dispatch Integration

Apply-Time Dispatch

Frame Effects Dispatch

Perk Examples

Instant Effects

Stat Modifiers

Continuous Effects

Import Boundaries

Testing

Next Steps