Skip to content

SCANNERS.md

Latest commit

 

History

History
180 lines (132 loc) · 5.48 KB

SCANNERS.md

File metadata and controls

180 lines (132 loc) · 5.48 KB

Scanners

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

Scanners determine the vertical (Y-axis) positions at which props attempt placement. After a position provider generates candidate XZ coordinates, the scanner examines each column to find valid Y positions. There are 5 registered scanner types.

Common Fields

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

Scanner.Context

At runtime, scanners receive a context with:

Field Type Description
position Vector3i Base position for scan
pattern Pattern Pattern matcher for validity testing
materialSpace VoxelSpace<Material> Material data for block queries
workerId WorkerIndexer.Id Worker thread identifier

Scanner Types

Type: Origin

Scans only the exact origin position. Returns the position if the pattern matches, empty otherwise.

No additional fields.

Space size: (0,0,0) to (1,0,1)

{ "Type": "Origin" }

Type: ColumnLinear

Scans vertically in a single column, iterating linearly through a Y range.

Field Type Required Default Description
MinY int Yes — Minimum Y offset for scan range
MaxY int Yes — Maximum Y offset for scan range
ResultCap int No 1 Maximum results to return (>= 0)
TopDownOrder boolean No true Scan top-to-bottom (true) or bottom-to-top (false)
RelativeToPosition boolean No false Y values relative to scan position
BaseHeightName string No "" Framework DecimalConstants entry for base height

Behavior:

  • If RelativeToPosition is true: scans from position.y + MinY to position.y + MaxY
  • If RelativeToPosition is false: scans from baseHeight + MinY to baseHeight + MaxY
  • TopDownOrder controls iteration direction
  • Stops when ResultCap positions are found
{
  "Type": "ColumnLinear",
  "MinY": 60,
  "MaxY": 120,
  "ResultCap": 1,
  "TopDownOrder": true
}

Type: ColumnRandom

Scans vertically using random Y sampling within a range.

Field Type Required Default Description
MinY int Yes — Minimum Y offset for scan range
MaxY int Yes — Maximum Y offset for scan range
ResultCap int No 1 Maximum results to return (>= 0)
Seed string No "A" Random seed
Strategy string No "DART_THROW" Selection strategy
RelativeToPosition boolean No false Y values relative to scan position
BaseHeightName string No "" Framework DecimalConstants entry for base height

Strategies:

Strategy Description
DART_THROW Randomly probes Y positions; attempts range * 1 tries, returns unique matches up to ResultCap
PICK_VALID Finds all valid positions first, then randomly selects ResultCap from them 
{
  "Type": "ColumnRandom",
  "MinY": 10,
  "MaxY": 200,
  "ResultCap": 3,
  "Seed": "cave_props",
  "Strategy": "PICK_VALID"
}

Type: Area

Scans a 2D area (XZ plane) using a child scanner at each column position.

Field Type Required Default Description
ResultCap int No 1 Maximum total results across entire area (>= 0)
ScanShape string No "CIRCLE" Scan pattern shape
ScanRange int No 0 Radius/half-width of scan area (>= 0)
ChildScanner ScannerAsset No Origin Scanner to apply at each column

Scan Shapes:

Shape Description
CIRCLE Circular area — positions where distance(x, z) <= range
SQUARE Square area — all positions in [-range, range] for both X and Z

Behavior:

  • Pre-computes all valid scan positions and sorts by distance from origin
  • Applies child scanner at each column position in distance order
  • Combines results up to ResultCap

Space size: (-range, 0, -range) to (1+range, 0, 1+range)

{
  "Type": "Area",
  "ScanShape": "CIRCLE",
  "ScanRange": 3,
  "ResultCap": 5,
  "ChildScanner": {
    "Type": "ColumnLinear",
    "MinY": 60,
    "MaxY": 120,
    "ResultCap": 1
  }
}

Type: Imported

References an exported scanner by name.

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

Summary

Scanner Y-Axis Mode Area Support Randomness
Origin Single point No None
ColumnLinear Linear scan No None
ColumnRandom Random sample No Yes (2 strategies)
Area Delegated Yes (2D area) Optional (via child)
Imported Delegated Varies Varies

Source files: ScannerAsset.java, Scanner.java, OriginScannerAsset.java, ColumnLinearScannerAsset.java, ColumnRandomScannerAsset.java, AreaScannerAsset.java, ImportedScannerAsset.java