Skip to content

Old Structure Formatting

Jump to bottom
Ryandw11 edited this page Mar 19, 2023 · 1 revision

This documentation is for an outdated version of CustomStructures. Click here to return to the current documentation.

Creating a new structure.

To create a new structure from in-game all you need to do is run the following command:

/cstructure create {name} {schematic}

See this page for how to create a schematic.

Table of Contents

Getting Started

As of version 1.5 all structure have their own file. When the plugin is first loaded a demo schematic and structure file is added to the plugin folder.
The demo schematic can be found at ~/customstructures/schematics/demo.schem^
The demo structure can be found at ~/customstructures/structures/demo.yml^
^ ~ is assumed to be the plugin folder in the file path.

First take a look at the structures folder and the demo.yml file inside of it. That file shows the complete structure file format including every feature there is. Some of the features included are optional and are not required to be stated in the file.

schematic: 'demo.schem'

Chance:
  Number: 1
  OutOf: 500

StructureLocation:
  Worlds:
    - world
  SpawnY: top
  SpawnYHeightMap: 'WORLD_SURFACE'
  CalculateSpawnFirst: true
  Biome: []
  DistanceFromOthers: 200
  # Set a custom spawn distance for the structures.
  spawn_distance:
    x: 10
    z: 10

StructureProperties:
  PlaceAir: true
  randomRotation: false
  ignorePlants: true
  spawnInWater: true
  spawnInLavaLakes: true
  spawnInVoid: false
  ignoreWater: false

SubSchematics:
  Schematics:
    demo2:
      File: 'demo2.schem'
      PlaceAir: false
      UseRotation: false

AdvancedSubSchematics:
  CategoryOne:
    demo2:
      Weight: 20
      File: 'demo2.schem'
      PlaceAir: false
      UseRotation: false

StructureLimitations:
  WorldHeightRestriction: 10
  whitelistSpawnBlocks:
    - GRASS_BLOCK
    - Dirt
    - Stone
    - air
  blacklistSpawnBlocks: []
  # This could cause issue with lag depending on how large the search area is.
  BlockLevelLimit:
    # Can be flat or flat_error.
    mode: flat
    cornerOne:
      x: -5
      z: -5
    cornerTwo:
      x: 5
      z: 5

  # This could cause issues with lag depending on how many blocks you have
  # to replace.
  replacement_blocks:
    'STONE': 'AIR'

  # Delay the replacement of blocks by x seconds.
  replacement_blocks_delay: 0

Masks:
  enabled: false
  union_type: 'AND'

  BlockTypeMask:
    - WHITE_WOOL

  NegatedBlockMask:
    - WHITE_WOOL

BottomSpaceFill:
  'SNOWY_TAIGA,SNOWY_PLAINS': SNOW_BLOCK
  'DESERT': SANDSTONE
  'default': DIRT


#List of lootTables for this Schematic, name and weight
#Weight determines how often it will be chosen out of all the entries in the list.
LootTables:
  CHEST:
    lootTable: 5
  BARREL:
    lootTable: 5

Important Features

One of the important features is at the top of the file:

schematic: 'demo.schem'

This tells the plugin what schematic to use! Schematics are to be put in the customstructures/schematics folder. As stated above, when the plugin is first loaded a test schematic is put inside of there. To add your own schematics check out this page!

The structure file is split into the following sections:

  • Chance
  • StructureLocation
  • StructureProperties
  • StructureLimitations
  • LootTables
    Each of these sections handle different parts of the structure. Some sections also have sub-sections.
    Below is a guide to all of the options that can be chosen for a structure.

Structure File Guide

Schematic

schematic: 'demo.schem'

This tells the plugin what schematic to use! Schematics are to be put in the customstructures/schematics folder. As stated above, when the plugin is first loaded a test schematic is put inside of there. To add your own schematics check out this page!

Chance

Chance:
  Number: 1
  OutOf: 100

Required: Yes

Number

Number: 1

Required: Yes
Value: A number
Examples:
Number: 1

This is the top number of the spawn rate fraction.

OutOf

OutOf: 500

Required: Yes
Value: A number
Examples:
OutOf: 500

This is the bottom number of the spawn rate fraction.

StructureLocation

StructureLocation:
  Worlds:
    - world
  SpawnY: top
  SpawnYHeightMap: 'WORLD_SURFACE'
  CalculateSpawnFirst: true
  Biome: []
  DistanceFromOthers: 200
  DistanceFromSame: 200
  # Set a custom spawn distance for the structures.
  spawn_distance:
    x: 10
    z: 10

Required: Yes

Worlds

Worlds:
  - world

Required: No
Value: A list containing world names
Default Value: All Worlds

Whitelist structures to spawn in certain worlds.

SpawnY

SpawnY: top

Required: Yes
Value: Several Possible Combinations

