Herd — Implementation Plan

Overview

A 2D top-down browser game. The player taps/clicks on the canvas to direct a border collie, which exerts pressure on a flock of sheep. The objective is to guide the entire flock into a marked pen area before time runs out.

Rendering: HTML5 Canvas (no heavy game engine).
Physics/AI: hand-rolled boids flocking + dog steering.
Stack: TypeScript · Vite · npm · GitLab Pages.

Phase 1 — Project Scaffold

• npm create vite@latest herd -- --template vanilla-ts
• Add .gitlab-ci.yml for GitLab Pages deployment (build → dist/, artifact on public/ path).
• Configure vite.config.ts with base: '/herd/' (adjust to match the repo name / Pages path).
• Set up tsconfig.json with strict: true.
• Add eslint + prettier configs (optional but recommended for the long run).
• Copy plant.png into the project root and reference it as the favicon in index.html: <link rel="icon" type="image/png" href="/plant.png" />
• Verify npm run dev and npm run build both work before writing any game code.

Deliverable: blank Vite page with favicon, deployed to GitLab Pages.

Phase 2 — Game Loop & Canvas

Files: src/main.ts, src/game/GameLoop.ts, src/game/Canvas.ts

• Create a <canvas> element that fills the viewport, scaling with devicePixelRatio for crisp rendering on retina/HiDPI screens.
• Handle resize events — recalculate canvas size and reposition entities proportionally.
• Implement a fixed-timestep game loop using requestAnimationFrame:
• Accumulate dt (delta time in ms).
• Run update(dt) in fixed 16 ms steps (≈60 Hz) to keep physics deterministic.
• Run render(interpolationAlpha) every frame.
• Expose GameLoop.start() / GameLoop.stop().

Deliverable: blank canvas with a running loop that logs FPS to console.

Phase 3 — Entity System

Files: src/entities/Entity.ts, src/entities/Sheep.ts, src/entities/Dog.ts, src/entities/Pen.ts

Entity base

Each entity has: - position: Vec2 - velocity: Vec2 - radius: number (for collision/influence zones) - update(dt: number): void - draw(ctx: CanvasRenderingContext2D): void

Vec2 math helper

File: src/math/Vec2.ts
Implement: add, sub, scale, normalize, length, distance, limit, lerp.
Keep it immutable — return new Vec2 instances.

Sheep

• Circular sprite (or a simple polygon) with a facing direction.
• Carries boids state: a list of currently visible neighbors (updated each tick).
• Has a fearLevel scalar that rises when the dog is close, decays over time.

Dog

• Distinct visual so it's easy to tell apart from sheep.
• Has a target: Vec2 | null — the position the player last tapped.
• Moves toward target at a fixed speed; stops when within ~8 px.

Pen

• An axis-aligned rectangle defined by x, y, width, height.
• contains(pos: Vec2): boolean — used for win-condition checking.
• Drawn as a fenced rectangle with an open side (the "gate").

Deliverable: entities visible on canvas, nothing moving yet.

Phase 4 — Sheep Flocking (Boids)

File: src/ai/Boids.ts

Classic boids with sheep-specific extensions. Each frame, for each sheep, compute a weighted sum of steering forces:

Implementation notes:

• Neighbor lookup is O(n²) — fine for ≤40 sheep.
• Cap final velocity with Vec2.limit(maxSpeed).
• maxSpeed for sheep: ~90 px/s. maxForce (acceleration cap per frame): ~6 px/s².
• When fearLevel is high, multiply dog-flee weight and max speed by a multiplier (panicked sheep move faster).

Deliverable: sheep flock together and scatter when the dog approaches.

Phase 5 — Dog Behaviour & Player Input

File: src/input/InputHandler.ts, update Dog

Input

• Listen for pointerdown on the canvas (covers mouse, touch, stylus).
• Convert from screen coordinates to canvas/world coordinates (account for devicePixelRatio and canvas CSS size).
• Set dog.target to the tapped world position.

Dog movement

• Each tick: compute vector from dog.position to dog.target.
• Steer toward target with a simple seek behaviour (Vec2.normalize(diff).scale(speed)).
• Dog speed: ~160 px/s — faster than sheep so it can actually herd.
• Stop when distance to target < arrival threshold (~10 px); set target = null.

Dog influence on sheep

• Each sheep tick, compute distance to dog.
• If within fleeRadius: increase sheep's fearLevel; apply flee force.
• fearLevel decays exponentially when dog is far: fearLevel *= 0.95 per tick.

Deliverable: tapping moves the dog; sheep scatter away from it.

Phase 6 — Game State & Win Condition

File: src/game/GameState.ts

States: IDLE → PLAYING → WIN | FAIL

Win condition

• Check every N ticks (e.g., every 30 frames).
• Count sheep whose position is pen.contains(sheep.position).
• Win when ≥ threshold (e.g., all sheep, or configurable percentage like 80%).
• Brief celebration (all sheep in pen, show "You Win!" overlay).

Fail condition (optional, adds pressure)

