Editor Block Variants - bh679/dungeon-train-mc GitHub Wiki

Block variants

A block variant turns one block inside a template into a random pool. Instead of saving "this position is always glass," you can say "this position rolls glass, stained glass, or iron bars" — every carriage that spawns from the template gets a different roll, but the same world always shows the same roll at the same spot.

Use this for windows, decor, accents — anywhere you want the train to feel hand-built across many cars without authoring more templates.

The Z key

Block variants are authored with one key: Z.

Hold Z + right-click a block — appends the block in your hand to that position's pool. Hold an empty hand to add an empty space entry (see below).
Tap Z while looking at a marked block — opens the variant menu against the block's face.

Both work inside any editor plot.

The variant menu

Tapping Z opens a panel anchored flat against the block's face. The header shows the block's position. Below, each entry in the pool is listed with its block icon, name, and weight.

Toolbar buttons:

Button	What it does
Add	Append the block in your hand to the pool. Empty hand adds an empty-space entry.
Copy	Drop a variant clipboard item into your hotbar — see Lock groups.
Lock	Mark this block as part of a lock group. Click cycles through lock numbers.
Remove	Toggle remove-mode — each entry shows a red `×` you can click to delete it.
Clear	Drop the whole pool. The block in the world stays as-is.
X	Close the menu.

Click an entry's name to preview that variant in place. Handy for picking which option looks right against the rest of the template.

Shift-click an entry's name to replace it with the block in your hand (since v0.930.0, PR #1486). The row keeps its weight, rotation lock, half setting and difficulty band, and orientation carries over where the two blocks share a property — a north-facing stone stair swapped for a stage stair still faces north. An empty hand turns the row into an empty-space entry; a filled bucket turns it into that fluid's source. Spawn eggs and armor stands are refused, as are mob rows — remove those and add instead. Undo (Ctrl+Z) reverts it like any other menu edit, and a locked cell takes its whole group along.

Holding a variant clipboard instead turns the row into a reference to the clipboard's lock group (since v0.931.0, PR #1488), under the same rules as Add with a clipboard: the source cell must be locked, a cell can't reference its own group or create a loop, and it can hold only one reference per group. The row keeps its weight. Shift-clicking an existing reference row with a different clipboard points it at the new group.

Empty space (the "air" entry)

Add an entry with an empty hand and the pool gets an empty space entry — it rolls as air at spawn. A pool of glass + glass + empty space picks glass two times out of three and leaves a gap the third time, perfect for windows that are sometimes open or roofs that occasionally show sky.

The action bar confirms with (empty-space) and the entry shows as nothing in the list.

