feat(shared)!: resolve save paths per dimension

Serkyo commented

2026-10-02 18:08:04 +00:00

Owner

What does this PR do?

I gave dimensions a name and moved region files under a per-dimension directory.

shared::registry gains DimensionId, a newtype over ContentId so a block or item ID cannot stand in for a dimension, with DimensionId::nyelenor() returning syn:nyelenor. A private ContentId::syn constructor builds first-party IDs, and RegistryBuilder::with_air now uses it too.
shared::paths::region_dir takes a &DimensionId and resolves to saves/<world>/dim/<namespace>/<name>/region/. The ID splits into two path components because : is not a legal filename character on Windows.
shared::paths also resolves entities_dir beside a dimension's regions and the world-scope playerdata_dir, modstate_dir and worldstate_dir. Nothing writes to them yet.
The server and the inspect_save example pass DimensionId::nyelenor() to region_dir, and the server logs the dimension with the save location.
WORLD_FORMAT_VERSION goes from 4 to 5, so a world saved with the old flat region/ layout is refused at load.
docs/save_format.md describes the new layout and the version 5 bump.

Why is this change necessary?

Every region file sat directly under the world's region/ directory, so the save had no place for a second dimension's chunks. Keying the path by dimension now means adding one later is a new directory, with no change to the layout every existing world already uses.

Scope of Changes

server, shared, workspace

Testing

Automated:

cargo check -p shared -p server passed.
cargo test -p shared -p server passed, including the new tests in crates/shared/src/tests/paths.rs for the dimension and world-scope directories, nyelenor_matches_its_parsed_id, and rejects_a_version_4_record.
cargo clippy --all-targets --all-features -- -D warnings passed.
cargo fmt --all -- --check passed.

Manual:

I started the server and the client on a fresh world. The save came out as saves/default/level.dat beside dim/syn/nyelenor/region/, which held the eight region files around the origin (r.0.0.0 through r.-1.-1.-1). No region/ directory was written at the world root, and the level.dat header carries SYNW with format version 5.

Additional Context

This breaks the save format. WORLD_FORMAT_VERSION moves to 5 and a version 4 level.dat is refused with UnsupportedVersion. The version 4 payload is identical to version 5; only the region layout moved, so the header is the only thing marking the difference. There is no migrator, so existing worlds have to be recreated.

The worldgen registry in the server stays keyed by version alone. Every generator belongs to Nyelenor, so a dimension in the key would carry no information until a second dimension generates terrain.

None.

Checklist

I have branched from dev (or a feature branch off dev) and my PR targets dev.
I have kept my changes focused to a single concept.
I have added or updated documentation (/// doc comments for Rust) where necessary.
I have tested my changes and described any relevant automated or manual testing above.

### What does this PR do? I gave dimensions a name and moved region files under a per-dimension directory. - `shared::registry` gains `DimensionId`, a newtype over `ContentId` so a block or item ID cannot stand in for a dimension, with `DimensionId::nyelenor()` returning `syn:nyelenor`. A private `ContentId::syn` constructor builds first-party IDs, and `RegistryBuilder::with_air` now uses it too. - `shared::paths::region_dir` takes a `&DimensionId` and resolves to `saves/<world>/dim/<namespace>/<name>/region/`. The ID splits into two path components because `:` is not a legal filename character on Windows. - `shared::paths` also resolves `entities_dir` beside a dimension's regions and the world-scope `playerdata_dir`, `modstate_dir` and `worldstate_dir`. Nothing writes to them yet. - The server and the `inspect_save` example pass `DimensionId::nyelenor()` to `region_dir`, and the server logs the dimension with the save location. - `WORLD_FORMAT_VERSION` goes from 4 to 5, so a world saved with the old flat `region/` layout is refused at load. - `docs/save_format.md` describes the new layout and the version 5 bump. ### Why is this change necessary? Every region file sat directly under the world's `region/` directory, so the save had no place for a second dimension's chunks. Keying the path by dimension now means adding one later is a new directory, with no change to the layout every existing world already uses. ### Scope of Changes server, shared, workspace ### Testing Automated: - `cargo check -p shared -p server` passed. - `cargo test -p shared -p server` passed, including the new tests in `crates/shared/src/tests/paths.rs` for the dimension and world-scope directories, `nyelenor_matches_its_parsed_id`, and `rejects_a_version_4_record`. - `cargo clippy --all-targets --all-features -- -D warnings` passed. - `cargo fmt --all -- --check` passed. Manual: I started the server and the client on a fresh world. The save came out as `saves/default/level.dat` beside `dim/syn/nyelenor/region/`, which held the eight region files around the origin (`r.0.0.0` through `r.-1.-1.-1`). No `region/` directory was written at the world root, and the `level.dat` header carries `SYNW` with format version 5. ### Additional Context This breaks the save format. `WORLD_FORMAT_VERSION` moves to 5 and a version 4 `level.dat` is refused with `UnsupportedVersion`. The version 4 payload is identical to version 5; only the region layout moved, so the header is the only thing marking the difference. There is no migrator, so existing worlds have to be recreated. The worldgen registry in the server stays keyed by version alone. Every generator belongs to Nyelenor, so a dimension in the key would carry no information until a second dimension generates terrain. ### Related Issues None. ### Checklist - [x] I have branched from `dev` (or a feature branch off `dev`) and my PR targets `dev`. - [x] I have kept my changes focused to a single concept. - [x] I have added or updated documentation (`///` doc comments for Rust) where necessary. - [x] I have tested my changes and described any relevant automated or manual testing above.

Serkyo added the

Compat/Breaking

Kind/Feature

labels

2026-10-02 18:08:04 +00:00

Serkyo added 5 commits

2026-10-02 18:08:05 +00:00

feat(shared): identify dimensions by content id ed89c6f387

feat(shared)!: resolve region files under a dimension directory a4497ffc88

feat(shared): resolve the per-world player, entity, mod and world state directories d632ba0022

feat(server): store Nyelenor's regions under its dimension 7dc2737b03

docs(workspace): describe the per-dimension save layout