Skip to content

Structure Sub Schematics

Jump to bottom
Ryandw11 edited this page Mar 20, 2023 · 3 revisions

SubSchematics allows you to add variety to your structures by creating a unique structure every time it spawns. SubSchematics works by replacing any [schem] or [advschem] signs with a another schematic. It is possible for a schematic spawned this way to contain another sign that would be replaced, thus allowing for recursive structures. Recursion allow for the generation of unique structures like dungeons or villages.

There are two types of SubSchematics: Advanced SubSchematics and Simple SubSchematics. The main difference between the two of them is that Advanced SubSchematics allow for more customization in generating random schematics. It is recommended that all new structures Advanced SubSchematics instead of the simple version. Even though there are two different systems they have the same layout for defining structures.

Advanced Sub Schematics

The AdvancedSubSchematics property is the new system for handling SubSchematics. It is recommended that all new structures use this instead of simple SubSchematics.

AdvancedSubSchematics:
  CategoryOne:
    demo2:
      Weight: 20
      File: 'demo2.schem'
      PlaceAir: false
      UseRotation: false
    demo3:
      Weight: 40
      File: 'demo3.schem'
      PlaceAir: false
      UseRotation: false
  CategoryTwo:
    demo4:
      Weight: 20
      File: 'demo4.schem'

The way AdvancedSubSchematics works is that all subschematics are placed into categories. In the example above there are two categories: CateogryOne and CategoryTwo. Each category then has the definitions for the different schematics. The general format is as follows:

AdvancedSubSchematics:
  CategoryOne:
    {{schematics}}
  CategoryTwo:
    {{schematics}}

You define where a schematic is placed within the main structure schematic by placing a sign with the following written on it:

[advschem]
{category}

