Engine Hooks & Event Bus

flowchart TB
    subgraph Sim["Deterministic Simulation Authority (20 Ticks/Sec)"]
        TickLoop["GameLoop (dt = 0.05s)"]
        World["ECS World"]
        SimSystems["Systems (Combat, Spells, Build, AI, Triggers)"]
        SimBus["Simulation EventBus"]
        
        TickLoop --> World
        World --> SimSystems
        SimSystems -->|emit| SimBus
    end
 
    subgraph Bridge["Cross-Boundary EventBridge"]
        SimBus -->|Whitelisted sim->main| EB["EventBridge (__bridged: true)"]
        EB -->|Whitelisted main->sim| SimBus
    end
 
    subgraph Main["Main Presentation Thread (60+ FPS Interpolated)"]
        MainBus["Main Thread EventBus"]
        Renderer["3D/2D Renderers (Three.js / Canvas)"]
        Audio["SoundManager / VoiceLineSystem"]
        HUD["React HUD / Victory Banners"]
        UserInput["Player Input (Spell targeting, Build clicks)"]
 
        EB -->|Re-emit| MainBus
        MainBus --> Renderer
        MainBus --> Audio
        MainBus --> HUD
        UserInput -->|emit| MainBus
        MainBus -->|User Intent| EB
    end

import { eventBus } from '@/game/core/EventBus';
 
// Registering a listener
function onMeleeHit(data: any) {
  console.log('Melee strike landed:', data);
}
 
eventBus.on('melee-attack-hit', onMeleeHit);
 
// Clean up when dismantling your module or system
eventBus.off('melee-attack-hit', onMeleeHit);

export interface DeathPayload {
  readonly entityId: number;
  /** Owning player index (0..7), or -1 for neutral critters. */
  readonly playerId: number;
  readonly isBuilding: boolean;
  readonly isFlying: boolean;
  readonly isNaval: boolean;
  /** True for defensive walls and palisades. */
  readonly isWall: boolean;
  /** True for destructible creep camps and spawn nests. */
  readonly isCreepSpawner: boolean;
  readonly pixelX?: number;
  readonly pixelY?: number;
  readonly gridX?: number;
  readonly gridY?: number;
  /** Footprint dimensions in tiles (buildings only). */
  readonly gridW?: number;
  readonly gridH?: number;
  readonly unitTypeId?: string;
  readonly buildingTypeId?: string;
  readonly buildingRole?: string;
  readonly buildProgress?: number;
  readonly buildingComplete?: boolean;
  readonly wallTier?: 1 | 2 | 3;
  /** Entity ID of the killer; omitted for decay or scripted suicide. */
  readonly killerEntityId?: number;
  /** 8-way directional heading (0..7) at the exact moment of death. */
  readonly direction?: Direction;
}

// 'unit-trained'
export interface UnitTrainedPayload {
  readonly unitType: string;
  readonly playerId: number;
  readonly entityId?: number;
}
 
// 'building-complete'
export interface BuildingCompletePayload {
  readonly entityId: number;
  readonly buildingType: string;
  readonly playerId: number;
}
 
// 'building-upgraded'
export interface BuildingUpgradedPayload {
  readonly entityId: number;
  readonly oldType: string;
  readonly newType: string;
  readonly playerId: number;
}
 
// 'upgrade-complete'
export interface UpgradeCompletePayload {
  readonly upgradeId: string;
  readonly playerId: number;
}
 
// 'game-over'
export interface GameOverPayload {
  readonly winner: number; // Winning team or player ID (-1 for draw)
  readonly state: GameState; // GameState.VICTORY or GameState.DEFEAT
}

import type { DamageType } from '@/game/data/constants';
import type { AnimationCueDef } from '@/game/data/animationCues';
 
// 'attack-start'
export interface AttackStartEvent {
  readonly attackerEntityId: number;
  readonly targetEntityId: number;
  readonly attackKind: 'melee' | 'ranged';
  readonly unitTypeId?: string;
  readonly projectileType?: string;
  readonly sourcePixelX: number;
  readonly sourcePixelY: number;
  readonly targetPixelX: number;
  readonly targetPixelY: number;
  readonly cues: readonly AnimationCueDef[];
}
 
