秦淮系列文档

English

简体中文

English

简体中文

Appearance

Structure Files (.nbt / .schem / marker blocks / terrain blending) ​

Previous: Ruin Template (full template.yml fields)　·　Next: Selection & Saving (pos1 / pos2 / save / stage)

The structure section of the Ruin Template decides "which structure to use and how to place it." This chapter explains every detail related to the structure body: file formats, import conversion, mask terrain blending, marker blocks, foundation fill, rotation, and frame-spread anti-lag.

1. .nbt vs .schem: Which Does QR Use? ​

FormatWho produces itCan QR use it directly
.nbt (native Bukkit structure)Vanilla structure blocks / /qr save / /qr import✅ Used directly, structure.file points to it
.schem (WorldEdit / FAWE / various build sites)WorldEdit //copy //schem save, BetterStructures, etc.❌ Must first be converted to .nbt with /qr import

Conclusion: QR's runtime format is always .nbt. Got a .schem? Convert it first.

Tip

💡 Why native .nbt: QR calls Bukkit's StructureManager directly, with no dependency on WorldEdit / FAWE. Structures can be placed even on servers without those plugins installed.

2. /qr import: Convert .schem to .nbt ​

Drop the .schem file into the plugins/QinhRuins/schematics/ directory, then in-game:

text
/qr import <filename.schem> <ruin id>

QR will:

  1. Temporarily lay out the .schem's blocks at your standing position (frame-spread placement, ~40000 blocks/tick, no server lag);
  2. Reverse-scan marker blocks and sign markers to generate blueprint.yml;
  3. Re-capture this region into structure.nbt using the native API, writing it into templates/<ruin id>/;
  4. Restore the temporarily laid-out blocks (the original terrain was auto-backed-up before import), returning the site to its original state;
  5. Write a minimal template.yml (only id / display / structure.file; you fill in the rest, see Ruin Template).

Key points:

  • Filename Tab-completion: <filename> lists the available .schem files from the schematics/ directory.
  • Import temporarily modifies the world: find an open area to import; it auto-restores afterward; don't import on top of important builds.
  • Volume cap: a single import is at most ~8 million blocks; over that it's rejected.
  • Block-entity fidelity: import preserves sign text, spawner entity types, and other BlockEntity data as much as possible.
  • Permission: qinhruins.admin.

🖼️ [Image placeholder] A screenshot of the /qr import process: frame-spread laying out the schem in an open area, scanning markers, then capturing · suggested assets/import-flow.png

