Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ Each task becomes one GitHub issue under milestone M0, in this order.

**Exit criteria:** the vectors pass, the round-trip suite is green, CI is green, and `convert` turns a real `.schem` into a `.nbt` that mcbuilder's importer reads back.

**Where that stands (2026-11-08):** the vectors pass, the round-trip suite is green, and CI is green on GitHub. No `.schem` saved by a real tool exists yet (see Open items), and no automated test feeds `convert`'s output to mcbuilder's importer.
**Where that stands (2026-11-16):** the vectors pass, the round-trip suite is green, CI is green on GitHub, `fixtures/real/` now holds real-tool `.schem` files (`worldedit/fantasyhouse2.schem`, three `shulkr/*.schem`, and three `flat-v3/smp_lobby_*.schem`), and `packages/mcbuilder/test/importer.test.ts` runs `scripts/convert.ts` on them and feeds the converted `.nbt` files into mcbuilder's importer, rebuilding identical blocks.

## Golden vectors

Expand Down Expand Up @@ -273,7 +273,7 @@ The code differs from the v1 spec in the ways below. Luki decided all fourteen o

- [x] Create the repository `lzif/voxwright` so the scaffold can start (created **private**; it is **public** now, checked 2026-11-11)
- [x] Choose `AGPL-3.0-only` or `AGPL-3.0-or-later` for the SPDX headers, before M0 (`AGPL-3.0-only`)
- [ ] Before M2, send fixtures saved by real tools: two or three `.schem` from WorldEdit (`.nbt`, `.litematic` and `.mcstructure` of one build are in `fixtures/real/`, saved by bloxelizer.com, not Litematica or Bedrock). M2 was built without them, so this is late
- [x] Before M2, send fixtures saved by real tools: two or three `.schem` from WorldEdit (`.nbt`, `.litematic` and `.mcstructure` of `Rafeals_house` in `fixtures/real/rafeals-house/`, saved by bloxelizer.com, plus `worldedit/fantasyhouse2.schem`, three `shulkr/*.schem`, three `flat-v3/smp_lobby_*.schem`, and `legacy/storageroom-medieval.schematic` added 2026-11-16)
- [ ] Check the domain and trademark (npm is settled, decided 2026-11-14: only the command line is published, unscoped as `voxmc`; the `@voxwright` npm scope holds only the old `@voxwright/mcbuild` and is not used otherwise)
- [ ] Pick the open source Bedrock to Java block-mapping table and confirm its license is AGPL-compatible (needed by M2; the code uses hand-written rules meanwhile)
- [x] Decide each entry under "Differences from the v1 spec" (all 14 decided 2026-11-07; see that section)
Expand Down
16 changes: 9 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -320,9 +320,11 @@ Built:
the renderer (see [vectors/README.md](vectors/README.md)).
- `core`: NBT reader and writer (big and little endian, gzip), block strings,
rotation, sectioned volume, and codecs for `.nbt`, `.schem`, `.litematic` and
`.mcstructure`, all tested. A real build saved in three of those formats
decodes to the same blocks in each, once the Java default properties that
Bedrock leaves out (such as `waterlogged=false`) are set aside.
`.mcstructure`, all tested (including real-tool `.schem` builds from WorldEdit
and Shulkr, plus flat-v2-layout files tagged `Version: 3`). A real build
saved in three of those formats decodes to the same blocks in each, once the
Java default properties that Bedrock leaves out (such as `waterlogged=false`)
are set aside.
- `convert` script between all four formats.
- The Agent Skill in `skills/voxwright/`: `SKILL.md`, the references, and the skill CLI (`build`, `inspect`,
`preview` / `view`) as a committed zero-dependency bundle, with the web app opening a build from a
Expand All @@ -341,10 +343,10 @@ Not done yet:
trapdoors, beds, pillars, fences, panes, walls, torches, lanterns, leaves and blocks with
`facing`), not every block in the game. The summary lists each dropped property.
- Block-entity data (chest contents, sign text) and entities cannot be written from a recipe.
- `.schem` files saved by a real tool, and a run on a real phone (the touch editor
has only been driven by emulated touch so far; `docs/phone-test-checklist.md`
lists what to try). Luki checked an edited export in Litematica and smooth
navigation on a real GPU by hand on 2026-11-11; no GPU numbers were recorded.
- A run on a real phone (the touch editor has only been driven by emulated touch so
far; `docs/phone-test-checklist.md` lists what to try). Luki checked an edited
export in Litematica and smooth navigation on a real GPU by hand on 2026-11-11;
no GPU numbers were recorded.
- The 0.1.0 release: the 0.1.0 version bump and tag (`voxmc` is on npm at 0.0.3).
- Deferred, not in 0.1.0: the parts catalog (the spec names it, nothing defines it, so it needs a
definition first) and the fast and trusted preview tiers.
Expand Down
22 changes: 20 additions & 2 deletions fixtures/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,5 +14,23 @@ Schematic files shared by all tests.
`packages/core/test/litematic.test.ts` and `mcstructure.test.ts` check the
other two against the `.nbt`.