An example image showing the format above on a sign.
When the structure is spawned, any [advschem] signs will be placed using a randomly picked structure for the designated category. You can place any [advschem] or `[schem] sign in a subschematic. (The same goes for any Structure Sign).

Quick Reference:
Required: False
Default Behavior: Feature Disabled

Simple SubSchematics

Simple SubSchematics are the outdated way of creating subschematics. It still exists mainly for compatibility reasons.

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

The schematic definitions for simple SubSchematics are placed directly under the section. The ordering of the schematic definitions matters as that is how you will define what schematics are placed. Similar to AdvancedSubSchematics, you define where to place a schematic by placing a sign. Simple SubSchematics allow you to place a single schematic from the list or a random one from a subsection of the list.

[schem]
##

The ## references the schematic to spawn from the definition list. The list is zero indexed, meaning that the first schematic, demo2, is defined as schematic 0. demo3 is schematic 1, and so on.

[schem]
[x;y]

You can use a range to define a subsection of the list to spawn. An example would be: [0;2], which means that a random schematic from 0 to 2 (inclusive) will be picked to spawn. All schematics have an equal probability of spawning, you will need to use AdvancedSubSchematics for finely tuned probability control.
Note: Ensure the following condition holds true for the range: x < y.
Image showing an example sign of the two possible sign configurations.

Quick Reference:
Required: False
Default Behavior: Feature Disabled

General Schematic Definition

The general layout for defining a schematic in the SubSchematic configuration sections is as follows:

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

First is the name of the schematic you are adding. In the example above the name of the schematic is demo2. Currently the name of the schematic is not important, as it is never used. The only important thing is that it is unique and the names are never duplicated.

Weight

Weight is only used by schematics placed in the AdvancedSubSchematics section. The weights are what determines the probability of a schematic spawning for a category. This is the same probability system used by the LootTables. The most important thing to know is that a schematic is more likely to spawn the higher you set the weight (when compared to other schematics). See the page on weighted probability for a detailed explanation on the math behind this.

Weight: 20

Consider The Following: Due to the weighted probability system, a schematic is always guaranteed to spawn (unlike with structures). If you don't want a subschematic to spawn sometimes, consider making an empty schematic and add it to the list to spawn.

Quick Reference:
Required: If in an AdvancedSubSchematic category.
Value: Positive Integer
Default Value: None (required)

File

The file determines what schematic is actually spawned. Just like the schematic for the main structure, the file comes from CustomStructures\schematics. The logic for a structure's main schematic also applies to subschematics. For example, a subschematic will spawn based upon its origin point, which is where you were standing when you created the schematic using /cstruct createScheme or some other command.

File: 'demo2.schem'

Quick Reference:
Required: True
Value: String
Default Value: None (required)

Place Air

The PlaceAir property works the same as the one for the main structure. When set to true, it means that any air within the schematic fill will be placed into the world.

PlaceAir: false

Quick Reference:
Required: False
Value: Boolean
Default Value: False

Use Rotation

The UseRotation property allows for the rotation of the subschematic to match the rotation of the sign when set to true.

UseRotation: false

Quick Reference:
Required: False
Value: Boolean
Default Value: False

Vertical Repositioning

The VerticalRepositioning property allows you to reposition where a subschematic spawns on the y-axis. Using this property means that the location of the sign will only determine the x and z position.

VerticalRepositioning:
  Range: '[-10;20]'
  SpawnY: 'top'
  SpawnYHeightMap: 'WORLD_SURFACE'
  NoPointSolution: ''
Complete Example 
    demo3:
      Weight: 40
      File: 'demo3.schem'
      PlaceAir: false
      UseRotation: false
      VerticalRepositioning:
        Range: '[-10;20]'
        SpawnY: 'top'
        SpawnYHeightMap: 'WORLD_SURFACE'
        NoPointSolution: ''

Quick Reference:
Required: False
Default Behavior: Feature Disabled

Range

The Range sub-property allows you to configure a local range of y values where your structure is allowed to spawn relative to the y-position of the sign.

Range: '[-10;20]'

In the example above, your subschematic is allowed to spawn 10 blocks below to sign up to 20 blocks above the sign. All range values must follow the format of [x;y] where x < y.

Quick Reference:
Required: False
Value: Integer Range
Default Value: No Range

SpawnY

The SpawnY property functions the same as the one for the primary structure. SpawnY determines how the y-position of the subschematic will be selected. See the main SpawnY documentation for more information.

SpawnY: 'top'

If the selected y-level is not in the range provided by the Range property, then the NoPointSolution property is used as a fallback to determine what will happen to the subschematic.

Quick Reference:
Required: True
Value: SpawnY String
Default Value: None (Required)

SpawnY Height Map

This property functions the same as the one for the primary structure. It determines which HeightMap is used to determine the surface block. See the main SpawnYHeightMap documentation for more information..

SpawnYHeightMap: 'WORLD_SURFACE'

Quick Reference:
Required: False
Value: HeightMap Enumeration
Default Value: 'WORLD_SURFACE'

No Point Solution

The NoPointSolution property is used as a fallback to determine what happens when the selected y-value is outside of the range defined by the Range property. There are 3 possible options:

  • 'CURRENT': The subschematic spawns at the same y-level as the sign.
  • 'PREVENT_SPAWN': The subschematic will not be spawned in.
  • {Stylized Integer}: An integer y-value ('10') or a range of y-values ('[20;50]') for a value to be randomly selected.
NoPointSolution: 'CURRENT'

Quick Reference:
Required: False
Value: Varies
Default Value: 'CURRENT'

Properties Inherited From Parent Structure

The following properties are inherited from the parent structure:

That means that the properties above will also be applied to any subschematics. For example, any blocks set to be replaced in the ReplaceBlocks property will also be replaced in the subschematic.

Recursive Structures

Recursive Structures are structures that have subschematics that spawn other subschematics. Examples of recursive structures are Dungeons and Villages.

When creating a recursive structure it is important for you to have a base case subschematic. A base case subschematic is a subschematic that does not spawn any subschematics. Without a base case your structure will never stop spawning, and will cause the server to crash. To prevent something like that from happening on accident, CustomStructures has a fail safe mechanism called the IterationLimit. The IterationLimit defines how deep the recursion subschematic spawning is allowed go. By default the IterationLimit is set to the small value of 2 to prevent accidental recursion from occuring. You will need to manually increase that limit in order to take advantage of recursive structures.

Note: It is recommended to not exceed 25-30 consecutive recursive spawns. Ensure that your base case schematic is not extremely rare.

Custom Structure WIKI

Clone this wiki locally