Skip to content

PROPS.md

Latest commit

 

History

History
310 lines (224 loc) · 9.31 KB

PROPS.md

File metadata and controls

310 lines (224 loc) · 9.31 KB

Props

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

Props are the object/structure placement system in Hytale's V2 world generation. They place blocks, prefabs, and decorations into the world. There are 11 registered prop types and 4 directionality types.

Common Fields

All prop assets share these base fields from PropAsset.ABSTRACT_CODEC:

Field Type Required Default Description
Skip boolean No false If true, this prop is disabled (returns NoProp)
ExportAs string No "" Name for Export/Import reuse system

Placement Flow

graph LR
    PP[PositionProvider] --> S[Scanner]
    S --> P[Pattern]
    P --> BM[BlockMask]
    BM --> Prop[Prop.place]
Loading
  1. PositionProvider generates candidate XZ positions
  2. Scanner scans vertically to find valid Y positions
  3. Pattern validates whether the block meets placement conditions
  4. BlockMask checks if the target block can be placed/replaced
  5. Prop places blocks into the chunk

Prop Types

Type: Box

Places a rectangular box of blocks.

Field Type Required Default Description
Range Vector3i Yes — 3D size of the box
Material MaterialAsset Yes — Block material to place
Pattern PatternAsset Yes Constant(true) Placement condition
Scanner ScannerAsset Yes Origin Position scanner 
{
  "Type": "Box",
  "Range": { "X": 3, "Y": 5, "Z": 3 },
  "Material": { "Solid": "stone" },
  "Pattern": { "Type": "Floor", "Floor": { "Type": "Constant", "Value": true } },
  "Scanner": { "Type": "Origin" }
}

Type: Column

Places a vertical column of blocks.

Type: Cluster

Places clusters of props with distance-based probability.

Field Type Required Default Description
Range int No 0 Clustering range (must be >= 0)
DistanceCurve CurveAsset Yes Constant(0) Probability curve based on distance
Seed string No "A" Random seed
WeightedProps WeightedPropAsset[] Yes — Weighted prop selection (each must be column-shaped)
Pattern PatternAsset No Constant(true) Placement condition
Scanner ScannerAsset No Origin Position scanner 
{
  "Type": "Cluster",
  "Range": 4,
  "Seed": "flowers",
  "DistanceCurve": {
    "Type": "DistanceExponential",
    "Range": 4.0,
    "ExponentA": 2.0
  },
  "WeightedProps": {
    "red_flower": { "Weight": 2.0, "ColumnProp": { "Type": "Box", "Range": { "X": 1, "Y": 1, "Z": 1 } } },
    "blue_flower": { "Weight": 1.0, "ColumnProp": { "Type": "Box", "Range": { "X": 1, "Y": 1, "Z": 1 } } }
  }
}

Type: Density

Places blocks based on a density function, with material provider support.

Field Type Required Default Description
Range Vector3i Yes — 3D range (all values >= 0)
PlacementMask BlockMaskAsset Yes — Which blocks can be placed
Pattern PatternAsset Yes Constant(true) Placement condition
Scanner ScannerAsset Yes Origin Position scanner
Density DensityAsset Yes Constant(0) Density function for placement
Material MaterialProviderAsset Yes Constant Material selection 
{
  "Type": "Density",
  "Range": { "X": 8, "Y": 8, "Z": 8 },
  "Density": { "Type": "SimplexNoise3D", "Seed": "rock_scatter", "ScaleXZ": 0.1, "ScaleY": 0.1 },
  "Material": { "Type": "Constant", "Material": { "Solid": "stone" } },
  "Pattern": { "Type": "Constant", "Value": true },
  "Scanner": { "Type": "Origin" }
}

Type: Prefab

Places prefab structures from files.