Offline Conversion (on the server owner's computer) ​

If you'd rather not lay out blocks on the server, you can also convert .schem to .nbt offline: use the schem2struct.py script on the server owner's computer (no FAWE needed); once converted, just drop structure.nbt into the ruin folder. Ideal for batch-processing landscape packs like BetterStructures.

3. Rotation ​

structure.rotation controls the structure's orientation when placed:

yaml
structure:
  rotation: none                 # none / random / fixed:90
ValueMeaning
none (default)Fixed orientation, placed as-is.
randomRandomly choose one of four directions (0° / 90° / 180° / 270°) each generation.
fixed:90 / fixed:180 / fixed:270Fixed rotation by that angle.

Caution

⚠️ Two restrictions:

  • Don't use random on structures with marker blocks or sign markers — after rotation the markers' relative coordinates shift, and spawn points / cores will drift off. Only markerless pure-landscape structures are suitable for random orientation.
  • Enabling the target mask target-mask forces NONE orientation (block-by-block placement doesn't support rotation).

4. Mask Paste: Blend into Terrain Without Bulldozing ​

Default placement is "full overwrite" — every cell the structure occupies flattens whatever block the world originally had there. Masks let the structure only place blocks at qualifying positions, so it meshes with terrain instead of forcibly bulldozing.

Three masks, written in the structure section:

yaml
structure:
  file: structure.nbt
  target-mask: [REPLACEABLE]       # Target mask: only place where the world has these blocks
  source-skip: [AIR]               # Source blacklist: don't place these types from the structure
  source-mask: [STONE, DEEPSLATE]  # Source whitelist: only place these types from the structure

4.1 target-mask Target Mask (most common) ​

Only place where the world hits these blocks — the structure blends into terrain without destroying existing blocks.

SyntaxMeaning
[REPLACEABLE] or [*]Only place at "replaceable blocks": air + water + non-solid vegetation + snow + leaves + vines. The most common "blend into terrain" recipe.
[AIR]Only place at air (including cave air / void air).
[STONE, DIRT]Only place at the listed specific materials.
!material (exclude syntax)"Place everywhere except this." E.g. [REPLACEABLE, "!BEDROCK"] = place at replaceable spots, but never overwrite bedrock.

The "replaceable" determination: air / water / all non-solid blocks (except lava) / *_LEAVES / SNOW / VINE.

4.2 source-skip Source Block Blacklist ​

Simply don't place these types from the structure (blacklist).

  • Typical use: [AIR] = don't place air boxes, so the structure's air cells won't clear the world's existing blocks (for a "semi-transparent" effect, or to filter out placeholder air exported by build sites).
  • Supports the !material exclude syntax.

4.3 source-mask Source Block Whitelist ​

Only place these types from the structure, skip everything else (whitelist), complementing the blacklist.

  • Typical use: [STONE, DEEPSLATE] = paste only the stone skeleton into the world, place no decorations / furniture.
  • Supports the !material exclude syntax (e.g. ["!OAK_LEAVES"] = place everything except leaves).

4.4 The Cost of Masks ​

Caution

⚠️ After enabling any mask (target / source):

  • NONE orientation is forced (rotation not supported);
  • Block-by-block placement is used, making very large structures slightly slower than native bulk placement (but still completed in one pass, not frame-spread);
  • Multi-part blocks (doors / beds and other Bisected blocks) get special handling to ensure both halves are placed.

5. Marker Blocks: Barrier / Bedrock ​

Marker blocks let you use two special blocks as "marks" while building the structure; on placement QR automatically swaps them for the desired effect. Controlled by the global switch config.generation.marker-blocks (on by default).

Place in the structureBecomes on placementUse
Barrier BARRIERCleared to airCarve out hollows / doorways / hollow rooms.
Bedrock BEDROCKKeeps the original terrain, no overwrite (lets the world's blocks "show through" the structure)Create half-buried ruins / let a mountainside pass through the structure.

Example: to "bury" the tower base into a hillside — place bedrock at the positions to be eaten by terrain, and on placement those cells keep the mountain; to make the tower door a real opening — place barriers at the doorway, and on placement they're cleared to air.

yaml
# config.yml
generation:
  marker-blocks: true   # On by default: auto-handle barrier/bedrock markers

Caution

⚠️ Want to use "real barriers / real bedrock" in a ruin (e.g. you genuinely want an unbreakable boundary) → turn off config.generation.marker-blocks; then barriers / bedrock are placed as-is.

Marker-block handling is a frame-spread background task (~4096 blocks/tick), no server lag.

6. Batch Block Swap After Pasting: replace-blocks ​

After placement completes, batch-swap blocks of a given type for another (frame-spread, no server lag).

yaml
structure:
  replace-blocks:
    STONE: AIR                   # stone → air = hollow out the interior
    OAK_PLANKS: DARK_OAK_PLANKS  # swap material = themed skin variant
    COBBLESTONE: "mossy_cobblestone"  # value supports full block-state strings
  • The key is the source material name; the value is the target block (can be a material name, or a full block state like "oak_log[axis=y]").
  • Typical use: one structure, multiple themed variants — the same structure.nbt with different replace-blocks to reskin (oak version / dark-oak version / mossy-stone version).
  • Unmatched types are auto-skipped without errors.

7. Foundation Fill: foundation ​

Makes the ruin's bottom grow a foundation downward and taper its edges into terrain, avoiding floating or cliffs. The fields are in the top-level foundation section of template.yml (not inside the structure section):

yaml
foundation:
  enabled: true
  max-depth: 16                  # Max blocks to fill downward
  ignore-water: true
  blend-radius: 4                # Outward edge taper of N blocks
  materials:
    default: STONE
    "DESERT,BADLANDS": SANDSTONE
FieldDefaultDescription
enabledfalseMaster switch.
max-depth16Max blocks per column to fill downward (1–256); stops on hitting solid ground.
ignore-watertrueTreat water as fillable too; foundation passes through water.
blend-radius0Outward edge taper of N blocks: within N blocks beyond the structure's footprint, each block farther out the foundation drops one block, forming a sloped skirt blending into terrain (0 = fill only directly below, may cliff).
materials.defaultnoneFallback foundation material.
materials."biome,biome"—Swap material by biome; a key can be comma-separated to share across multiple biomes (e.g. "DESERT,BADLANDS": SANDSTONE).

How it works:

  • For each column within the structure's footprint, fill downward from the bottom face until it hits solid ground or fills max-depth.
  • "Fillable" cells = air / leaves / logs / grass and other non-solid vegetation / (with ignore-water on) water. On hitting solid ground it stops, never carving through an existing foundation.
  • blend-radius lowers the edges block by block, slanting them into the surrounding terrain.
  • Biome materials are matched in real time per the biome each column sits in, so a ruin spanning biomes can naturally switch materials at its edges.
  • The whole process is a frame-spread background task (~16 columns/tick), no server lag.

Tip

💡 Pairing with masks: target-mask: [REPLACEABLE] (structure blends into terrain) + foundation (fills foundation underneath) is the golden combo for a "half-buried natural ruin" — the structure embeds into terrain, with a solid foundation below so it doesn't float.

8. Frame-Spread Placement: Anti-Lag for Very Large Structures ​

yaml
# config.yml
generation:
  spread-place-threshold: 30000  # Structure block count over this AND NONE orientation → frame-spread placement
  • When a structure's block count exceeds spread-place-threshold (default 30000) and orientation is NONE, QR automatically switches to frame-spread placement: ~8192 blocks/tick laid out in the background without freezing the main thread.
  • Small structures still use native one-pass placement (faster).
  • Rotated structures (non-NONE) use native bulk placement, not frame-spread.

Caution

⚠️ To make a very large structure use frame-spread, don't give it rotation (keep rotation: none), otherwise the frame-spread path isn't triggered.

9. /qr markers: Reverse-Scan Markers ​

text
/qr markers <anchor id>

For an already-generated anchor, re-scan the sign markers and marker blocks within its range, and report the number of spawn points / reward chests / cores found.

  • Use: check exactly which markers are buried in a ruin, and confirm whether markers are correctly recognized (for debugging blueprints).
  • <anchor id> has Tab-completion (lists live anchors in the current world).
  • Find anchor IDs: /qr tp <anchor id> also lists them, or enable director.notify-admins to get coordinates DM'd on generation.

The full sign-marker syntax (the four-line [mob] / [chest] / [core] / [command] format) is in Blueprint & Objectives and Selection & Saving.

10. Common Recipes Quick Reference ​

Desired effectHow to configure
Place the structure as-is hard (landmark / floating tower)Write no mask at all (default full overwrite)
Blend into terrain without bulldozing (natural ruin)target-mask: [REPLACEABLE]
Blend into terrain but never destroy bedrocktarget-mask: [REPLACEABLE, "!BEDROCK"]
Half-buried / mountainside show-throughPlace bedrock in the structure as a "show-through" marker (marker-blocks on by default) + foundation to fill foundation
Hollow rooms / doorwaysPlace barriers in the structure as a "clear" marker
Paste only the stone skeletonsource-mask: [STONE, DEEPSLATE, COBBLESTONE]
Don't clear the world (semi-transparent overlay)source-skip: [AIR]
One structure, multiple themed skinsSame structure.nbt + different replace-blocks
Very large ruin without lagrotation: none + default frame-spread (auto over 30000 blocks)

Next Step ​