This controls the Y level the structure spawns at.
The structure will spawn at its (0, 0, 0) point which is determined by the place where you do /cstruct createscheme.

There are several things that can go here:

top

SpawnY: top
This tells the plugin to spawn the structure to spawn at the top block. The top block is selected based upon SpawnYHeightMap. For example: When SpawnYHeightMap: 'WORLD_SURFACE' it will spawn on the surface (including the ocean). See the section on SpawnYHeightMap for more information.

It will spawn in the ground. So if the surface is a grass block at a y of 30, than the structure will spawn at y = 30 replacing that block.

Number

SpawnY: 10
This tells the plugin to spawn the structure at the Y-Vale of 10.

In 1.17+ you can have a datapack that extends the height limit below 0, therefore, negative numbers are valid if you have such as datapack installed. SpawnY: -10

+[num]

SpawnY: '+[10]'
This tells the plugin to spawn the structure 10 blocks above the ground.

-[num]

SpawnY: '-[10]'
This tells the plugin to spawn the structure 10 blocks below the ground.

[num;num]

SpawnY: '[20;30]'
This tells the plugin to spawn the structure at a Y-Value between 20 and 30.

+[num;num]

SpawnY: '+[3;5]'
This tells the plugin to spawn the structure between 3 to 5 blocks above the ground.

-[num;num]

SpawnY: '-[3;5]' This tells the plugin to spawn the structure between 3 to 5 blocks below the ground.

SpawnYHeightMap

SpawnYHeightMap: 'WORLD_SURFACE'

This tells the plugin how to pick the top block when SpawnY is set to top. You have three options:

  • WORLD_SURFACE --> This is the highest non-air block.
  • OCEAN_FLOOR --> The highest non-air, solid block. (The structure will not spawn on top of water). (Note: You will still need to limit the biome to ocean if you want structures to spawn only on the ocean floor).
  • MOTION_BLOCKING --> The highest block that blocks motion or contains a fluid. (Not often used)

Calculate Spawn First

CalculateSpawnFirst: true

Required: No
Value: A boolean value (true or false)
Default Value: true

This allows you to pick whether the SpawnY for the structure is picked first or last in the structure picking process. Setting this value to false will allows properties such as spawnInWater, spawnInLaveLakes, and whitelistSpawnBlock to be done first.

So if SpawnY is 60, and this value is false, then the structure would not spawn over water since it checks to see if the spawn block is water before moving the structure up to y = 60.

Biome

Biome:
  - DESERT

Required: No
Value: A list containing the biomes the structure can spawn in.
Default Value: All Biomes

Whitelist structures to spawn in certain biomes. Valid biome names can be found here!

Distance From Others

DistanceFromOthers: 200

Required: No
Value: An integer with the distance in blocks.
Default Value: 200

The Distance From Others is the minimum distance between structures. By default, a structure must spawn 200 blocks away from another structure.

Distance From Same

DistanceFromSame: 200

Required: No
Value: An integer with the distance in blocks.
Default Value: 200

The Distance From Same is the minimum distance between structures of the same type. By default, a structure must spawn 200 blocks away from a structure of the same type.

Spawn Distance

  spawn_distance:
    x: 300
    z: 300

Required: No
Value: An x and z distance from the spawn.
Default Value: 0

The spawn distance denotes how close a structure can spawn to the spawn of the world (0,0). So in the example above the distance between the structure x and (0, 0) must be 300. Same thing with the z. Here are some examples:

Can Spawn: (330, 500); (400, 301); (1000, 400)
Can't Spawn: (10, 10); (10, 400); (500, 40); (300, 300)

StructureProperties

StructureProperties:
  PlaceAir: true
  randomRotation: false
  ignorePlants: true
  spawnInWater: true
  spawnInLavaLakes: true
  spawnInVoid: false
  ignoreWater: false

Place Air

PlaceAir: true

Required: no
Value: True or false

If air should be placed around the structure when it spawns.

Random Rotation

randomRotation: false

Required: no
Value: True or false

If the structure should be randomly rotated every time it spawns.

Ignore Plants

ignorePlants: true

Required: no
Value: True or false

If the structure should ignore plants when finding a location to spawn.

Spawn In Water

spawnInWater: true

Required: no
Value: True or false

If the structure can spawn inside of water.

Spawn In Lava Lakes

spawnInLavaLakes: true

Required: no
Value: True or false

If the structure can spawn inside of lava.

Spawn In Void

spawnInVoid: false

Required: no
Value: True or false

The SpawnY value must also be an absolute value. An absolute value is a value that is not based off of the ground level. Here is a list of valid and invalid values when this option is set to true:

Valid Spawn Y Values:

SpawnY: 45
SpawnY: [20;30]

Invalid Spawn Y Values:

SpawnY: top
SpawnY: '+[5]'
SpawnY: +[45;50]