// 'melee-attack-hit'
export interface MeleeAttackHitPayload {
  readonly attackerEntityId: number;
  readonly targetEntityId: number;
  readonly attackerPixelX: number;
  readonly attackerPixelY: number;
  readonly targetPixelX: number;
  readonly targetPixelY: number;
  readonly damage: number;
  readonly unitTypeId?: string;
  readonly direction: number;
  readonly damageType: DamageType;
  readonly bonusElement: string | null;
  readonly isCrit: boolean;
}
 
// 'projectile-resolved'
export interface ProjectileResolvedPayload {
  readonly targetId: number;
  readonly damage: number;
  readonly pixelX: number;
  readonly pixelY: number;
  readonly projectileType: string;
  readonly damageType: DamageType;
  readonly bonusElement: string | null;
  readonly isCrit: boolean;
  readonly aoeRadius?: number;
  readonly sourceUnitTypeId?: string;
}
 
// 'aoe-impact'
export interface AoeImpactPayload {
  readonly pixelX: number;
  readonly pixelY: number;
  readonly radius: number;
  readonly color: string;
  readonly spellId?: string;
  /** Ordered list of entity targets for multi-hop chain abilities. */
  readonly chainHops?: Array<{ entityId: number; x: number; y: number }>;
}
 
// 'cone-blast-vfx'
export interface ConeBlastPayload {
  readonly entityId: number;
  readonly sourcePixelX: number;
  readonly sourcePixelY: number;
  readonly angle: number;      // Radians
  readonly halfAngle: number;  // Radians
  readonly lengthPx: number;
  readonly color: string;
}
 
// 'crit-landed'
export interface CritLandedPayload {
  readonly attackerEntityId: number;
  readonly targetEntityId: number;
  readonly pixelX: number;
  readonly pixelY: number;
  readonly damage: number;
  readonly isMelee: boolean;
}
 
// 'entity-attacked'
export interface EntityAttackedPayload {
  readonly targetEntityId: number;
  readonly attackerEntityId: number;
  readonly targetPlayerId: number;
  readonly attackerPlayerId: number;
  readonly damage?: number;
}

// 'cast-start'
export interface CastStartEvent {
  readonly entityId: number;
  readonly spellId: string;
  readonly totalTicks: number;
  readonly castAnimSlot: 1 | 2 | 3;
  readonly sourcePixelX: number;
  readonly sourcePixelY: number;
  readonly targetEntityId?: number;
  readonly targetPixelX?: number;
  readonly targetPixelY?: number;
  readonly targetGridX?: number;
  readonly targetGridY?: number;
  readonly cues: readonly AnimationCueDef[];
}
 
// 'cast-complete' & 'cast-cancel'
export interface CastCompletePayload {
  readonly entityId: number;
  readonly spellId: string;
}
 
export interface CastCancelPayload {
  readonly entityId: number;
  readonly spellId: string;
  readonly reason: 'stunned' | 'moved' | 'died' | 'silenced' | 'manual';
}
 
// 'spell-failed'
export interface SpellFailedPayload {
  readonly reason: 'not_enough_mana' | 'cooldown' | 'out_of_range' | 'invalid_target';
  readonly playerId: number;
  readonly casterEntityId: number;
}
 
// 'heal-vfx'
export interface HealVfxPayload {
  readonly targetEntityId: number;
  readonly amount: number;
  readonly pixelX: number;
  readonly pixelY: number;
}
 
// 'polymorph-vfx'
export interface PolymorphVfxPayload {
  readonly pixelX: number;
  readonly pixelY: number;
  readonly color: string;
  readonly spellId: string;
}
 
// 'raise-dead-vfx'
export interface RaiseDeadVfxPayload {
  readonly pixelX: number;
  readonly pixelY: number;
  readonly corpseCount: number;
}
 
// 'summon-vfx'
export interface SummonVfxPayload {
  readonly pixelX: number;
  readonly pixelY: number;
  readonly unitTypeId: string;
}

// 'item-purchased'
export interface ItemPurchasedPayload {
  readonly playerId: number;
  readonly shopEntityId: number;
  readonly heroEntityId: number;
  readonly itemId: string;
  readonly cost: number;
}
 