• A countdown timer. If it hits zero before the win condition, show "Time's Up!" overlay.

UI overlays

• Render directly on canvas (no DOM elements during gameplay for performance).
• IDLE: "Tap to start" message.
• PLAYING: sheep-in-pen counter (e.g., "3 / 8 🐑") + timer bar.
• WIN / FAIL: message + "Play Again" prompt.

Deliverable: complete game loop from start to end state, restartable.

Phase 7 — Visual Polish

Keep it readable and charming without requiring art assets (use canvas primitives).

Sheep

• White filled circle, darker ellipse for the "wool" texture, two small dots for eyes, tiny legs.
• Or: import simple SVG sprite at a later pass.

Dog

• Brown/black filled circle with pointed ears, different color from sheep.

Pen

• Dashed or solid rectangle, green fill at low opacity, fence posts along three sides, open gate on one side with a visual indicator.

Logo / favicon

• plant.png (grass icon) is already in the project root and wired up in index.html.
• Render it in the top-left corner of the canvas as a small watermark during gameplay (e.g. 32×32 px at low opacity).
• Can also appear on the level-select / idle screens at full size as the game's title graphic.

Environment

• Green fill for the field.
• Optional: a few static obstacle circles (rocks / trees) that sheep path around — add boundary repulsion force for each.

Feedback

• Footprints that fade out behind the dog.
• Sheep briefly turn red/orange when at high fearLevel.
• Pen fill color shifts from transparent → light green as more sheep enter.

Phase 8 — Levels & Configuration

File: src/levels/LevelConfig.ts

All coordinates are fractional (0.0–1.0) relative to canvas size so levels are resolution-independent.

LevelConfig type

interface SheepOverride {
  index: number;
  stubborn?: boolean;       // higher flee radius, lower cohesion pull
  leader?: boolean;         // larger cohesion broadcast radius — others weight this sheep more
  subFlock?: number;        // group ID; sheep strongly prefer neighbors in the same group
  startFear?: number;       // 0–1 initial fearLevel (default 0)
}

interface DynamicObstacle {
  x: number; y: number; r: number;
  appearsAtSeconds: number; // obstacle materializes partway through the level
}

interface LevelConfig {
  id: number;
  title: string;
  subtitle: string;           // one-line real-world resonance note shown on level card

  sheepCount: number;
  penRect: { x: number; y: number; w: number; h: number };
  penGateSide: 'top' | 'right' | 'bottom' | 'left';
  timeLimitSeconds: number | null;  // null = no timer
  winThreshold: number;             // fraction of flock that must be penned, e.g. 1.0 = all

  spawnClusters: Array<{ cx: number; cy: number; r: number; count: number }>;
  // where sheep start — allows scattered vs. grouped starts

  obstacles: Array<{ x: number; y: number; r: number }>;
  dynamicObstacles: DynamicObstacle[];

  sheepOverrides: SheepOverride[];

  darkMode: boolean;                // canvas is dark; only the dog's vicinity is lit
  penShrinksEverySeconds: number | null; // pen width/height reduce by 10% on each interval
}

The 10 Levels

Level 1 — "First Lesson"

No real-world parallel — pure tutorial.

The player learns that tapping moves the dog, the dog scares sheep, and sheep flock together. The generous threshold and timer mean almost any approach works. A tooltip appears on first tap.

Level 2 — "The Scatter"

Real-world parallel: rural depopulation. Communities spread too thin across a landscape to self-organize. Someone has to physically go out and bring them back together before cohesion can happen at all.

The mechanical lesson: cohesion only kicks in at range. A scattered flock can't self-organize; it needs active bridging.

Level 3 — "The Holdouts"

Real-world parallel: herd immunity. You need a population-wide threshold, but a small minority requires dramatically more effort than the rest. The burden of 100% is not evenly distributed.

The main flock pens easily. Then the player discovers that the three holdouts need individual, sustained pressure — they can't be herded efficiently as a group and will break away from the main flock if spooked.

Level 4 — "Two Tribes"

Real-world parallel: political polarization. Two groups have strong internal cohesion but actively repel each other. Getting both into the same space requires patient, impartial pressure — heavy-handed intervention on one tribe panics the other.

The player quickly learns that chasing one group into the pen scatters the other. Gentle, alternating pressure from behind both groups is the only solution. The pen is large enough to hold both — once they're in, proximity to the pen edges overrides the inter-flock repulsion (sheep stop caring about tribe when they're already safe).

Level 5 — "Shrinking Pasture"

Real-world parallel: habitat loss / urban sprawl. The environment erodes in real time. What was open ground becomes obstacles. The sheep adapt by clustering, which paradoxically makes them easier to herd — but the route to the pen gets harder.

The player doesn't need to hurry at first — but procrastination means the path to the pen gets blocked. The level is completable early with a moderate strategy or late with a very tight squeeze.

Level 6 — "Already Spooked"

Real-world parallel: displaced or traumatized populations. Every intervention triggers a panic response. Heavy-handed herding makes things worse. The player must slow down, reduce pressure, and use patience rather than force.

