claude-timemachine
d73c1c9537
8 topical docs (overview, data types, lifecycle, handshake, status/ping, login+encryption, configuration, version-differences) + proxy-forwarding set + 16 per-version release-line docs, sourced from minecraft.wiki, ViaVersion (source + commits), minecraft-data, node-minecraft-protocol, Velocity, BungeeCord. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
130 lines
8.9 KiB
Markdown
130 lines
8.9 KiB
Markdown
# Research & Build Plan — minecraft_protocol
|
|
|
|
How this repo gets built: my orchestration plan (for me) + the task spec every research agent follows (for each agent). Living doc — updated as phases complete.
|
|
|
|
---
|
|
|
|
## 0. Goal & scope
|
|
|
|
A version-aware deep-dive reference for the Minecraft: Java Edition wire protocol, **1.7.10 (protocol 5) → latest (26.2 / protocol 776)**. Two layers:
|
|
1. **Topical foundation** — how the protocol works as a system (framing, state machine, handshake, status, login+encryption, configuration, proxy forwarding).
|
|
2. **Per-version deep-dive** — what changed in *each* protocol-bumping release, sourced from release notes + commits + wiki.
|
|
|
|
## 1. Method — the loop
|
|
|
|
`research → clone → explore → write → verify → repeat`, with citation discipline:
|
|
- Every non-trivial claim cites a source inline: a reference-impl `path:line` and/or a wiki URL/section + fetch date.
|
|
- Wire formats (handshake overloads, encryption, forwarding HMAC, packet IDs) **must** come from source or wiki, never memory.
|
|
- Anything unconfirmed gets an inline `<!-- VERIFY -->` flag; Phase 4 resolves them.
|
|
- Version-aware always: state the version/protocol number where a detail was added/changed.
|
|
|
|
## 2. Source catalog
|
|
|
|
| Tag | Source | Used for |
|
|
|---|---|---|
|
|
| MCWIKI | minecraft.wiki (ex-wiki.vg): `/w/Java_Edition_protocol`, `/w/Protocol_version`, per-version protocol archives, **`/w/Java_Edition_1.X.Y` release articles (release notes)** | spec of record + headline changes per release |
|
|
| VV | `/tmp/mcproto-refs/ViaVersion` — `ProtocolVersion.java` + `protocols/vX_YtoX_Z/` packages | authoritative version numbers + what packets changed between adjacent versions |
|
|
| VV-LOG | ViaVersion **git history** (`git log` on each `protocols/` package) | the commits that implemented each version's changes |
|
|
| MD | PrismarineJS/minecraft-data `protocolVersions.json` + per-version `protocol.json` (raw.githubusercontent) | cross-check numbers + packet field defs |
|
|
| NMP | `/tmp/mcproto-refs/node-minecraft-protocol` | clean reference impl of framing/encryption/ping/states |
|
|
| VELO | `/tmp/mcproto-refs/Velocity` | modern forwarding, login flow, state registry |
|
|
| BUNGEE | `/tmp/mcproto-refs/BungeeCord` | legacy forwarding format |
|
|
| MOJANG | minecraft.net / feedback.minecraft.net changelogs | official release notes per version |
|
|
|
|
**Setup TODO before Phase 3** (commits are a requested source, but refs were `--depth 1`):
|
|
- `git -C /tmp/mcproto-refs/ViaVersion fetch --unshallow` (full history for `git log`)
|
|
- clone `minecraft-data` (sparse `data/pc/`) for per-version `protocol.json`
|
|
|
|
---
|
|
|
|
## 3. Orchestration plan (me)
|
|
|
|
### Phase 1 — Topical foundation (8 docs)
|
|
| Doc | Status |
|
|
|---|---|
|
|
| 00-overview + 01-data-types | ✅ done |
|
|
| 02-connection-lifecycle | ✅ done |
|
|
| 03-handshake | ⬜ re-dispatch (cancelled by interrupt) |
|
|
| 04-status-ping | ✅ done |
|
|
| 05-login-encryption | ⬜ re-dispatch |
|
|
| 06-configuration | ⬜ re-dispatch |
|
|
| 07-version-differences | ✅ done (has the full version map) |
|
|
| proxy-forwarding/ (6 files) | ⬜ re-dispatch (opus) |
|
|
|
|
→ **Action: re-dispatch the 4 ⬜ rows** (specs in §6). Wave 1 closes when all 8 are in.
|
|
|
|
### Phase 2 — Version map
|
|
Build `versions/INDEX.md`: every protocol-bumping release 1.7.10→26.2 with {release, protocol #, release date, ViaVersion package, mc-wiki release-article URL, mc-wiki protocol-archive URL}. Derived from `07` + VV `protocols/` listing + MCWIKI. This index drives Phase 3 and becomes the navigation hub for `versions/`.
|
|
|
|
### Phase 3 — Per-version deep-dive (batched)
|
|
One doc per **release line** under `versions/` (e.g. `versions/1.13.md`), each with a **sub-section per protocol bump** inside that line (1.13=393, 1.13.1=401, 1.13.2=404). Granularity rationale: a full doc per trivial patch bump is noise; a doc per major.minor line with per-bump sections is thorough without 50 stubs. *(If you want one-doc-per-protocol-number instead, say so — easy to split.)*
|
|
|
|
Batched by the **7 eras** from `07` (keeps each wave ≤ concurrency cap, lets us quality-gate between):
|
|
- B1 — Era 1: 1.7.10, 1.8
|
|
- B2 — Era 2: 1.9, 1.10, 1.11, 1.12
|
|
- B3 — Era 3: 1.13, 1.14, 1.15
|
|
- B4 — Era 4: 1.16, 1.17, 1.18
|
|
- B5 — Era 5: 1.19
|
|
- B6 — Era 6: 1.20
|
|
- B7 — Era 7: 1.21, 26.x
|
|
|
|
After each batch: I read the docs, spot-check citations, resolve obvious gaps, then launch the next. Per-version agent spec in §7.
|
|
|
|
### Phase 4 — Verification & polish
|
|
- `fact-verifier` agents on: all `<!-- VERIFY -->` flags, every protocol number in the map, the crypto details (AES/CFB8, serverId hash) and forwarding formats (Velocity HMAC payload, Bungee `\0` string).
|
|
- Cross-link docs; fill the README status table (⬜/✅ per doc); write `references.md`.
|
|
- Then offer to commit + push to `Timemachine/minecraft_protocol`.
|
|
|
|
## 4. Conventions (all phases)
|
|
|
|
- **Models**: research/writing agents = `sonnet`; hard synthesis (proxy-forwarding, big-era version docs) = `opus`; never `haiku` for protocol reasoning. Verifiers = `fact-verifier` type.
|
|
- **No nested fan-out**: every agent works directly, spawns **no** sub-agents.
|
|
- **One file owner**: each agent writes only its assigned file(s) — no two agents touch the same file (parallel-safe).
|
|
- **Citations + VERIFY**: as §1.
|
|
- **Mermaid**: sequence/state diagrams for flows; parse-safe (quote labels containing `:` or special chars).
|
|
|
|
---
|
|
|
|
## 5. Per-agent task spec (common template)
|
|
|
|
Every research agent is handed:
|
|
1. **Exact output path(s)** in `~/Documents/minecraft_protocol/`.
|
|
2. **Topic** + the specific points to cover.
|
|
3. **Sources to read**, by path/URL (from §2), with the instruction to cite `path:line` / wiki-URL inline.
|
|
4. **Format**: markdown, headers + tables; mermaid for flows; example payloads where useful.
|
|
5. **Rules**: version-aware; wire formats from source not memory; `<!-- VERIFY -->` for anything unconfirmed; **no sub-agents**; touch only the assigned file(s).
|
|
6. **Report back**: file path(s) + 3-line summary + any VERIFY flags + (for format-critical docs) the exact extracted format with its citation.
|
|
|
|
## 6. Phase-1 re-dispatch assignments (the 4 pending)
|
|
|
|
- **03-handshake.md** (sonnet) — handshake packet fields; SRV; serverAddress overloads: Forge `\0FML\0`/`\0FML2\0`/`\0FML3\0`, BungeeCord legacy `host\0ip\0uuid\0props` (exact, from `BUNGEE/.../InitialHandler.java` + `ServerConnector.java`), note Velocity-modern uses a login plugin msg instead; transfer next-state(3)=1.20.5+.
|
|
- **05-login-encryption.md** (sonnet) — login packet flow; RSA-1024 + AES/CFB8; serverId negative-hex SHA-1; online-mode join/hasJoined (Mojang session server); compression (1.8+); 1.19 profile keys. Sources: NMP `client/encrypt.js`, `transforms/encryption.js`; VELO `EncryptionRequest/ResponsePacket.java`; MCWIKI Protocol_Encryption.
|
|
- **06-configuration.md** (sonnet) — the 1.20.2 Configuration state; registry/tags/packs → Finish; re-configuration loop; Known Packs (1.20.5). Sources: MCWIKI Configuration; NMP/VELO state handling.
|
|
- **proxy-forwarding/** (opus, 6 files) — README, online-offline-modes, bungeecord-legacy, velocity-modern, bungeeguard, forge-fml. Velocity HMAC payload from `VELO/.../PlayerDataForwarding.java` + `VelocityConstants.java`; Bungee format from `BUNGEE/.../InitialHandler.java`+`ServerConnector.java`. Comparison table; mermaid for both forwarding flows.
|
|
|
|
## 7. Phase-3 per-version agent spec (template)
|
|
|
|
For release line **X** (e.g. 1.16), write `versions/X.md` covering every protocol bump in that line. Each agent:
|
|
|
|
**Read:**
|
|
- MCWIKI release article(s) `/w/Java_Edition_X` and each patch → headline gameplay + technical changes (**release notes**).
|
|
- MCWIKI protocol archive for X (the version-specific protocol page / the diff section).
|
|
- VV package(s) for the bump(s) into X — `protocols/vPREVtoX/` — the `ProtocolPREVToX.java` + `Clientbound/ServerboundPacketsX` enums = the authoritative changed-packet list. AND `git -C ViaVersion log --oneline -- <that package>` = the **commits** that implemented it.
|
|
- MD `protocol.json` for X (raw fetch) to cross-check packet IDs/fields.
|
|
|
|
**Write** `versions/X.md` with:
|
|
- Header: release line, protocol number(s) + release date(s) (cite MCWIKI/MD).
|
|
- **Headline changes** (release notes): what shipped, 1-paragraph.
|
|
- **Protocol changes**: new / removed / renumbered / restructured packets (from VV enums + MCWIKI), grouped by state (handshake/status/login/config/play). Note data-format changes (NBT, registries, chunk, item components).
|
|
- **Per-patch sub-sections** if the line had multiple protocol numbers (e.g. 1.16→735, 1.16.2→751…), each noting what that bump specifically changed (cite the VV package + commit).
|
|
- **Proxy/forwarding & translation impact**: what a proxy/ViaVersion must do for this version.
|
|
- Citations inline; `<!-- VERIFY -->` for gaps.
|
|
|
|
**Report:** path + which protocol numbers covered + notable changes + VERIFY flags.
|
|
|
|
---
|
|
|
|
## 8. Status log
|
|
|
|
- 2026-06-19: repo created (`Timemachine/minecraft_protocol`), refs cloned, README + this PLAN written. Wave-1: 4/8 docs landed (00/01, 02, 04, 07). Next: re-dispatch the 4 pending (§6), then Phase 2.
|