Hanamori on Rune, part 2: positions, inventory, loot and portals
How the meadow writes and replays the state that changes every second: positions, attributes, inventory, rewards, loot pickups and portals. With the real code.
Part 1 covered the vocabulary: topics, views, boot replay, login and the transaction queue. (The meadow server is Hanamori's open-world server; realm servers run the dungeons.) This part covers the data that changes every second. We will follow four things: where a player stands, what a player earns and owns, what lies on the ground, and when portals open. Each one uses the same few tools in a slightly different way, which is the point of having tools. Part 3 then takes a hero through a portal.
1. Positions: a coalesced, compact topic
Positions go to meadow_positions: four partitions, compact, Acks::Leader, key = character id. The Sim thread does not write one record per step.
A moving player is flagged dirty. In step 7 of every tick, a dirty player whose nextPersistAt has arrived is written, and the next write is scheduled
1000 ms later plus a random 0 to 512 ms, so a few hundred players never all write on the same millisecond. The jitter is deliberate; synchronised herds are a reliable way to
find out how a network feels about bursts.
// SimWorld, tick step 7 (shape) constexpr int64_t PERSIST_PERIOD_MS = 1000, PERSIST_JITTER_MS = 512; if (ps.dirty && nowMs >= ps.nextPersistAt) { writePosition(ps, /*acksAll=*/false); // also refreshes lastPos_ ps.nextPersistAt = nowMs + PERSIST_PERIOD_MS + rng() % (PERSIST_JITTER_MS + 1); }
writePosition also updates lastPos_ in memory. That matters: a player who disconnects and returns within the same second is admitted at the position the server
last knew, not at a stale one the log has not caught up with.
The Rune thread does not send every write either. PositionCoalescer keeps one slot per character; put overwrites whatever was waiting and drain hands the slots to the fast producer
(drainFast_). Each send returns Ok, BackPressured (keep the slot, stop for now) or Dropped (counted). So if Rune is slow or down, the meadow loses
freshness, never memory: the queue cannot grow beyond one entry per player. Spawn-point deadlines use the same fast producer.
The shutdown flush
Leader acks are fast but they are not a promise. So on a clean shutdown SimWorld::shutdown() writes every player's position with acksAll=true, dirty or not. The Rune thread holds the coalescer
for that flush and shutdownFlush_ writes the remainder with an Acks::All producer, bounded to 10 s, then sends SHUTDOWN_DONE. After that the process may exit, and nobody has
lost where they were standing.
2. Attributes, XP, gold and inventory
Each inventory slot is one record on meadow_inventory, keyed by slotKey. A move is therefore two records (the cleared source and the filled
destination), and both are written in one transaction. The rule that makes this safe lives in the Sim thread: pendingTxn_ allows one inventory-changing transaction per character at a time,
and nothing in the in-memory caches changes until the commit comes back (onTxnDone). A rejected commit leaves the memory exactly as it was.
// SimWorld::onInventoryMove (shape) if (pendingTxn_.count(charId)) return reject(); // one at a time auto plan = planMove(bag, from, to); // yields 2 SlotWrite pendingTxn_[charId] = PendingTxn{plan}; // remembered, not applied toRune(Txn{ inventoryRecord(plan.a), inventoryRecord(plan.b) }); // ... later, in onTxnDone(ok): apply plan to the cache, tell the client
Other handlers follow the same pattern:
onSpendAttribute: one record onmeadow_attributeswithwriterId0 (meaning "the meadow wrote this").onEquipMove: like a bag move, between the bag and equipment slots.onCraft,onShopBuy,onShopSell: inventory records plus one gold ledger entry (goldOp) in the same transaction. The station must be within 7 m (nearStation). Paying and receiving the item are one atomic fact, which is more than most real-world shops can say.
Level and unspent attribute points are not stored anywhere. They are derived from the XP total and the spent attributes (hsim::level::levelOf, unspentPoints). Storing the inputs
and computing the output means the two can never disagree.
Rewards arriving from a realm
Dungeon rewards are written by realm servers, not by the meadow. XP is a meadow_xp ledger entry, gold is a meadow_gold entry, and loot is meadow_inventory records, each carrying
writerId (the realm's server id) and an ownerEpoch. The meadow tails those topics after boot, accepting only records with a non-zero writerId, and applies them. A
cleared slot arrives as a record with quantity 0. Part 3 explains why the meadow waits for exactly the right number of them before it lets a hero back in.
3. Ground items and the 8-op pickup
Loot on the ground is a record on meadow_ground_items (key itemId). Items spawn at baked spawn points, at most one per point (GroundItems::tick). A spawn is a
standalone one-operation transaction. Drops from mobs and players have a source of 1 or 2 and despawn after 10 minutes (DROP_DESPAWN_MS); when due, the meadow writes a tombstone.
When the meadow restarts, it replays the topic and gets the items back without a clock: records do not carry timers. The first tick spawns only spawn points that are empty and whose
nextSpawnAt is due (default 0 means due), so a restart does not respawn everything early. The respawn deadline is itself a record on meadow_spawn_points
(startedAt + respawnS * 1000), written by the pickup below.
The pickup
- Claim in memory.
GroundItems::claimeither succeeds or fails withTAKEN,RANGEorGONE. A second claimant never gets the item. Ranges: click 1.8 m, arrive 1.4 m, gold auto-pick 6 m. - Build one transaction, at most 8 operations (
msg::Txn::MAX_OPS): the ground-item tombstone; the spawn-point respawn deadline if the item came from one (respawnFor); and then either a gold ledger entry (reason 0, a random non-zeroentryId) or inventory slot writes. - Slot writes get what is left of the budget:
8 - (respawn ? 2 : 1). If the item does not fit,releasethe claim and fail withFULL. - On commit,
finishPickupcallsitems_.commit: tell everybody the item is gone and set the in-memory respawn deadline. On failure,items_.release: the item stays and the claim is undone. A gold auto-pick tries again afterGOLD_RETRY_MS(1000).
// SimWorld::startPickup (shape) auto c = items_.claim(itemId, player); // TAKEN | RANGE | GONE | ok if (!c.ok) return fail(c.why); Txn t; t.add(groundItems, itemId, /*tombstone*/); // op 1 if (c.respawn) t.add(spawnPoints, spawnPoint, startedAt + respawnS * 1000); int budget = 8 - (c.respawn ? 2 : 1); if (isGold) t.add(gold, randomNonZero(), delta); // reason 0 else if (!addSlotWrites(t, budget)) { items_.release(c); return fail(FULL); } toRune(t); // finishPickup() runs on commit
4. Portals: expiry and early close
The portal scheduler lives in the Sim. Each state change is a standalone one-operation transaction on meadow_portals (key portalId), so the topic always holds the latest state of every portal.
- Spawning. At most 4 are live (
MAX_LIVE). A new one appears 22 to 80 m from a random online player, every 6 to 12 s while fewer than 2 are live and every 30 to 60 s otherwise. With nobody online, none spawn. The rank is rolled with weights GREEN 50, YELLOW 28, RED 15 and PURPLE 7. - Life. A portal is open for
OPEN_MS(1300 ms) plus a random 300 to 900 s. AtexpiresAta write changes it to CLOSING. AfterCLOSE_MS(1100 ms) a tombstone removes it. - Entering. The player must be within
SEAL_RANGE(3 m). - Boot. Portal records are staged and applied on the first tick by
restore, which tombstones any that have already expired. - Early close. A realm
clearedevent onrealm_eventscallscloseNow: the dungeon is done, so the portal closes.
5. When a subscription ends
Subscriptions can end (a session is lost, a leader moves, a broker restarts). SubResume and TailRearm handle it. A tail that ends is re-armed from
position(), the offset after the last record delivered, with a delay of 1 s, 2 s, 4 s and so on, capped at 30 s. The exception is a transient topic: its offsets restart after a broker restart, so it
is re-armed from the start of the log instead (kRearmFromLogStart). A Rune subscription also counts dataResets() when a transient partition's data was reset under it, and when that rises, or a tail is re-subscribed,
the Rune thread sends REALM_TOPICS_RESET to Sim so the realm bookkeeping rebuilds from the log. A subscription that is part of boot is different: it ends the process, because a half-replayed world is worse than a restart.