// 'item-equipped'
export interface ItemEquippedPayload {
  readonly heroEntityId: number;
  readonly itemId: string;
  readonly slotIndex: number;
  readonly statsDelta?: Record<string, number>;
}
 
// 'item-used'
export interface ItemUsedPayload {
  readonly heroEntityId: number;
  readonly playerId: number;
  readonly itemId: string;
  readonly slotIndex: number;
}
 
// 'item-dropped'
export interface ItemDroppedPayload {
  readonly heroEntityId: number;
  readonly itemId: string;
  readonly gridX: number;
  readonly gridY: number;
  readonly groundEntityId: number;
}
 
// 'item-sold'
export interface ItemSoldPayload {
  readonly heroEntityId: number;
  readonly playerId: number;
  readonly itemId: string;
  readonly goldRefund: number;
}
 
// 'resource-gathered'
export interface ResourceGatheredPayload {
  readonly resourceType: 'gold' | 'lumber' | 'stone' | 'oil';
  readonly amount: number;
  readonly playerId: number;
}
 
// 'creep-bounty'
export interface CreepBountyPayload {
  readonly killerPlayerId: number;
  readonly gold: number;
  readonly entityId: number;
  readonly pixelX: number;
  readonly pixelY: number;
}

// 'wonder-started' & 'wonder-complete'
export interface WonderStartedPayload {
  readonly entityId: number;
  readonly playerId: number;
}
 
export interface WonderCompletePayload {
  readonly entityId: number;
  readonly playerId: number;
  readonly holdTicks: number;
}
 
// 'wonder-countdown'
export interface WonderCountdownPayload {
  readonly entityId: number;
  readonly playerId: number;
  readonly remainingTicks: number;
}
 
// 'wonder-progress'
export interface WonderProgressPayload {
  readonly entityId: number;
  readonly playerId: number;
  readonly gridX: number;
  readonly gridY: number;
  readonly percent: number;
  readonly milestone: boolean;
  readonly milestonePercent: number;
}
 
// 'king-slain'
export interface KingSlainEvent {
  readonly playerId: number;
  readonly teamId: number;
  readonly entityId: number;
}
 
// 'relic-picked-up' & 'relic-dropped'
export interface RelicPickedUpPayload {
  readonly relicEntityId: number;
  readonly index: number;
  readonly heroEntityId: number;
  readonly playerId: number;
}
 
export interface RelicDroppedPayload {
  readonly relicEntityId: number;
  readonly index: number;
  readonly gridX: number;
  readonly gridY: number;
  readonly playerId: number;
  readonly reason: 'carrier_lost' | 'bank_destroyed';
}
 
// 'control-point-captured'
export interface ControlPointCapturedPayload {
  readonly entityId: number;
  readonly playerId: number;
  readonly teamId: number;
}
 
// 'score-standings'
export interface ScoreStandingsPayload {
  readonly remainingTicks: number;
  readonly standings: Array<{
    readonly playerId: number;
    readonly teamId: number;
    readonly score: number;
  }>;
}

{
  "id": "trig_boss_phase_2",
  "name": "Boss Enrage at 50% HP",
  "enabled": true,
  "events": [
    {
      "k": "unitAttacked",
      "unit": { "k": "entityByAid", "aid": "boss_dragon" }
    }
  ],
  "conditions": [
    {
      "k": "lt",
      "a": {
        "k": "unitProp",
        "unit": { "k": "entityByAid", "aid": "boss_dragon" },
        "prop": "hp"
      },
      "b": 2500
    },
    {
      "k": "eq",
      "a": { "k": "var", "name": "phase2_triggered" },
      "b": false
    }
  ],
  "actions": [
    { "k": "setVar", "name": "phase2_triggered", "val": true },
    {
      "k": "raiseEvent",
      "name": "boss-enraged",
      "data": { "bossAid": "boss_dragon" }
    },
    {
      "k": "order",
      "order": "attack_move",
      "units": { "k": "unitsWithTag", "tag": "minions" },
      "target": { "k": "regionCenter", "region": "player_base" }
    }
  ]
}