Field Type Required Default Description
WeightedPrefabPaths WeightedPathAsset[] Yes — Weighted prefab file selection
LegacyPath boolean No false Use legacy path resolution
Directionality DirectionalityAsset Yes Static(0) Rotation mode
Scanner ScannerAsset Yes Origin Position scanner
BlockMask BlockMaskAsset No — Block replacement rules
MoldingDirection MoldingDirection No NONE UP, DOWN, or NONE
MoldingPattern PatternAsset No Constant(true) Molding condition
MoldingScanner ScannerAsset No Origin Molding scanner
MoldingChildren boolean No false Apply molding to children
LoadEntities boolean No true Load entities from prefab 
{
  "Type": "Prefab",
  "WeightedPrefabPaths": {
    "oak_tree": { "Weight": 3.0, "Path": "Trees/OakTree.prefab" },
    "birch_tree": { "Weight": 1.0, "Path": "Trees/BirchTree.prefab" }
  },
  "Directionality": { "Type": "Random", "Seed": "tree_rotation" },
  "Scanner": { "Type": "ColumnLinear", "MinY": 60, "MaxY": 120, "ResultCap": 1 }
}

Type: PondFiller

Specialized prop for filling pond/water features.

Type: Queue

Executes multiple props in sequence at each position.

Type: Union

Combines multiple props into a single composite.

Field Type Required Default Description
Props PropAsset[] Yes [] Array of props to execute together 
{
  "Type": "Union",
  "Props": [
    { "Type": "Box", "Range": { "X": 1, "Y": 3, "Z": 1 }, "Material": { "Solid": "log" } },
    { "Type": "Box", "Range": { "X": 3, "Y": 2, "Z": 3 }, "Material": { "Solid": "leaves" } }
  ]
}

Type: Offset

Applies a spatial offset to a child prop.

Type: Weighted

Randomly selects a prop from a weighted list.

Field Type Required Default Description
Entries EntryAsset[] Yes — Weighted entries
Seed string Yes "" Random seed

Each entry contains:

  • Weight (double, default 1.0, must be > 0)
  • Prop (PropAsset, default NoProp)
{
  "Type": "Weighted",
  "Seed": "vegetation",
  "Entries": {
    "tree": { "Weight": 1.0, "Prop": { "Type": "Prefab", "WeightedPrefabPaths": {} } },
    "bush": { "Weight": 3.0, "Prop": { "Type": "Box", "Range": { "X": 2, "Y": 1, "Z": 2 } } },
    "nothing": { "Weight": 5.0, "Prop": { "Type": "Box", "Skip": true } }
  }
}

Type: Imported

References an exported prop by name.

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

Directionality

Directionality controls the rotation of prefab props. There are 4 registered types.

Type: Static

Fixed rotation applied to all prefabs.

Field Type Required Default Description
Rotation int No 0 Rotation in degrees (0, 90, 180, 270)
Pattern PatternAsset No Constant(true) Condition for applying rotation 
{ "Type": "Static", "Rotation": 90 }

Type: Random

Random rotation per placement.

Field Type Required Default Description
Seed string Yes "A" Random seed
Pattern PatternAsset No Constant(true) Condition 
{ "Type": "Random", "Seed": "tree_rotation" }

Type: Pattern

Direction-based placement using pattern matching per cardinal direction.

Field Type Required Default Description
InitialDirection OrthogonalDirection Yes — Starting direction (N/S/E/W)
Seed string Yes "A" Random seed
NorthPattern PatternAsset Yes Constant(true) North-facing condition
SouthPattern PatternAsset Yes Constant(true) South-facing condition
EastPattern PatternAsset Yes Constant(true) East-facing condition
WestPattern PatternAsset Yes Constant(true) West-facing condition

Type: Imported

References an exported directionality by name.

Field Type Required Default Description
Name string Yes — Name of the exported directionality

PropField Structure

At runtime, each prop configuration is wrapped in a PropField:

Field Type Description
assignments Assignments The prop distribution (what to place)
positionProvider PositionProvider Where to attempt placement
runtime int Runtime stage index

See: Assignments, Position Providers

Source files: PropAsset.java, PropField.java, BoxPropAsset.java, ClusterPropAsset.java, DensityPropAsset.java, PrefabPropAsset.java, UnionPropAsset.java, WeightedPropAsset.java, ImportedPropAsset.java, DirectionalityAsset.java, StaticDirectionalityAsset.java, RandomDirectionalityAsset.java, PatternDirectionalityAsset.java