Still needed: files saved by real tools (two or three `.schem` from
WorldEdit). Put them in a directory per tool and add tests that read them.
- `real/worldedit/` holds `fantasyhouse2.schem`, a Sponge v3 schematic saved by
WorldEdit 7.4.6 (`enginehub:fabric`, DataVersion 5023; 22,953 blocks, 342
block states, 93 block entities, 41 entities, non-zero `Offset`).

- `real/shulkr/` holds three Sponge v3 builds exported by Shulkr (DataVersion
5023): `castelo-medieval.schem` (4,895 blocks, 6 block entities),
`raifox-medivial-house.schem` (1,595 blocks, 138 block entities) and
`simple-survival-mansion.schem` (6,218 blocks, 77 block entities).

- `real/flat-v3/` holds three real-world `.schem` files (`smp_lobby_big.schem`,
`smp_lobby_center_dense.schem`, `smp_lobby_medieval.schem`, DataVersion 3465)
that declare `Version: 3` while writing Sponge v2's flat layout (top-level
`Palette` and `BlockData` without `Schematic`/`Blocks`). `readSchem` accepts
this layout with a warning.

- `real/legacy/` holds `storageroom-medieval.schematic` (pre-1.13 MCEdit
`Materials: "Alpha"` format), used to verify legacy `.schematic` rejection.