In the plot the empty entry stands as a translucent ghost cube (the dungeontrain:variant_placeholder block, since v0.903.0 / PR #1443) — it reads as "nothing here" at a glance and you can place blocks against it with a plain right-click. Before v0.903.0 the placeholder was a vanilla command block, which opened its screen on right-click (you had to hold shift to build against it); templates saved with command blocks still load and are rewritten to the ghost cube the next time you save them.

Mob entries (since v0.174.0)

Hold a vanilla spawn egg instead of a block and the pool gets a mob entry — when it rolls at carriage spawn, the cell becomes air and the mob spawns at that position. Same Z + right-click flow, same Add button in the menu — both accept spawn eggs.

The action bar confirms with light-purple + minecraft:zombie (mob) and the menu row shows the spawn-egg icon next to the mob's name (e.g. zombie (mob)).

A pool of [nothing, zombie, skeleton] rolls one of three each time — sometimes nothing, sometimes a zombie, sometimes a skeleton. Mix mob and block entries freely; weights apply across the whole pool.

Mobs spawn through the same 48-block player-distance gate that template- baked enemies use — they don't pop into existence ahead of you. They also get PersistenceRequired so vanilla despawn doesn't eat them.

A renamed or NBT-tagged spawn egg (via anvil or /give) carries its EntityTag into the variant — so you can pre-equip a zombie with custom armor, give it a name, etc., and the variant remembers.

Slimes and magma cubes roll a random size (1–4) each time they spawn from a spawn-egg variant (since v0.282.0) — the variant path skips vanilla's spawn-time size roll, so otherwise they'd all appear at the smallest size. A spawn egg tagged with an explicit Size (anvil / EntityTag) keeps that size instead.

A few caveats for v1:

Mob variants on track / pillar / tunnel sidecars parse but don't spawn yet — the cell becomes air at world-gen with a single WARN per cell. A follow-up will add the queueing infrastructure for non-carriage mobs.
The rotation field is parsed and stored but not yet applied — mobs always spawn at 0° yaw.
The editor's in-place template restamp deliberately doesn't spawn mob variants, so re-entering a plot doesn't dump random mobs around you.

Lock groups

Lock groups make several blocks share the same random pick — so every corner of a window rolls the same colour of stained glass, every plank in a row matches, etc.

Open the variant menu on the first block. Click Lock — the lock cycles to a new number (e.g. 1).
Click Copy — a variant clipboard item appears in your hotbar. It looks like the ghost-cube placeholder block, with its lock number in the top-left corner and its blocks as tiny icons along the bottom — 8 per row, filling upward, up to 32 (since v0.1223.0, PR #1927).
Place the clipboard at another position in the plot. That position joins the same lock group — same pool, same number.
At spawn, every block in the group rolls the same variant, every time.

Locked blocks show their lock number on every face while you're in the plot, so you can tell at a glance which blocks belong together.

Doors, beds and tall plants (since v0.953.0)

A variant cell can hold two-block things — doors, beds, tall grass, tall flowers, pitcher plants. When one is rolled, both halves spawn (a bed's head follows its rolled facing, even when rotation is random).

Aim at either half and tap Z — the same menu opens, placed on the half you looked at.

If the cell also holds ordinary one-block entries, a Span button appears on the toolbar. It decides how an ordinary block fills the two spaces, and opens a small popup above the menu:

Section	Options	Shown when
How many	`1` · `2` · `R` (random per carriage)	always
Position	`1` (the cell) · `2` (the other half's space) · `R`	How many is 1 or R
Repeat	Same block in both · Random re-roll from the cell's one-block entries	How many is 2 or R

Until you pick, the cell follows its first entry: a door added first means 2 / Same, a one-block entry added first means 1 / Position 1. The space that isn't used is left as air, so no half-doors are left floating.

The particle outline

Every block with a variant pool shows a soft white sparkle outline in the world, visible up to 24 blocks away. Lets you see at a glance which positions have variants and which don't.

Breaking a marked block in creative removes its variant pool automatically — no orphan sparkles.

Where block variants work

Block variants work in every editor plot — carriages, parts (floor / walls / roof / doors), contents, tracks, pillars, tunnels. Same Z key, same menu, same behaviour.

Recipes

Goal	Steps
A window that's sometimes open	Place glass. Hold `Z` + right-click with an empty hand → adds the empty-space entry. Spawn → 50/50 glass vs gap per carriage.
A roof that rolls a few wood types	Place oak planks. Hold `Z` + right-click with spruce planks in hand. Tap `Z`, then Add with birch planks held. Now each carriage rolls oak, spruce, or birch.
All four corners of a window match	Tap `Z` on corner A → Lock → Copy. Place the clipboard at corner B, then C, then D. All four corners now share one pick.
A pattern of decorative blocks across many cars	Build the pattern with block variants per position. Use lock groups for any blocks that need to match each other.
A pad that sometimes spawns an enemy	Pick the pad cell. Hold a zombie spawn egg + Z + right-click. Hold a husk spawn egg + Z + right-click. Now each carriage rolls between the empty pad, a zombie, and a husk at that position — they spawn when you walk close.
A doorway that's sometimes a door, sometimes a bookshelf stack	Tap `Z` on the doorway's bottom block, Add with an oak door held, then with a bookshelf held. Open Span → How many 2, Repeat Same. Each carriage rolls a whole door or a two-high bookshelf.