Ignore Water

ignoreWater: false

Required: no
Value: True or false

If set to true then the Bottom Fill Feature will ignore water and replace it with the specified fill block.

SubSchematics

SubSchematics:
  Enabled: false
  Schematics:
    schem0:
      File: 'schem0.schem'
      PlaceAir: false
      UseRotation: false
    schem1:
      File: 'schem1.schem'
      PlaceAir: false
      UseRotation: false

Configures what secondary schematics can be spawned by a structure.

Required: no

Enabled

Enabled: false

Required: no
Value: boolean (true or false)

Choose if you want to enable this feature or not on a structure. (Omitting SubSchematics from the file will achieve the same thing).

Schematics

  Schematics:
    schem0:
      File: 'schem0.schem'
      PlaceAir: false
      UseRotation: false
    schem1:
      File: 'schem1.schem'
      PlaceAir: false
      UseRotation: false

Required: yes

This holds the possible sub-schematics a structure could spawn. The names schem0 and schem1 does not matter.
The File must be a valid schematic file found in the normal schematics folder.
If UseRotation is set to true, then the rotation of the sub schematic will be the same as the sign that spawns it in.
See this page for information for how to include sub-schematics in your structure

Advanced Sub-Schematics

AdvancedSubSchematics:
  CategoryOne:
    demo2:
      Weight: 20
      File: 'demo2.schem'
      PlaceAir: false
      UseRotation: false

Required: no

Advanced Sub-Schematics provides a more advanced way to spawn sub-schematics within a structure. You can use categories to spawn schematics with different probabilities. You can also easily add schematics to a structure without having to change the parent schematic.

Learn more about Advanced Sub-Schematics here!

Structure Limitations

StructureLimitations:
  iterationLimit: 20
  WorldHeightRestriction: 10
  whitelistSpawnBlocks:
    - Grass_block
    - Dirt
    - Stone
    - air
  
  blacklistSpawnBlocks: []

  BlockLevelLimit:
    mode: flat
    cornerOne:
      x: -5
      z: -5
    cornerTwo:
      x: 5
      z: 5

  # This could cause issues with lag depending on how many blocks you have
  # to replace.
  replacement_blocks:
    'STONE': 'AIR'

  # Delay the replacement of blocks by x seconds.
  replacement_blocks_delay: 0

Required: no

Iteration Limit

iterationLimit: 20

Required: no
Value Type: Integer
Default Value: 2

The iteration limit controls how deep sub-schematic recursion spawning can go.
Important Note: An excessive limit could cause lag or intermittent server crashes. Use this configuration option with moderation.

World Height Restriction

WorldHeightRestriction: 10

Required: no
Value Type: Integer
Default Value: 0

Defines how much vertical space is needed for a structure to spawn. A structure will not spawn at the top of a world if it does not have enough space. In the example above, 10 blocks of vertical space is needed for a structure to spawn.

Whitelist Spawn Blocks

whitelistSpawnBlocks:
  - Grass_block
  - Dirt
  - Stone
  - air

Required: no
Value: A valid block name

A list of blocks that the structure can spawn on. If this does not exist in the config than it is assumed the structure can spawn on all blocks.
For a list of valid block names go here!

Blacklist Spawn Blocks

blacklistSpawnBlocks:
    - SNOW_BLOCK
    - DIRT

Required: no
Value: A valid block name

A list of blocks that the structure cannot spawn on. For a list of valid block names go here!

Block Level Limit

  BlockLevelLimit:
    mode: flat
    cornerOne:
      x: -5
      z: -5
    cornerTwo:
      x: 5
      z: 5

Required: No

This is a way to tell the plugin to only spawn a structure if 5 blocks around it are flat.

Mode

mode: flat
This tells the plugin that it needs to check and see if the area specified is flat.
To disable the feature put mode: none

Corner One

Defines a point relative to the center of a structure.

Corner Two

Defines the second point relative to the center of a structure.

The plugin will use both Corner One and Corner Two as a way to know what area to check. With the example above a 10x10 area is check around the structure.

Valid Modes

Flat

BlockLevelLimit:
    # Can be flat or flat_error.
    mode: flat
    cornerOne:
      x: -5
      z: -5
    cornerTwo:
      x: 5
      z: 5

Flat means that the ground below the structure must not be air and the blocks above the structure must be plants or air. There is no margin for error.

Flat Error

BlockLevelLimit:
    mode: flat_error
    error: 0.40
    cornerOne:
      x: -5
      z: -5
    cornerTwo:
      x: 5
      z: 5

Flat error is the exact same as flat except that there is margin of error. error: 0.40 defines a 40% margin of error for the structure to spawn. The way this works is that it counts every block that it checks, if the block is not valid according to the flat conditions, it adds one to the error counter. It then calculates error/totalErrors and compares it to the error: 0.40 value. If error/totalErrors is greater than 0.40 than the plugin will not spawn the structure.

