Exact source used by this build. SHA-256: 20161305ca813715c5dab986e235413f5177743d2978e7ff778a0a7e13d41523.

1 # Community system integration
2 
3 ## Integration into main
4 
5 See [the integration-2 report](../../../../../docs/w3-integration2-report.md).
6 Bundles now accept real fish/crops/artisan goods/minerals. Museum minerals reuse
7 the mines catalog; fishing treasure contains eligible minerals and artifacts.
8 Producer tests obtain and donate those actual inventory items. These producers
9 use their own drop/treasure RNG, rather than calling `awardMuseumFind` to create
10 an extra reward. Rod/pot catches populate the shared fish collection and trusted
11 villager quest progress. The former absent-producer notes below describe the
12 original branch. Cooking/crafting collection callbacks remain available for
13 separate recipe integration; they are outside the requested animal-machine path.
14 
15 `communitySystem` owns the shared `world.systems.community` slice. Inventory,
16 energy, money and base area tiles are updated only through validated actions
17 and the owning inventory/money helpers. No collection or achievement increment
18 intent exists. All counters, museum ownership, displays, bundle contributions,
19 reward claims and completed repairs persist in snapshots and journals.
20 
21 Register this system after shipping so the overnight observer sees the settled
22 ledger. `onPresenceChange` hydrates new/old saves with the injected content and
23 spawns the first day's artifact spots. Daily spawns use persisted seeded RNG.
24 
25 ## Actions
26 
27 - `bundleDonate {bundleId, requirementId, slot, quantity}` accepts partial
28   contributions from either player. At most `choose` requirements can be active;
29   a partially filled choice is completed before another choice is started.
30   Item IDs/tags, minimum quality, quantity and station proximity are authoritative.
31 - `communityClaimReward {rewardId}` claims one shared reward exactly once.
32   IDs are `bundle:bundle_01` and `museum:5`, for example. A full backpack leaves
33   every item and the claim available. Bundle rewards stay at the ruined building;
34   museum rewards require the museum's hours and location.
35 - `museumDonate {slot, displaySlot}` consumes one previously undonated eligible
36   item. `museumMoveDisplay {fromSlot, toSlot}` moves or swaps donated pieces.
37   The grid has 102 spaces. Both players edit the same gallery.
38 - `digArtifactSpot {spotId}` requires a physical, available hoe, energy, a clear
39   tillable tile, inventory space and proximity. The spot's seeded item is chosen
40   when it spawns, and successful digging tills its tile and removes it once.
41 
42 ## Trusted producer hooks
43 
44 `awardMuseumFind(state, playerId, "mines" | "fishingTreasure", rules)` is called
45 by a server-validated mine-node or treasure completion handler. It selects one
46 eligible museum item using persisted RNG and adds it atomically. On inventory
47 failure it returns the original state and RNG; the owning producer must retain
48 its pending reward. It is not a network intent. Until those producer systems
49 are registered, every MVP museum item can also occur at artifact spots; minerals
50 have one quarter the individual artifact weight.
51 
52 `recordCollection(state, "fish" | "cooking" | "crafting", id, count, rules)` is
53 called after a verified catch/cook/craft result. Fish require a catalog fish item;
54 cooking/crafting accept trusted recipe IDs so another domain can register recipes
55 without shared-code changes. Shipping is observed automatically from its durable
56 cumulative counts. Museum counts come exclusively from accepted museum donations.
57 These collections are shared. Recipe knowledge remains owned by the relevant
58 per-player producer system. The 40-entry shipping catalog is seeded in content;
59 future fish/recipe catalogs can populate the empty typed lists, and recorded
60 entries are retained independently of catalog availability.
61 
62 ## Repairs and numerical scope
63 
64 Room 01 opens `town-canyon`; room 02 restores a 7 by 6 greenhouse soil patch at
65 the existing farm ruin; room 03 opens `beach-rainforest` and `woods-bog`.
66 `isWarpRepaired` supplies the generic movement authorization hook. Repairs also
67 project to immutable warp and destination-area metadata so map barriers and
68 area spawning agree. Synchronization reconciles this projection on saved worlds.
69 `isGreenhouseTile` supplies the generic out-of-season crop exception for both
70 planting and overnight growth. Restoring the greenhouse enables its soil.
71 
72 The 12 achievement definitions retain numerical thresholds independently of
73 MVP content counts. The 40- and 95-donation achievements and later recipe
74 thresholds can remain locked until their future content arrives. Museum reward
75 thresholds are 5, 10, 15, 20, 25, 30, 35, 40, 50, 60, 70, 80, 90 and 95. The MVP
76 contains 14 mineral and 11 artifact slots. Creative names/descriptions and all
77 visual manifest keys remain explicit TBD placeholders.
78