docs/rust-link/PLAYER_WALK.md

The player walk — proving the half of the read path a console cannot reach

Protocol 2's catalogue divides cleanly in two, and the line is not about importance: it is about whether a hook can fire without somebody holding a mouse.

Everything in the first half was proven from a console and a REST client while phase 3 was built — the boards, the wipe id, the envelope, bans, the server lifecycle. Everything below needs a real player on a real server, because the hooks carry a BasePlayer, a HitInfo or a chat line, and none of those three can be manufactured from a console without becoming a different test.

This document is the walk that closes it. It takes about ten minutes, it is the same on Oxide and on Carbon, and it is written so that the answer is readable afterwards rather than watched live.

---

Before you start

1. A rig running, with RunicGateway.cs loaded — oxide.plugins (or c.plugins) lists Runic Gateway, and rg.link answers connected=True.
2. A sidecar the rig can reach, with its store empty — that is what makes the event list at the end readable as a transcript of the walk and nothing else.
3. The sidecar's token to hand, for the reads at the bottom.

Run this once, before you join:

rg.hooks

Every player hook should read silent. That is the baseline: the point of the walk is to move them, and starting from a run where some already fired proves less.

---

The walk

Do these in order. The order matters only in two places, noted where it does.

#	Do this	Fires	The frame should carry
1	Join the server	CanUserLogin, OnUserApproved, OnPlayerConnected	Three frames, in that order. The first two carry your IP address — check it is a real address and not the string 0. player.connected carries your steam id and name
2	Wake up / spawn in (click Respawn if you are dead)	OnPlayerRespawned	player.respawned, steam id only. It does not fire if you simply wake from sleeping — that is the hook's own documented behaviour, so no frame here is a pass, not a failure
3	Say something in chat, then say something in team chat if you have a team	OnPlayerChat	Two player.chat frames, with channel reading Global and Team. The message must arrive whole — if it is truncated or the frame is missing, the flattener ate it
4	Chop a tree for about twenty seconds, then mine a node	OnDispenserGather	Nothing immediately. This is the aggregate: one player.tally frame within 60 seconds, carrying gathered with wood and stones, summed. Seeing a frame per swing would be the bug
5	Kill an animal or a scientist	OnEntityDeath	Again nothing immediately — npcKills on the next player.tally. No player.death: a chicken is not a killfeed entry
6	Die to the environment — fall damage is easiest	OnPlayerDeath	player.death with attackerType: "environment", a grid like H7, and no attackerId. Check the grid against the map: a wrong sign in the row arithmetic mirrors the whole map, and only a human with the map open can see that
7	Kill yourself — kill in the F1 console	OnPlayerDeath	attackerType: "self", no attackerId
8	If a second player is available: kill each other once	OnPlayerDeath	attackerType: "player", with attackerId, attackerName, a weapon shortname and a distance in metres. This is the killfeed's whole shape, and it is the one row phase 4's page is built from
9	Build a foundation, then destroy it yourself	OnEntityDeath	entity.destroyed with ownerId (yours), prefab, grid and attackerId. Decay must not produce one of these — only a player breaking it
10	Disconnect	OnPlayerDisconnected	player.disconnected with a reason and a sessionSec roughly equal to how long you were on. It also flushes your tally first, so any gathering since the last minute arrives immediately before it

Two ordering notes: step 4 must come before step 10 by at least a minute if you want to see the cadence flush rather than the disconnect flush, and step 1's three frames are the only place the order between hooks is itself part of the answer.

---

Reading the result

From the machine running the sidecar:

TOKEN=…            # [web].auth_token from sidecar.toml, or `--print-config`
BASE=http://127.0.0.1:8090

# The whole walk, oldest first, as a transcript.
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/feed?since=0&limit=500" \
  | python -m json.tool

# Or one kind at a time.
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/events?kind=player.death&limit=20"

And from the game console:

rg.hooks

Every hook in the walk should now read fired, with a count. A hook still silent after the step that should have fired it is the finding — and on Carbon it is the specific question CARBON.md §6 asks, since Carbon's catalogue omits thirteen uMod names and nobody has yet checked whether they are renames or holes.

---

What counts as a pass

Not "frames arrived". Three things, and the third is the one worth slowing down for:

1. Every hook in the table fired, on both frameworks, from the same plugin file.
2. Every frame carries the envelope — type, serverId and wipeId on all of them (PROTOCOL.md §8.1). A player frame without a wipeId cannot be attributed to a wipe and its rollup is lost.
3. The aggregates are aggregates. player.tally is a delta since the last flush, so two minutes of chopping is two frames that sum to the total, not two frames each carrying the total. Getting this backwards makes every leaderboard roughly double, and it looks correct until somebody counts.

Anything that disagrees with the table is a finding about the game or the framework rather than a mistake in the table — record it, the same way phases 0, 1 and 2 recorded theirs.

---

The identity walk (protocol 3, phase 6)

Added 2026-09-21, and here for the same reason as everything above: a link code reaches a player and nobody else, so no console can read one. The site's own half was walked in a browser — the refusals, the admin panel, staff unlink, the rate limit — and what needs a person in game is the three steps below.

It takes two minutes, and it wants two website accounts — one you will link, one you will try to link the same Steam account to.

#	Do this	You should see
1	In game, type /link	A private reply with a six-character code and a five-minute deadline. Check it is private: a second player on the server must not see it. The code has no O, 0, I or 1 in it — those glyphs are not in the alphabet, so one in your code is a finding
2	Type /link again straight away	"Please wait a moment…" — the thirty-second cooldown. The first code is now dead either way: a new request drops the old one, so only the newest ever works
3	On the website, sign in and open /player/rust. Type the code	The account appears, named as the game knows you, with the server it came from. Try the same code again: "That code is unknown or has expired" — it works once
4	Sign in as the SECOND account and type a fresh code for the same Steam account	Refused, naming the account that holds it: "That Steam account is already linked to . Run /unlink in game to release it." The link must not move — it is what phase 7 grants permissions against
5	In game, type /unlink	The site's row disappears within one ingest tick (five seconds by default). Reload /player/rust to confirm — this is the frame arriving over the feed, not the page asking
6	Type a code from a server whose sidecar you have just stopped	"One of the servers could not be reached… your code is still good — try again in a minute." Distinct from step 3's refusal, and the distinction is the point: the code is fine and fetching another one would not help

Step 6 needs a fleet of two, one of them down; on a single-server rig it reads "The game servers are unreachable right now" instead, which is the same rule with nothing left to be unsure about.

What counts as a pass here: the code never appears anywhere but in front of the player who asked for it (check the chat log and the sidecar's /events?kind=account.link.requested — the frame carries the steam id, the name and a TTL, and no code), a Steam account belongs to one website account at a time, and every refusal is a sentence that tells the player what to do next.