ARCANUM
← Blog
architecture

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.

2 Nov 2026 · 13 min read · part 2 of 3

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.

Sim dirty + jitter 1.0-1.5 s PositionCoalescer one slot per character Fast producer Acks::Leader meadow_positions 4 partitions put On boot the topic is replayed into Sim, so players reappear where they stood.On shutdown every player is written again with Acks::All.
Latest wins, and a slow broker costs freshness rather than memory

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 on meadow_attributes with writerId 0 (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.

Meadow Sim moves, crafts, shops Realm worker kills, pickups meadow-world transactional producer realm-<serverId> group txn queue meadow_inventory compact, per slot meadow_attributes meadow_xp / meadow_gold ledgers Views xp_total, gold_balance the meadow also tails realm writes (writerId != 0) after boot
Two writers, one set of topics, and a tail in the opposite direction

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

  1. Claim in memory. GroundItems::claim either succeeds or fails with TAKEN, RANGE or GONE. A second claimant never gets the item. Ranges: click 1.8 m, arrive 1.4 m, gold auto-pick 6 m.
  2. 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-zero entryId) or inventory slot writes.
  3. Slot writes get what is left of the budget: 8 - (respawn ? 2 : 1). If the item does not fit, release the claim and fail with FULL.
  4. On commit, finishPickup calls items_.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 after GOLD_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
1 Claim in memory 2 Transaction max 8 ops 3 Rune commit ok finishPickup failed release claim gone broadcast, deadline set item stays, gold retries 1 s What is in the transaction ground item tombstone spawn point deadline (if any) gold entry OR inventory slots 8 ops at most, or FULL Two players, one item: the second claim fails TAKEN before any record is written.
Claim first, write second, announce last

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. At expiresAt a write changes it to CLOSING. After CLOSE_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 cleared event on realm_events calls closeNow: the dungeon is done, so the portal closes.
OPEN write, 300-900 s CLOSING write at expiresAt GONE tombstone +1100 ms cleared from a realm Every arrow is a one-op transaction on meadow_portals, so the topic always holds the latest state. On boot the stored portals are replayed and expired ones are tombstoned on the first tick.
A portal is three records, at most

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.

← Part 1 · Next: part 3, the realm handoff →

← All posts