Exact source used by this build. SHA-256: ca0633fe3802da3b41fce2a8ba8195e4922638829aa9e5169913cc3a3a7096fe.
1 # Villagers and friendship
2
3 The `villagers` domain and simulation/client systems provide ten placeholder
4 villagers, three marriage candidates, shared NPC schedules, and independent
5 friendship, dialogue, events, mail and quests for each player. No production
6 server handler, protocol envelope, scene coordinator or map was changed.
7
8 ## Main integration (2026-10-22)
9
10 - NPCs now walk only in `onElapsedTime`. Calendar ticks select the next route
11 with zero travel, so the shared clock's boundary splitting cannot charge an
12 interval twice. Moving NPCs request the content-owned 1,000 ms simulation
13 cadence; stopped NPCs preserve state identity and use the normal clock cadence.
14 Walking emits no durable event and therefore remains within the generic
15 30-second checkpoint policy. Offline and explicit pause freeze NPCs.
16 - Every existing schedule/event target resolves to an accessible canonical POI
17 in `docs/maps.md`; the full-day traveler still reaches town, woods, farm and
18 beach. Villager festival dates are validated against the festival domain.
19 - The shared shop implementation retains integrated geode cracking and shops
20 supplied by other domains, while applying keeper presence to authority and
21 client availability. Villager 06 staffs the carpenter at
22 `poi.town.meeting_hall_bench_01`; villager 05 staffs ranch supplies at
23 `poi.town.sugar_shack_counter`. Both retain physical commutes and absences.
24 - Gift preferences include actual fish, cooked meals, artisan goods and minerals,
25 alongside existing crops/forage. Requests now include actual forage, cooked
26 meal and mineral deliveries, and the fishing request uses a real fish reward.
27 Item IDs and target tags are validated. Fishing/mines producers report catches,
28 kills and mined resources through the existing trusted quest-progress helper.
29 - New integration regressions compare one elapsed update with 56 smaller
30 updates across clock boundaries, verify offline/pause and idle cadence, enforce
31 carpenter/ranch keeper presence, and cover all five requested gift/quest item
32 categories. All original social, schedule, gathering and presentation assertions
33 remain. The real TCP two-player full-day loop passes unchanged. The older
34 mining/geode integration fixture now advances the real clock through the
35 blacksmith's commute before asserting its original price and output behavior.
36
37 The original branch report below is retained as implementation history; its
38 standalone-check counts and future-producer notes predate this integration.
39
40 ## Behavior
41
42 - Schedules choose festival, rain/storm, seasonal, weekday override, then ordinary
43 weekday entries. Canonical Tiled POIs supply coordinates. NPCs use collision-grid
44 A* and the unlocked warp graph, walking at 1.875 tiles/second. Save hydration
45 starts missing NPCs at the current schedule entry; subsequent travel is physical.
46 - Friendship uses 250 points/heart; talk earns 20 once daily; gifts are limited to
47 one/day and two/week independently for each player. Taste, positive-taste
48 quality multipliers, birthday exceptions, Sunday reset/bonus, dating caps and
49 decay are supported. Ordinary friends cap at 2,500; candidates have the hidden
50 2,249 pre-bouquet cap with decay stopping at 2,000; spouses cap at 3,500.
51 - A mapped shopkeeper must stand at the shop counter as well as satisfy hours.
52 The client displays the same availability used for purchases, sales and upgrades.
53 - Dialogue resolves authored conditions/fallback order; the bottom dialogue panel
54 reveals 64 characters/second with tap-to-skip/advance and portrait/name slots.
55 - Three sample heart events have gated triggers, POI actors, movement, facing,
56 dialogue, choices and fades. Choice rewards are persisted to prevent replay
57 farming across overnight interruptions.
58 - Mail arrives per player on daily processing. Reading recipe letters records
59 their recipe IDs. The board posts daily; delivery consumes inventory; gathering
60 counts successful tool resource production and forage pickup. Requests pay
61 three times the base item price times quantity and 150 friendship, once.
62 - Bouquet, proposal, exclusive engagement, wedding after three days, spouse heart
63 cap and daily spouse gifts work. Daily spouse chore requests are typed hooks.
64
65 ## Files
66
67 ```text
68 apps/
69 client/
70 src/systems/villagers/
71 index.ts
72 model.ts
73 panel.ts
74 dialogue.ts
75 event-player.ts
76 test/villagers-presentation.test.ts
77 server/test/villagers-loop.test.ts
78 packages/
79 content/
80 data/items/villagers.json
81 data/villagers/
82 villagers.json
83 voices/villager_01.json … villager_10.json
84 src/domains/villagers/
85 index.ts
86 schema.ts
87 test/villagers-content.test.ts
88 sim/
89 src/systems/villagers/
90 index.ts
91 types.ts
92 model.ts
93 friendship.ts
94 schedules.ts
95 pathfinding.ts
96 README.md
97 test/
98 villagers-social.test.ts
99 villagers-gathering.test.ts
100 ```
101
102 ## Shared changes
103
104 These are the small integration exceptions required by the existing architecture:
105
106 - `packages/sim/src/systems/index.ts`,
107 `packages/content/src/domains/index.ts`,
108 `apps/client/src/systems/index.ts`: import/register the new system/domain.
109 - `packages/sim/src/systems/shops/index.ts` and
110 `apps/client/src/systems/shops/index.ts`: combine hours with keeper presence,
111 including the displayed open/closed state.
112 - `packages/sim/src/systems/tools/index.ts` and
113 `packages/sim/src/systems/forage/index.ts`: report earned gathering progress
114 after successful authoritative resource production/pickup.
115 - `packages/content/test/domains.test.ts` and
116 `apps/client/src/core/registry.test.ts`: update explicit registry expectations.
117 - `apps/client/public/assets/CREDITS.md`: credit new procedural placeholders CC0.
118
119 No runtime dependency was added. No commit, deploy, login, credential operation,
120 remote push or history rewrite was performed.
121
122 ## Validation
123
124 The two-client test uses actual TCP WebSockets and production `FarmWorld`
125 authentication, intent validation, dispatch, journaling, broadcasts and SQL
126 checkpoints. Its Cloudflare socket/storage adapters and elapsed time are replaced
127 by the test harness. After initial fixture setup, gameplay changes use server
128 intents and alarms. It checks independent talk/gifts, repeated-gift rejection,
129 inventory consumption, every full-day traveler stop across four areas, NPC speed
130 and warp transitions, shop closure during the keeper's lunch, and persisted
131 relationships/NPC state after overnight. Existing workerd tests separately
132 exercise the local Cloudflare runtime transport.
133
134 Additional tests cover content references/POIs, isolated system registration,
135 friendship boundaries, dialogue fallback, event replay protection, mail,
136 delivery/gathering rewards, trusted future progression hooks, romance, typewriter
137 timing, NPC interpolation and event reconstruction.
138
139 Final integration results:
140
141 ```text
142 $ bun run check
143 180 pass
144 0 fail
145 7123 expect() calls
146 Ran 180 tests across 37 files. [55.70s]
147 Validated 13 content domains: 12 crops, 60 items, and 8 Tiled areas.
148
149 $ bun run --cwd apps/client build
150 233 modules transformed.
151 built in 408ms
152 JS 2,682.32 kB / gzip 473.27 kB
153
154 $ bun test apps/server/test/villagers-loop.test.ts
155 1 pass
156 0 fail
157 270 expect() calls
158
159 $ git diff --check
160 (no errors)
161 ```
162
163 Vite reports a chunk larger than 500 kB; the build succeeds. The final build was
164 rerun after the last client changes. Targeted content, social, gathering and
165 presentation tests and package typechecks also passed. Browser launch failed
166 before page verification, as described below.
167
168 ## Remaining integration hooks and authoring slots
169
170 - Fishing and monster quest definitions/progression are implemented and tested
171 via `recordVillagerQuestProgress`; their producer systems do not yet exist in
172 this checkout. Those systems must call this helper after authoritative catches
173 or kills. No client-supplied progress intent is accepted.
174 - Recipe mail records opaque `recipe_cook_01` through `recipe_cook_10` unlocks;
175 the cooking system must consume these. Romance-item purchasing, a wedding
176 presentation, house/nursery requirements, and executing spouse chores remain
177 future integration work. Chore requests do not mutate other systems' slices.
178 - Festival dates/schedule overrides are local MVP content; a future festival
179 domain should coordinate its calendar with these four entries.
180 - All ten names/descriptions, relationship descriptions, all 381 dialogue/event/
181 mail/quest text values and visual text are `TBD`; ten voice sheets are empty.
182 All artwork is colored procedural placeholders with manifest keys. No dialogue,
183 lore, proprietary art, or borrowed creative content was authored.
184 - Phone styles enforce 44-pixel minimum targets, responsive social panels and a
185 bottom dialogue panel capped at 40% viewport height. Visual browser QA could not
186 run: Chrome aborted during sandboxed Playwright launch and computer-use had no
187 browser surface. Helper tests and TypeScript/build validation are not a visual
188 verification substitute.
189 - Distant NPC motion interpolates the last server tick's route; nearby NPCs snap
190 to their authoritative position for interaction accuracy. Event presentation
191 moves actors directly between authored POIs. Schedule navigation uses A*.
192
193 ## Working tree and storage
194
195 All implementation changes are uncommitted, consistent with the project rule
196 requiring an explicit commit instruction. The starting working tree was clean.
197 The file tree and shared changes above account for the remaining modified and
198 untracked source files. No unrelated user changes were overwritten.
199
200 The generated test-state SQLite directory and temporary Playwright/npm install
201 were removed after verification. The ignored current client build (about 2.6 MB)
202 and generated content catalogs (16 KB) remain for review/reuse. No new unusually
203 large ignored or untracked artifact remains; the pre-existing dependency folder
204 is unchanged.
205
206 Numerical parity was checked against the repository's content-targets/time/feel
207 documents and the [friendship mechanics reference](https://stardewvalleywiki.com/Friendship).
208 Only mechanics were used.
209