# Deterministic Telegraphed Boss Phases in Pulse

> Deterministic multi-phase boss telegraphing in Pulse with integer phase state, ground ring vfx, rand() jitter, and fixed-tick shockwaves.

- **Canonical page:** https://gamecrew.ai/techniques/pulse/fixed-tick-telegraphed-boss-encounters
- **Techniques hub:** https://gamecrew.ai/techniques
- **Engine:** Pulse
- **Category:** ai
- **Tags:** `pulse`, `boss`, `ai`, `telegraph`, `deterministic`, `vfx`, `encounters`
- **Verification:** Compile-verified pattern

## When to Use & Field Best Practices

Boss attacks feel unfair when windups vary with frame rate or hitboxes resolve unpredictably across replays. Encoding attack phases as explicit fixed-tick integers keeps every dodge window crisp and replay-deterministic:

1. **Integer Phase Machine (`0 = Windup`, `1 = Strike`, `2 = Recover`)**: Persist phase counters and timers on a `BossPhase` component rather than module-level variables or async timers.
2. **Seeded `rand()` Jitter Only**: Use Pulse's seeded `rand()` when adding natural variation to strike offsets — never call `Math.random()`, which breaks fixed-seed verification scenarios.
3. **Lead With Ground Ring `vfx`**: Spawn a ground telegraph `"ring"` at phase `0` entry so players see the exact danger radius well before `"shockwave"` and `shake(...)` fire on the strike tick.

## Mathematical & Algorithmic Core

- **Seeded Disc Scatter**: Given deterministic angle $\theta = 2\pi \cdot \text{rand}()$ and jitter radius $\delta = 0.55 \cdot \text{rand}()$:
  $$(x_s, z_s) = (x_t + \delta \cos\theta,\; z_t + \delta \sin\theta)$$
- **Clear Dodge Window**: Pair windup duration $T_{\text{windup}} \approx 1.1\text{ s}$ with an explicit ground radius matched cleanly to `near(strikePos, radius, Score)`.

## Engine Implementation

### 1. Contract Declarations

Declare via `pulse_declare`:
- `"component BossPhase { state: int=0..2=0, timer_s: num=1.5, strike_x: num=0.0, strike_z: num=0.0 }"`
- `"event BossSlam { x: num=0.0, z: num=0.0, radius: num=2.5 }"`

### 2. Fixed-Tick Boss Telegraph & Shockwave System (`systems/boss-telegraph.ts`)

```ts
import { emit, near, query, rand, shake, system, vfx } from "pulse";
import { BossPhase, BossSlam, Score } from "../contracts/core";

const STRIKE_RADIUS_M = 2.6;
const WINDUP_TIME_S = 1.1;
const RECOVER_TIME_S = 1.4;

export const bossTelegraphSystem = system("boss-telegraph", { after: "physics" }, (dt) => {
  const players = query(Score);

  for (const boss of query(BossPhase)) {
    const bp = boss.bossPhase;
    bp.timer_s -= dt;
    if (bp.timer_s > 0.0) continue;

    if (bp.state === 0) {
      // Phase 0 -> 1: lock seeded target coordinates and paint telegraph ring
      const target = players[0];
      const baseX = target ? target.pos.x : boss.pos.x;
      const baseZ = target ? target.pos.z : boss.pos.z + 3.0;
      const angle = rand() * Math.PI * 2.0;
      const jitter = rand() * 0.55;
      bp.strike_x = baseX + Math.cos(angle) * jitter;
      bp.strike_z = baseZ + Math.sin(angle) * jitter;

      vfx("ring", {
        pos: [bp.strike_x, boss.pos.y + 0.08, bp.strike_z],
        color: "#ff5c38",
        size: STRIKE_RADIUS_M,
        life_s: WINDUP_TIME_S,
      });
      bp.state = 1;
      bp.timer_s = WINDUP_TIME_S;
    } else if (bp.state === 1) {
      // Phase 1 -> 2: detonate strike, test broadphase hits, trigger impact shake
      const impactPos: [number, number, number] = [bp.strike_x, boss.pos.y + 0.2, bp.strike_z];
      vfx("shockwave", { pos: impactPos, color: "#ff9b42", count: 1 });
      vfx("burst", { pos: impactPos, color: "#ffd166", count: 16 });
      shake(0.28);

      emit(BossSlam, { x: bp.strike_x, z: bp.strike_z, radius: STRIKE_RADIUS_M });
      const hits = near(impactPos, STRIKE_RADIUS_M, Score);
      for (const hit of hits) {
        vfx("spark", { pos: [hit.pos.x, hit.pos.y + 0.9, hit.pos.z], count: 10 });
      }

      bp.state = 2;
      bp.timer_s = RECOVER_TIME_S;
    } else {
      // Phase 2 -> 0: brief recovery window before next windup
      bp.state = 0;
      bp.timer_s = 0.6;
    }
  }
});
```

## Determinism & Replay Safety

- **No Non-Deterministic Globals**: Avoid `Math.random()`, `Date.now()`, and async callbacks so every fixed-seed scenario run replays identical strike timings and telegraph locations.
- **Explicit Visual Contrast**: Keep telegraph `"ring"` bright warm orange/amber over cool floor palettes so both capture inspection and motion playtest frames stay clear.

## Verification Checklist

1. Run `pulse compile` and verify zero determinism lint errors (`Math.random` or module-level mutable state).
2. Run a fixed-seed encounter scenario and confirm `BossSlam` fires within expected windup cadence every cycle.

## Official references

- Mark Brown (Game Maker's Toolkit — Readable Boss Telegraphs)
- GameCrew Pulse System Determinism Guide