import { eventBus } from '@/game/core/EventBus';
import type { DeathPayload } from '@/game/systems/deathPayload';
import type { AttackStartEvent } from '@/game/data/animationCues';
 
export class CombatTelemetryLogger {
  private boundOnDeath = (data: unknown) => this.onEntityDied(data as DeathPayload);
  private boundOnAttack = (data: unknown) => this.onAttackStart(data as AttackStartEvent);
 
  init(): void {
    eventBus.on('entity-died', this.boundOnDeath);
    eventBus.on('attack-start', this.boundOnAttack);
  }
 
  destroy(): void {
    eventBus.off('entity-died', this.boundOnDeath);
    eventBus.off('attack-start', this.boundOnAttack);
  }
 
  private onEntityDied(payload: DeathPayload): void {
    if (payload.isBuilding) {
      console.log(`Building ${payload.buildingTypeId} razed for player ${payload.playerId}`);
    }
  }
 
  private onAttackStart(event: AttackStartEvent): void {
    if (event.attackKind === 'ranged') {
      console.log(`Ranged attack from ${event.attackerEntityId} to ${event.targetEntityId}`);
    }
  }
}

import { System } from '@/game/ecs/System';
import { eventBus } from '@/game/core/EventBus';
import type { Position } from '@/game/components/Position';
import type { Health } from '@/game/components/Health';
 
export class PoisonSwampSystem extends System {
  // Systems with lower priority numbers update earlier in the tick.
  // 50 runs after MovementSystem (20) but before CombatSystem (60).
  priority = 50;
 
  private tickAccumulator = 0;
 
  init(): void {
    // Systems can register event listeners during initialization
    console.log('[PoisonSwampSystem] Initialized in World');
  }
 
  update(dt: number): void {
    this.tickAccumulator++;
    // Run environmental check every 20 ticks (1 second)
    if (this.tickAccumulator % 20 !== 0) return;
 
    // DETERMINISM RULE: Always query entities using canonically sorted queries!
    const entities = this.world.getEntitiesWith('position', 'health', 'owner');
 
    for (const entity of entities) {
      // Never affect dead or flying entities
      if (entity.hasComponent('flying')) continue;
 
      const pos = entity.getComponent<Position>('position');
      const health = entity.getComponent<Health>('health');
 
      // Check if entity is standing on swamp terrain (assumes custom tile check)
      if (this.isSwampTile(pos.gridX, pos.gridY)) {
        const damage = 5;
        health.current = Math.max(1, health.current - damage);
 
        // Notify presentation layer of environmental damage tick
        eventBus.emit('combat-number', {
          entityId: entity.id,
          amount: damage,
          kind: 'poison',
          pixelX: pos.pixelX,
          pixelY: pos.pixelY,
        });
      }
    }
  }
 
  private isSwampTile(x: number, y: number): boolean {
    // Custom terrain inspection logic...
    return false;
  }
 
  destroy(): void {
    // Clean up timers or internal buffers
  }
}

import { world } from '@/game/ecs/WorldInstance';
import { PoisonSwampSystem } from './PoisonSwampSystem';
 
// Add the system with its defined priority
const swampSystem = new PoisonSwampSystem();
world.addSystem(swampSystem, swampSystem.priority);

// ❌ WRONG: Non-deterministic iteration order
const set = world.getComponentIndex('combat');
for (const entityId of set) {
  // Diverges across clients!
}
 
// ❌ WRONG: Using unsorted render queries in simulation
const entities = world.getEntitiesWithIntoUnsortedRenderOnly([], 'combat', 'position');
 
// ✅ CORRECT: getEntitiesWith is canonically sorted by entity.id (ascending)
const entities = world.getEntitiesWith('combat', 'position');
 
// ✅ CORRECT: Allocation-free sorted query for hot tick loops
const scratchBuffer: Entity[] = [];
world.getEntitiesWithIntoSorted(scratchBuffer, 'combat', 'position');
for (const entity of scratchBuffer) {
  // 100% deterministic on all machines!
}

// ✅ CORRECT: Snapshot array prevents mid-loop index corruption
const targets = world.getEntitiesWith('health');
for (const entity of targets) {
  if (shouldDie(entity)) {
    entity.destroy(); // Safe because 'targets' is a stable snapshot
  }
}