`packages/core/test/real-fixtures.test.ts`, `convert.test.ts` and
`packages/mcbuilder/test/importer.test.ts` read and convert these fixtures.
Binary file added fixtures/real/flat-v3/smp_lobby_big.schem
Binary file not shown.
Binary file not shown.
Binary file added fixtures/real/flat-v3/smp_lobby_medieval.schem
Binary file not shown.
Binary file not shown.
Binary file added fixtures/real/shulkr/castelo-medieval.schem
Binary file not shown.
Binary file added fixtures/real/shulkr/raifox-medivial-house.schem
Binary file not shown.
Binary file not shown.
Binary file added fixtures/real/worldedit/fantasyhouse2.schem
Binary file not shown.
25 changes: 20 additions & 5 deletions packages/core/src/codecs/schem.ts
Original file line number Diff line number Diff line change
Expand Up @@ -228,9 +228,18 @@ export async function readSchem(
if (version !== 2 && version !== 3) {
throw new CodecError(`unsupported Sponge schematic version ${version} (expected 2 or 3)`);
}
if ((version === 3) !== isV3) {
// Some real-world exporters write Sponge v2's flat layout (top-level `Palette` and `BlockData`,
// no nested `Schematic`/`Blocks`) while stamping `Version: 3`. Accept that layout with a warning.
const flatV2WithV3Tag =
version === 3 &&
!isV3 &&
child(schem, "Blocks") === undefined &&
child(schem, "Palette")?.type === "compound" &&
child(schem, "BlockData")?.type === "byteArray";
if ((version === 3) !== isV3 && !flatV2WithV3Tag) {
throw new CodecError(`Sponge schematic version ${version} has the wrong layout`);
}
const layoutVersion: SchemVersion = flatV2WithV3Tag ? 2 : version;

const width = dimension(schem, "Width");
const height = dimension(schem, "Height");
Expand All @@ -240,7 +249,7 @@ export async function readSchem(
let paletteTag: NbtTag | undefined;
let dataTag: NbtTag | undefined;
let blockEntities: NbtTag | undefined;
if (version === 3) {
if (layoutVersion === 3) {
const blocks = asCompound(child(schem, "Blocks"), "Blocks");
paletteTag = child(blocks, "Palette");
dataTag = child(blocks, "Data");
Expand Down Expand Up @@ -301,17 +310,23 @@ export async function readSchem(
}

const lost = new Tally();
readBlockEntities(volume, compoundList(blockEntities), version, lost);
readEntities(volume, compoundList(child(schem, "Entities")), version, lost);
readBlockEntities(volume, compoundList(blockEntities), layoutVersion, lost);
readEntities(volume, compoundList(child(schem, "Entities")), layoutVersion, lost);

const warnings = [...lost.lines("their position holds no block, or is missing or malformed")];
warnings.push(...dropped.lines());
if (flatV2WithV3Tag) {
warnings.push("Version is 3, but layout is Sponge v2 (read using v2 layout)");
}
const metadata = child(schem, "Metadata");
if (metadata?.type === "compound" && metadata.value.size > 0) {
warnings.push(`Metadata not carried over (${[...metadata.value.keys()].join(", ")})`);
}
// v3 keeps biomes in a "Biomes" compound; v2 in "BiomeData" with a "BiomePalette".
if (child(schem, version === 3 ? "Biomes" : "BiomeData") !== undefined) {
if (
child(schem, layoutVersion === 3 ? "Biomes" : "BiomeData") !== undefined ||
(flatV2WithV3Tag && child(schem, "Biomes") !== undefined)
) {
warnings.push("biomes not carried over (a volume holds no biomes)");
}

Expand Down
49 changes: 43 additions & 6 deletions packages/core/test/convert.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,41 @@ describe("scripts/convert.ts", () => {
expect(final.volume.size).toBe(762);
});

it("turns a real WorldEdit .schem into a .nbt with identical blocks and entities", async () => {
const src = join(root, "fixtures/real/worldedit/fantasyhouse2.schem");
const out = join(dir, "fantasyhouse2.nbt");
const log = run(src, out);
expect(log).toContain("22953 blocks, 342 palette entries, DataVersion 5023");
const original = await readSchem(new Uint8Array(readFileSync(src)));
const converted = await readStructureNbt(new Uint8Array(readFileSync(out)));
expect(converted.volume.size).toBe(original.volume.size);
expect(converted.volume.blockEntityCount).toBe(93);
expect(converted.volume.entities).toHaveLength(41);
expect(converted.meta.dataVersion).toBe(5023);
let mismatches = 0;
original.volume.eachCell((x, y, z, idx) => {
if (converted.volume.get(x, y, z) !== original.volume.palette[idx]) mismatches++;
});
expect(mismatches).toBe(0);
});

it("converts a flat-v3 .schem into .nbt and prints the layout warning on stderr", async () => {
const src = join(root, "fixtures/real/flat-v3/smp_lobby_big.schem");
const out = join(dir, "smp_lobby_big.nbt");
const res = spawnSync(process.execPath, [script, src, out], { encoding: "utf8" });
expect(res.status).toBe(0);
expect(res.stdout).toContain("18295 blocks, 41 palette entries, DataVersion 3465");
expect(res.stderr).toContain("Version is 3, but layout is Sponge v2");
const original = await readSchem(new Uint8Array(readFileSync(src)));
const converted = await readStructureNbt(new Uint8Array(readFileSync(out)));
expect(converted.volume.size).toBe(original.volume.size);
let mismatches = 0;
original.volume.eachCell((x, y, z, idx) => {
if (converted.volume.get(x, y, z) !== original.volume.palette[idx]) mismatches++;
});
expect(mismatches).toBe(0);
});

it("keeps the .schem Offset from .schem to .schem", async () => {
const v = new Volume();
v.set(0, 0, 0, "minecraft:stone");
Expand Down Expand Up @@ -135,12 +170,14 @@ describe("scripts/convert.ts", () => {
it("tells the user to re-save a legacy .schematic as .schem", () => {
const legacy = join(dir, "old.schematic");
writeFileSync(legacy, new Uint8Array(0));
const bad = spawnSync(process.execPath, [script, legacy, join(dir, "x.nbt")], {
encoding: "utf8",
});
expect(bad.status).toBe(1);
expect(bad.stderr).toContain("legacy .schematic");
expect(bad.stderr).toContain("re-save it as .schem");
for (const src of [legacy, join(root, "fixtures/real/legacy/storageroom-medieval.schematic")]) {
const bad = spawnSync(process.execPath, [script, src, join(dir, "x.nbt")], {
encoding: "utf8",
});
expect(bad.status).toBe(1);
expect(bad.stderr).toContain("legacy .schematic");
expect(bad.stderr).toContain("re-save it as .schem");
}
});

it("fails clearly on bad input", () => {
Expand Down
Loading
Loading