replacement_blocks

replacement_blocks:
    'STONE': 'AIR'
    'SPONGE': 'GRASS_BLOCK'

Required: No

This is a simple list that allows you to replace one block type with another block type. You define what blocks you want to replace with what by using a key-value list. The format is as follows: the material on the left is what you want to replace, and the material on the right is what you are replacing the block with. So it is REPLACEE: REPLACER. So with the example above: 'STONE': 'AIR', Stone blocks are replaced with air blocks.

Note: Replacement occurs after the structure is placed. That means existing blocks can be replaced if place air is set to false.
See the list of materials you can use here

Replacement Blocks Delay

replacement_blocks_delay: 0

Required: No
Value: decimal number (in seconds)
Example Value: 1.25

This allows you to delay the replacement of signs and blocks when a structure is spawned. This is useful if you are using an async worldedit plugin where structures take a second or two to spawn. The delay is in seconds. (Decimal Values are permitted)

Masks

Masks:
  enabled: false
  union_type: 'AND'

  BlockTypeMask:
    - WHITE_WOOL

  NegatedBlockMask:
    - WHITE_WOOL

Required: No

Masks is a feature that allows you to use world edit makes in your structure.
This is considered an advanced feature

enabled: false: If Masks are enabled.
union_type: 'AND': This informs the plugin how it should handle multiple masks. Options: AND, OR. If union type is set to AND than that means that all masks must be true, if union type is OR than only one of the masks needs to be true.

Mask Types:

Block Type Mask

BlockTypeMask:
  - WHITE_WOOL

Required: No

The BlockTypeMask informs the plugin what blocks can be placed. So in the example above only WHITE_WOOL will be placed. You can add more blocks to the list. Here is a list of valid block types

Negated Block Mask

NegatedBlockMask:
    - WHITE_WOOL

Required: No

The NegatedBlockMask functions opposite of the BlockTypeMask. Instead of only placing WHITE_WOOL the plugin will place every block but WHITE_WOOL. This mask essentially functions as a structure void block and works faster than the replacement_blocks function.

Bottom Space Fill

BottomSpaceFill:
  'SNOWY_TAIGA,SNOWY_PLAINS': SNOW_BLOCK
  'DESERT': SANDSTONE
  'default': DIRT

Required: No

If present, all air blocks under a structure will be set to the desired fill block according to the biome that the structure is spawning in. Ignore blocks are not considered ground blocks, so stuff like plants and trees will be replaced. Water is treated like a ground block unless you have the ignoreWater property set to true under StructureProperties.
The default implementation of this feature may be a little slow for large structures. In the future an addon named CSFastFill will be released to fix this issue. You can also have your own implementation of the feature using the Developer API. You can map a single biome to a block:

'DESERT': SANDSTONE

Or multiple biomes to a block by a comma separated list:

'SNOWY_TAIGA,SNOWY_PLAINS': SNOW_BLOCK

If you want to set a default block fill type for any biome not explicitly stated, you can use the 'default' option:

'default': DIRT

In the example above all biomes except SNOWY_TAIGA, SNOWY_PLAINS, and DESERT, have bottom fill blocks of dirt.
The 'default' option can be omitted so that if the block type for the biome is not explicitly stated, then nothing will happen.

Loot Tables

LootTables:
  BARREL:
    lootTable: 5

Required: No

This is a way to describe loot tables for the plugin.
The BARREL is the type of container that the loot table is used for. The value lootTable is the name of the loot table. The name must match a valid loot table. Loot tables are located at customstructures/lootTables.
The 5 is the weight of the loot table, it determines how often the loot table will be rolled.
To add another loot table to the list you just add it below the first one.

LootTables:
  BARREL:
    lootTable: 5
    lootTable2: 3

Loot tables can have more than one container:

LootTables:
  BARREL:
    lootTable: 5
    lootTable2: 3  
  CHEST:
    lootTable: 6

In the example above the lootTable loot table can spawn in chests and barrels. Each container has its own weight system so loot tables that spawn in a barrel will not interfere with the probability of those that spawn in a chest.

Valid types are: CHEST, FURNACE, HOPPER, BREWING_STAND, TRAPPED_CHEST, BARREL

Container Specific Loot Tables

If you want a specific container to have a specific loot table, you can specify it by using the /cstruct setLootTable command. Running that command while looking at a container will put a piece of paper in the first item slot of the container, which tells the plugin what loot table the container should have. This will override any loot tables set by the configuration option above for the container. This feature allows for multiple containers of the same type to have different loot table types.

Advanced Formatting

This is not a section of the structure configuration, instead it is a collection of advanced features that can be found in the config.

Please view this page for more information

Custom Structure WIKI

Clone this wiki locally