# RegionIO — working notes

A Minecraft Java Edition server core in Go, targeting **26.1.2 / protocol 775**.
The goal is vanilla fidelity, not a lookalike: where vanilla behaviour is known, match it exactly.

README.md describes what the server does. This file is about how to work on it.

## Commands

```
go build ./... && go vet ./...
make test          # go test ./...
make test-race     # the race-sensitive subset
make verify        # both

go run ./cmd/regionio -seed 12345            # serves on 0.0.0.0:25565
go run ./cmd/regionio -seed 12345 -world ""  # in-memory world, nothing read from or written to disk
go run ./cmd/gendump                         # client-free generator diagnostics
```

## Hard rules

**No third-party dependencies.** `go.mod` has none. NBT, zlib framing, MD5 seeding, noise, the
density-function interpreter — all in-tree. Keep it that way.

**Bump `generatorVersion` whenever the generator's output changes.** It lives in
`internal/world/store.go` and is stamped into every saved chunk; a mismatch makes the chunk
regenerate. Without a bump, the chunks already on disk keep their old terrain and your change looks
like it did nothing in exactly the area you are standing in — `chunkAt` prefers the store over the
generator. `TestGeneratorVersionStampRejectsStaleChunks` covers the mechanism. For quick iteration,
`-world ""` sidesteps persistence entirely. (The seed is guarded separately, by the world metadata
file, and a seed mismatch is a hard error rather than a regeneration.)

**Verify vanilla behaviour against the jar; don't recall it.** See below.

## Vanilla ground truth

None of these are redistributable, so all are gitignored. Obtain `server.jar` from Mojang.

| Source | What it gives you |
|---|---|
| `.refjava/` | Decompiled classes for the parts we port: `Climate`, `SurfaceRules`, `SurfaceSystem`, `Aquifer`, `DensityFunctions`, `NoiseRouterData`, `NoiseBasedChunkGenerator`, `TerrainProvider`, `PalettedContainer`, `LevelChunkSection`, `ClientboundLevelChunkPacketData` |
| `versions/26.1.2/server-26.1.2.jar` | The real (deobfuscated) server. The outer `server.jar` is only a bundler |
| `generated/reports/` | Datagen output: `blocks.json`, `registries.json`, `packets.json`, `biome_parameters/` |

The inner jar also carries the **complete worldgen datapack**, which is the source for everything we
still approximate: 259 `placed_feature`, 222 `configured_feature`, 66 `biome` (with per-stage
`features` and `carvers`), 5 `configured_carver`, 35 `structure`, 1359 structure NBTs — 648 KB for
the feature/biome/carver set.

Three ways in, cheapest first:

```
unzip -p versions/26.1.2/server-26.1.2.jar data/minecraft/worldgen/biome/plains.json
javap -p -c -classpath versions/26.1.2/server-26.1.2.jar net.minecraft.world.level.chunk.Strategy
```

`javap` settles questions the decompiled subset does not cover. It is how the biome palette
threshold was pinned down: `Strategy$2` switches `{0..3}` and everything above falls through to the
global palette, which `.refjava/` alone could not show.

When a constant has to come from vanilla's *runtime* rather than its source or reports, dump it with
a throwaway Java program run against the jar. `tools/VanillaLightDump.java` is the precedent — it
walks the block-state registry and emits opacity, emission and voxel face shapes into
`internal/world/light_properties.bin`. Substring-matching block names is how the light table was
wrong before (`grass_block` matched "grass", `bedrock` matched "bed"); don't reintroduce that shape
of guess anywhere.

## Layout

```
cmd/regionio/     entry point (flags, listener, graceful shutdown)
cmd/gendump/      client-free generator diagnostics — biome spread, surface blocks,
                  subsurface banding, deep-layer composition, bedrock band, cross-section
cmd/genblocks/    generates internal/worldgen/generated_blocks.go from the block report
cmd/genlight/     legacy light-table generator, superseded by tools/VanillaLightDump.java
tools/            Java dumpers run against the jar, plus their Go-side fixtures
internal/protocol/  VarInt, framing, compression, packet IDs
internal/nbt/       NBT codec (modified UTF-8)
internal/registry/  28 embedded synced registries + tags, verbatim from vanilla
internal/world/     chunk model, wire encoder, cache + tickets, Anvil store, lighting,
                    the chunk generator itself (vanilla.go), decoration
internal/worldgen/  the library: noise, density-function interpreter, surface rules,
                    climate/biome finder, embedded datapack under data/
internal/network/   per-connection state machine
internal/server/    shared core: config, sessions, status, profiles, entity loops
```

Note the split: `internal/worldgen` is a *library* over the datapack; the chunk generator that drives
it is `internal/world/vanilla.go`.

## Fidelity status

Bit-exact and parity-tested — treat as settled, change only with a vanilla reference in hand:
`random.go` (Xoroshiro128++, `upgradeSeedTo128bit`, MD5 seeding), `improved_noise.go`,
`perlin_noise.go`, `normal_noise.go`, `blended.go`, `spline.go`, `density.go`, the 4×8×4 cell grid
with trilinear interpolation, the climate/biome finder, and the chunk wire encoder
(`TestGoldenAgainstVanilla` compares bytes against a real vanilla chunk).

Known gaps, roughly in order of how visible they are:

- **Aquifers are absent.** `vanilla.go` floods every air block below sea level with water, so every
  cave below y=63 is solid water and there are no lava lakes. Vanilla resolves fluid per position
  through `Aquifer.computeSubstance`; the datapack ships all four router keys (`barrier`,
  `fluid_level_floodedness`, `fluid_level_spread`, `lava`) and they are not parsed.
- **`above_preliminary_surface` is wrong**, so there is no subsurface banding: every land column is
  one grass block directly on stone, no dirt, no sandstone under sand. Vanilla is
  `blockY >= preliminarySurfaceLevel + surfaceDepth - 8`; we compare against the actual top block,
  which gates the whole biome surface subtree to a single block per column. `gendump` prints this.
- **Several surface-rule conditions are stubs**: `hole` is hardcoded false (vanilla is
  `surfaceDepth <= 0`), `steep` is never assigned, `water` uses sea level instead of the column's
  real water height, and 6 of the 7 `noise_threshold` noises are unsupported so calcite, ice, packed
  ice, powder snow, swamp water and gravel patches never appear. `bandlands` is a 4-colour cycle
  rather than the 192-band array.
- **No carvers and no ore veins.** Caves come only from the density router; `configured_carver` and
  the `vein_*` router keys are unimplemented.
- **Decoration is hand-written heuristics**, not the vanilla feature system: oak trees only and
  without a biome check (so oaks grow in deserts), ores that cannot generate below y≈0 because they
  only replace stone and never deepslate, and no grass, flowers, lakes or springs.

## Testing worldgen

`make verify` is the gate, but most generator defects are invisible to it — they show up as terrain
that looks wrong. `cmd/gendump` exists for that: biome distribution, top surface blocks, subsurface
banding, deep-layer composition, the bedrock band, and an ASCII cross-section, with no client
involved. Add an assertion to it whenever you fix a class of defect; the bedrock-band check is the
model — it prints per-layer counts and fails loudly on any air or water in the floor.

`internal/world/vanilla_parity_test.go` compares surface heights against a capture from the official
server and skips when the capture is absent. Note it reads a hardcoded `/tmp` path, so on Windows it
never runs. A capture is produced by running the vanilla server headless at a known seed and reading
its region files back with our own `regionfile.go` + `nbt`.