The player who taps aggressively will send sheep careening into walls and each other. The level is easier with a slow dog, moved in short steps, looping wide around the flock. The generous timer and threshold explicitly reward restraint over speed.

Level 7 — "The Influencers"

Real-world parallel: social contagion and opinion dynamics. In any group, a small number of nodes determine collective movement. Identify and redirect the key nodes and the crowd follows. Ignore them and you're pushing against invisible resistance.

The player who tries to herd the whole flock at once will be confused why it doesn't work. The player who figures out to target the leaders first will watch the rest follow almost by themselves.

Level 8 — "Race to Market"

Real-world parallel: industrial livestock production. Volume, speed, and efficiency above all else. The level is deliberately exhausting — a comment on what it feels like to operate at industrial scale.

The player has to be decisive and aggressive. The 80% threshold gives a little slack but not much. It's the one level where patience is actively punished. After the calm required by Level 6, the gear shift is jarring — intentionally.

Level 9 — "Lights Out"

Real-world parallel: information asymmetry — making decisions when you can only see a fraction of the picture. The flock is out there. You just can't see where. You respond to what's in front of you and hope.

To win you must sweep the entire field systematically. The 100% threshold means you can't leave anyone behind, and you can't see who's left. After clearing most sheep, the final one or two are found by listening.

⚠️ The rustling audio cue is gated on Phase 9 being implemented. Without audio, the level is still playable but loses its most important feedback signal — implement Phase 9 before shipping Level 9.

Level 10 — "The Last Pasture"

Real-world parallel: climate crisis. The deadline isn't a countdown — it's a slow erosion. You have time until suddenly you don't. The goal seems achievable right up until the moment it isn't.

The player is told only that all sheep must reach the pen. There is no visible clock. The pen visually shows its current size, and a subtle ambient sound grows more urgent as the pen contracts. Players who dawdle discover the deadline too late. The level is designed to be replayed — on a second run, knowing the pen is shrinking changes everything about how you approach it.

Difficulty Curve Summary

Extended LevelConfig notes

• All coordinates are 0.0–1.0 fractions of canvas dimensions.
• spawnClusters defines where sheep appear; sheep within a cluster are placed with small random offsets from the cluster center.
• sheepOverrides are applied by index after spawn assignment.
• darkMode activates a canvas compositing layer; the "torch" radius and falloff are tunable constants.
• penShrinksEverySeconds contracts both w and h by a fixed fraction each interval; minimum pen size is capped to prevent a zero-area pen (which would make 100% threshold impossible and trigger a specific "too late" lose state).
• Level metadata (title, subtitle) is shown on a pre-level card screen before the game starts.

Phase 9 — Audio (Optional / Later)

• Use the Web Audio API directly (no library).
• Sounds: soft baa on scare, dog bark on tap, success chime.
• Keep audio files small (< 50 KB total).
• Add a mute toggle button in the corner.

Phase 10 — GitLab CI/CD

File: .gitlab-ci.yml

pages:
  stage: deploy
  image: node:20
  script:
    - npm ci
    - npm run build
    - mv dist public
  artifacts:
    paths:
      - public
  only:
    - main

• Set base in vite.config.ts to match the GitLab Pages URL path.
• Confirm the deployed URL loads and runs the game.

Assets & Attribution

The Flaticon license requires attribution when the free tier is used. Attribution is included in the README and (where space permits) in an in-game "Credits" screen or overlay.

File Structure (target)

herd/
├── .gitlab-ci.yml
├── index.html
├── package.json
├── plant.png             # favicon + logo (Icongeek26 / Flaticon, outline collection)
├── tsconfig.json
├── vite.config.ts
└── src/
    ├── main.ts               # entry point — mounts canvas, starts GameLoop
    ├── math/
    │   └── Vec2.ts
    ├── game/
    │   ├── Canvas.ts         # canvas sizing, dpr scaling, coord transform
    │   ├── GameLoop.ts       # rAF loop, fixed timestep
    │   └── GameState.ts      # state machine, win/fail checks, UI overlays
    ├── entities/
    │   ├── Entity.ts
    │   ├── Sheep.ts
    │   ├── Dog.ts
    │   └── Pen.ts
    ├── ai/
    │   └── Boids.ts          # force calculation, neighbor queries
    ├── input/
    │   └── InputHandler.ts   # pointer events → world coords
    └── levels/
        └── LevelConfig.ts

Key Constants to Tune (start here, adjust by feel)

These will need iteration. The game feel lives entirely in these numbers.

Development Order

1. Scaffold (Phase 1) — get CI green with a blank page first.
2. Canvas + loop (Phase 2).
3. Vec2 + entities rendering statically (Phase 3).
4. Boids forces in isolation with no dog — just watch sheep flock (Phase 4).
5. Add dog input and flee force (Phase 5).
6. Win/fail states (Phase 6).
7. Polish passes (Phase 7+) as desired.

Do not skip to polish before the core herding feel is fun. The boids tuning in Phase 4–5 is the game.