Skip to content

PATTERNS.md

Latest commit

 

History

History
262 lines (181 loc) · 7.71 KB

PATTERNS.md

File metadata and controls

262 lines (181 loc) · 7.71 KB

Patterns

Source: Decompiled from HytaleServer.jar (pre-release 2026.02.05-9ce2783f7)

Patterns are boolean condition functions that determine whether a block position qualifies for prop placement. They check surrounding blocks, surface conditions, and density values. There are 15 registered pattern types.

Common Fields

Field Type Required Default Description
Skip boolean No false If true, pattern is disabled
ExportAs string No "" Name for Export/Import reuse

Surface Patterns

Type: Floor

Checks if the position is on a floor surface (solid below, air above).

Field Type Required Default Description
Floor PatternAsset Yes Constant(true) Condition for the floor block
Origin PatternAsset Yes Constant(true) Condition for the origin block 
{
  "Type": "Floor",
  "Floor": { "Type": "BlockType", "Material": { "Solid": "grass" } },
  "Origin": { "Type": "Constant", "Value": true }
}

Type: Ceiling

Checks if the position is on a ceiling surface (solid above, air below).

Field Type Required Default Description
Ceiling PatternAsset Yes Constant(true) Condition for the ceiling block
Origin PatternAsset Yes Constant(true) Condition for the origin block

Type: Wall

Checks if the position is adjacent to a wall surface.

Field Type Required Default Description
Wall PatternAsset Yes Constant(true) Condition for the wall block
Origin PatternAsset Yes Constant(true) Condition for the origin block
RequireAllDirections boolean No false Require walls in all specified directions
Directions WallDirection[] Yes — Cardinal directions to check (N/S/E/W)

Type: Surface

General surface detection with configurable facings and gap/medium support.

Field Type Required Default Description
Surface PatternAsset Yes — Condition for the surface block
Medium PatternAsset Yes Constant(true) Condition for the medium (air) side
SurfaceRadius double No 0.0 Surface detection radius (>= 0)
MediumRadius double No 0.0 Medium detection radius (>= 0)
SurfaceGap int No 0 Gap between surface check and origin (>= 0)
MediumGap int No 0 Gap between medium check and origin (>= 0)
RequireAllFacings boolean No false Require all specified facings
Facings Facing[] Yes — Face directions to check

Type: Gap

Detects gaps in terrain with configurable anchor and depth.

Field Type Required Default Description
GapPattern PatternAsset Yes Constant(true) Gap block condition
AnchorPattern PatternAsset Yes Constant(true) Anchor block condition
GapSize double Yes — Gap size (>= 0)
AnchorSize double Yes — Anchor size (>= 0)
AnchorRoughness double Yes — Roughness (>= 0)
DepthDown int Yes — Downward depth (>= 0)
DepthUp int Yes — Upward depth (>= 0)
Angles float[] Yes — Detection angles

Block Patterns

Type: BlockType

Matches a specific block material at the position.

Field Type Required Default Description
Material MaterialAsset Yes — Block material to match 
{ "Type": "BlockType", "Material": { "Solid": "stone" } }

Type: BlockSet

Matches any block from a set of materials.

Field Type Required Default Description
BlockSet MaterialSetAsset Yes — Set of materials to match

Spatial Patterns

Type: Cuboid

Checks if position is within a 3D cuboid region.

Field Type Required Default Description
SubPattern PatternAsset Yes Constant(true) Condition within the cuboid
Min Vector3i Yes — Minimum corner
Max Vector3i Yes — Maximum corner 
{
  "Type": "Cuboid",
  "Min": { "X": -2, "Y": 0, "Z": -2 },
  "Max": { "X": 2, "Y": 5, "Z": 2 },
  "SubPattern": { "Type": "Constant", "Value": true }
}

Type: Offset

Applies a spatial offset before checking a child pattern.

Field Type Required Default Description
Pattern PatternAsset Yes Constant(true) Child pattern
Offset Vector3i Yes — Offset to apply 
{
  "Type": "Offset",
  "Offset": { "X": 0, "Y": -1, "Z": 0 },
  "Pattern": { "Type": "BlockType", "Material": { "Solid": "grass" } }
}

Type: FieldFunction

Density-driven pattern — matches when a density value falls within specified ranges.

Field Type Required Default Description
FieldFunction DensityAsset Yes Constant(0) Density function to evaluate
Delimiters DelimiterAsset[] Yes — Min/Max ranges that qualify 
{
  "Type": "FieldFunction",
  "FieldFunction": { "Type": "SimplexNoise2D", "Seed": "placement_noise", "Scale": 0.05 },
  "Delimiters": {
    "high": { "Min": 0.5, "Max": 1.0 }
  }
}

Logic Patterns

Type: And

Logical AND — all child patterns must match.

Field Type Required Default Description
Patterns PatternAsset[] Yes [] Child patterns 
{
  "Type": "And",
  "Patterns": [
    { "Type": "Floor", "Floor": { "Type": "Constant", "Value": true } },
    { "Type": "BlockType", "Material": { "Solid": "grass" } }
  ]
}

Type: Or

Logical OR — any child pattern must match.

Field Type Required Default Description
Patterns PatternAsset[] Yes [] Child patterns

Type: Not

Logical NOT — inverts a child pattern.

Field Type Required Default Description
Pattern PatternAsset Yes Constant(true) Child pattern to negate 
{ "Type": "Not", "Pattern": { "Type": "BlockType", "Material": { "Solid": "water" } } }

Type: Constant

Always returns a fixed boolean value.

Field Type Required Default Description
Value boolean Yes — Constant result 
{ "Type": "Constant", "Value": true }

Reuse

Type: Imported

References an exported pattern by name.

Field Type Required Default Description
Name string Yes — Name of the exported pattern 
{ "Type": "Imported", "Name": "grass_floor" }

Source files: PatternAsset.java, FloorPatternAsset.java, CeilingPatternAsset.java, WallPatternAsset.java, SurfacePatternAsset.java, GapPatternAsset.java, MaterialPatternAsset.java, BlockSetPatternAsset.java, CuboidPatternAsset.java, OffsetPatternAsset.java, DensityPatternAsset.java, AndPatternAsset.java, OrPatternAsset.java, NotPatternAsset.java, ConstantPatternAsset.java, ImportedPatternAsset.java