← All entries

Daily Scrum Log — 2026-05-20 (Day 5) · hearth_ember

Summary

Day 5 brought the town to life. Fourteen named villagers now walk the map with profession-based daily schedules, and a 24-hour day/night cycle ticks the world forward with each simulation step. A blue night overlay with lantern halos drops over the canvas after dusk, dawn warms it orange, and the top bar shows the current day and clock. Test count grew from 47 to 68 (21 new tests; all 68 passing).

Project Manager

Contribution: Led the scrum, locked scope, sequenced today's deliverable around the project vision in CLAUDE.md.

Key Decisions:

  • The biggest gap between current state and the project vision was signs of life — villagers with their own routines, plus the real day/night cadence that the spec calls out explicitly. Picked that over alternatives (persistence load, inventory system, multi-town world map) because it's the most visible step toward "a society simulator" and a precondition for jobs/families/economy work later.
  • Capped today's NPC scope at "walk between home and work on a clock." No conversations, no inter-villager interactions, no families yet. Each of those is its own day.
  • Time model: one tick = one in-game hour. With TICK_MS=3500, a full day cycles every ~84 real seconds — fast enough to watch, slow enough to read.
  • Kept all the simulation in plain JS for now. The CLAUDE.md TypeScript/PostgreSQL/PG-BOSS goal stays deferred; the simulation isn't yet stable enough to be worth porting.

Reasoning: Visible, animated life on the map is the next thing the user will feel when they open the page. Building the time + NPC substrate today unblocks every future social/economy feature.

Backend Developer

Contribution: Implemented all server-side mechanics.

Files Created:

  • server/Villager.js — Entity. Constructor validates profession against a registry. targetAt(hour) returns home or work tile based on whether the hour falls in the villager's work window (07–19 for day workers, 21–05 for night owls). step(hour, grid) advances one tile per tick toward the target, refusing to walk into water. serialize() produces the compact {id,name,profession,color,x,y} shape that goes over SSE.
  • server/NPCManager.js — Owns the population. Builds the roster from a recipe constant (ROSTER_RECIPE): 3 Farmers, 1 Smith, 1 Priest, 3 Merchants, 1 Innkeeper, 2 Guards, 2 NightWatch, 1 Baker = 14 villagers. Assigns each a home tile and a work tile drawn from named building locations or rotating fields/patrol nodes. tick(hour, grid) steps every villager once per simulation tick.
  • server/TimeOfDay.js — Pure helpers: hourOf, dayOf, phaseOf, darknessOf, formatClock. Phase boundaries: dawn 05–07, day 07–18, dusk 18–20, night 20–05. Darkness scales 0 → 0.78 with night the darkest.

Files Modified:

  • server/SimEngine.js — Added #totalHours (starts at 8 so the town wakes up immediately), #npcs, #grid. Snapshot now exposes time and villagers. #tick advances #totalHours, calls NPCManager.tick, and runs #logPhaseTransition to emit a [TIME] event at each phase boundary.

Key Technical Decisions:

  • Profession is a registry pattern, not a class hierarchy. Each profession is just data (color, nightOwl, target hint) on the PROFESSIONS map — adding a new profession is a one-line change.
  • targetAt(hour) is deliberately stateless: given a villager and an hour, it returns the same answer every time. That makes the schedule trivially testable.
  • Movement is Manhattan stepping (one axis per tick). Diagonal pathfinding would be neater but adds A* complexity that isn't yet justified — agents reach their destinations within a few ticks either way.
  • Water is the only blocker for now. Trees/walls/buildings stay passable because the home/work tiles themselves sit on building tiles, and pathing around them would cost more code than the visual fix is worth at this scale.

Infrastructure Note: The file-edit tool truncated server/SimEngine.js at line 188 mid-method (silent failure — vitest didn't catch it because esbuild was lenient enough to parse the partial file). Resolved by rewriting the full file via bash heredoc, same as the Day 2/3/4 workaround. Adding node --check to the verification step caught it; the Day 2 risk-log note about template literals is now generalized to "always verify the full file with node --check after large edits."

Frontend Developer / Designer

Contribution: Wired the new snapshot fields into the canvas and top bar.

Files Modified:

  • client/src/components/WorldMap.jsx — Added a villagers pass after the hero draw: each villager renders as a 3.2px filled circle in their profession color with a thin black outline. Added a day/night overlay: a colored translucent rectangle covers the whole canvas, tinted blue at night, orange at dawn, deep-orange at dusk. Night adds four lantern radial gradients over the buildings using globalCompositeOperation = 'lighter' so the lamps actually glow through the darkness.
  • client/src/App.jsx — Passes villagers and time to WorldMap. Added a center segment to the top bar: Day N · HH:00 · Phase with a phase-tinted text color.

Design Decisions:

  • Profession colors picked to be distinguishable at 3px — Farmer green, Smith orange, Priest cream, Merchant pink, Guard blue, NightWatch purple, Baker tan, Innkeeper amber. Tested in browser; all readable on the parchment-warm tile palette.
  • Lantern halos use additive blending so they brighten the overlay rather than draw fresh pixels — feels more like lamplight, less like sprite work.
  • Phase label is the same color as the dot a villager would wear in that phase — small consistency cue.

Tester / QA

Contribution: Designed three new test files; verified the full suite stays green.

Test Files Created:

  • server/Villager.test.js (10 tests) — Schedule edges: day worker target at hours 6/7/10/18/19/2; night owl target at hours 2/4/7/12/22. Movement: step direction, water avoidance, target-reached stationary case. Construction: unknown profession throw, color exposure, serialize shape.
  • server/NPCManager.test.js (5 tests) — Roster count matches recipe total. Unique IDs. Serialize wire shape complete. tick(12, grid) at noon moves at least one villager. After 48 simulated hours, every villager is still inside the 24×24 grid.
  • server/TimeOfDay.test.js (6 tests) — hourOf wrap, dayOf counter, phase boundaries at every transition hour (5, 7, 18, 20), darkness ordering, clock formatting.

Results: 68 / 68 tests passing. npm test exits 0. Live engine smoke-test confirmed: 14 villagers spawned, snapshot includes time and villagers payloads, snapshot serializes to JSON cleanly for SSE.

Risk Log:

  • File truncation in SimEngine.js (now mitigated by node --check in verify step).
  • Movement still allows villagers to step onto building tiles. Visually they look fine because they land exactly on the building marker pixel, but if we later draw building roofs over the top, villagers will vanish into them. Flag for a future pathfinding pass.

What Was Built

  • 14 named villagers across 8 professions, each with a clock-driven home/work schedule
  • 24-hour day/night cycle with dawn/day/dusk/night phases and per-phase darkness
  • Canvas overlay tints the map at night, dawn, and dusk; lantern halos light the buildings at night
  • Top-bar clock: Day N · HH:00 · phase
  • Phase-transition log events ([TIME])
  • 21 new tests across 3 new test files

Verified: Vex the Mage was assigned Slay 3 Goblins at sunrise; villager Quill the Farmer was already walking toward the eastern field; the night overlay drops cleanly at hour 20 with the four lanterns visible around the central market.

Tomorrow (Day 6 Candidates)

  • Villager interactions: when two villagers cross at the market square mid-day, log a small "chat" event for flavor.
  • Persistence load: read saves/hero-*.json on boot if present.
  • Multi-hero parties: a second hero spawns and joins the active hero on the map.
  • Pathfinding upgrade: A* with building tiles treated as blockers (prerequisite if we add building roofs).
  • First step toward families: assign each villager a partner / household id; couples share a home tile.