hud_react_util¶

Source: base/tealdef/gui/hud/hud_react_util.d.tl

Notes

Helpers for configuring HUD icons in the 3D view: building and editing Builtin.Type.VisibilityThresholds, the default line-viewer snap factors and per-carrier vehicle icon offsets.

HudReactUtil¶

record global base/tealdef/gui/hud/hud_react_util.d.tl:3

global record HudReactUtil

Load: local hud_react_util = ug_require "/gui/hud/hud_react_util.tl"

Notes

Helpers to build and modify the Builtin.Type.VisibilityThresholds that control when and in which draw order HUD icons appear.

Details

All set*/reset* functions return a new thresholds object and leave the input unchanged. The result goes into visibilityThresholds of a builtin.HudIconManagerConfig (see the layer windows in gui/layers).

Fields

Name	Type	Description
`DefaultVisDistDetailThreshold`	`number`	Default camera distance (350) beyond which a station shows its main icon instead of the per-terminal sub icons; used as `detailsThreshold` of the station entry. used 1× in the base game
`DefaultCameraHeightThreshold`	`number`	Default `cameraHeightThreshold` of the visibility thresholds (150).
`DefaultCameraHeightLowerCutoff`	`number`	Default `cameraHeightLowerCutoff` of the visibility thresholds (30).
`DefaultHudLodFarRangeThreshold`	`number`	Default `hudLodFarRangeThreshold` of the visibility thresholds (3000).

Functions

makeVisibilityThresholdsUserdata(visibilityThresholds : Builtin.Type.VisibilityThresholds) : Builtin.Type.VisibilityThresholds base/tealdef/gui/hud/hud_react_util.d.tl:10

Call as hud_react_util.makeVisibilityThresholdsUserdata

convert the config formulated with lua tables into the actual userdata type

Returns Builtin.Type.VisibilityThresholds

makeDefaultVisibilityThresholds() : Builtin.Type.VisibilityThresholds base/tealdef/gui/hud/hud_react_util.d.tl:12

Call as hud_react_util.makeDefaultVisibilityThresholds

Notes

Builds the base game's default HUD icon visibility thresholds for lines, towns, industries, warehouses, depots, stations, signals, vehicles, dead ends, town buildings and sub-constructions.

Returns Builtin.Type.VisibilityThresholds: A new Builtin.Type.VisibilityThresholds userdata.

Details

The per-type scale values come from HudGuiConfig.renderDistances. Order matters: the first matching component entry applies to an entity with several components. By default, town districts are hidden (detailsThreshold = -1 for SelectionDetails.Type.Town); see resetSubEntityThresholds.

Example

local visibilityThresholds = hud_react_util.makeDefaultVisibilityThresholds()
-- show town districts as well (from gui/layers/layer_cargo_flow.tl)
visibilityThresholds = hud_react_util.resetSubEntityThresholds(visibilityThresholds, api.gui.SelectionDetails.Type.Town)

Used in the base game: 25 times in 24 files

base/content/gui/gui/layers/layer_terrain.tl:181

visibilityThresholds = hud_react_util.makeDefaultVisibilityThresholds(),

base/content/gui/gui/layers/layer_passenger_flow.tl:207

visibilityThresholds = hud_react_util.makeDefaultVisibilityThresholds(),

base/content/gui/gui/layers/layer_infrastructure.tl:191

visibilityThresholds = hud_react_util.makeDefaultVisibilityThresholds(),

base/content/gui/gui/layers/layer_civilization.tl:109

visibilityThresholds = hud_react_util.makeDefaultVisibilityThresholds(),

base/content/gui/gui/layers/layer_cargo_flow.tl:321

local visibilityThresholds = hud_react_util.makeDefaultVisibilityThresholds()

base/content/gui/gui/layers/layer_noise.tl:203

visibilityThresholds = hud_react_util.makeDefaultVisibilityThresholds(),

… and 18 more files.

findSubEntityThresholds(thresholds : Builtin.Type.VisibilityThresholds, detailsType : api.gui.SelectionDetails.Type, makeIfNotExisting? : boolean) : Builtin.Type.VisibilityThresholds.OfSubEntity base/tealdef/gui/hud/hud_react_util.d.tl:14

Call as hud_react_util.findSubEntityThresholds

Notes

Looks up the sub-entity thresholds for a selection-details type.

Parameter	Type	Description
`thresholds`	`Builtin.Type.VisibilityThresholds`	Thresholds to search.
`detailsType`	`api.gui.SelectionDetails.Type`	Sub-entity type, e.g. `api.gui.SelectionDetails.Type.Station`.
`makeIfNotExisting?`	`boolean`	If true, return a new empty `OfSubEntity` instead of `nil` when there is no entry.

Returns Builtin.Type.VisibilityThresholds.OfSubEntity: The entry from thresholds.forSubEntities (not a copy), a new empty object, or nil.

Used in the base game: 1 time in 1 file

base/content/gui/gui/entity_window/station_group/station_group.tl:932

local stationDetailsThresholds = hud_react_util.findSubEntityThresholds(visibilityThresholds, api.gui.SelectionDetails.Type.Station, true)

setSubEntityThresholds(thresholds : Builtin.Type.VisibilityThresholds, detailsType : api.gui.SelectionDetails.Type, value : Builtin.Type.VisibilityThresholds.OfSubEntity) : Builtin.Type.VisibilityThresholds base/tealdef/gui/hud/hud_react_util.d.tl:19

Call as hud_react_util.setSubEntityThresholds

Notes

Returns a copy of the thresholds with the sub-entity entry for detailsType replaced by value.

Parameter	Type	Description
`thresholds`	`Builtin.Type.VisibilityThresholds`	Thresholds to copy.
`detailsType`	`api.gui.SelectionDetails.Type`	Sub-entity type whose entry is replaced.
`value`	`Builtin.Type.VisibilityThresholds.OfSubEntity`	New sub-entity thresholds.

Returns Builtin.Type.VisibilityThresholds: New thresholds object.

Details

If forSubEntities is not set, a list with only the new entry is created. If the list exists but has no entry for detailsType, no entry is added.

Used in the base game: 1 time in 1 file

base/content/gui/gui/entity_window/station_group/station_group.tl:934

visibilityThresholds = hud_react_util.setSubEntityThresholds(visibilityThresholds, api.gui.SelectionDetails.Type.Station, stationDetailsThresholds)

resetSubEntityThresholds(thresholds : Builtin.Type.VisibilityThresholds, detailsType : api.gui.SelectionDetails.Type) : Builtin.Type.VisibilityThresholds base/tealdef/gui/hud/hud_react_util.d.tl:24

Call as hud_react_util.resetSubEntityThresholds

Notes

Returns a copy of the thresholds where the sub-entity entry for detailsType has no detailsThreshold, so main icon and sub-entity icons are shown together.

Parameter	Type	Description
`thresholds`	`Builtin.Type.VisibilityThresholds`	Thresholds to copy.
`detailsType`	`api.gui.SelectionDetails.Type`	Sub-entity type, e.g. `api.gui.SelectionDetails.Type.Town` to show town districts.

Returns Builtin.Type.VisibilityThresholds: New thresholds object; layer and physicsImpact of the entry are kept.

Used in the base game: 4 times in 4 files

base/content/gui/gui/layers/layer_cargo_flow.tl:322

visibilityThresholds = hud_react_util.resetSubEntityThresholds(

base/content/gui/gui/line_vehicle_mgmt/line_util.tl:1133

visibilityThresholds = hud_react_util.resetSubEntityThresholds(

base/content/gui/gui/construction/construction_react_util.tl:1268

visibilityThresholds = hud_react_util.resetSubEntityThresholds(

base/content/gui/gui/entity_window/town/town.tl:1041

visibilityThresholds = hud_react_util.resetSubEntityThresholds(

setMainIconsLayer(thresholds : Builtin.Type.VisibilityThresholds, componentType : Engine.ComponentType, layer : integer) : Builtin.Type.VisibilityThresholds base/tealdef/gui/hud/hud_react_util.d.tl:29

Call as hud_react_util.setMainIconsLayer

Notes

Returns a copy of the thresholds with a new draw-order layer for the main icons of one component type.

Parameter	Type	Description
`thresholds`	`Builtin.Type.VisibilityThresholds`	Thresholds to copy.
`componentType`	`Engine.ComponentType`	Component type of the entry to change.
`layer`	`integer`	New draw order (lower is drawn in front).

Returns Builtin.Type.VisibilityThresholds: New thresholds object; other values of the entry are kept.

Used in the base game: 1 time in 1 file

base/content/gui/gui/line_vehicle_mgmt/line_util.tl:1144

visibilityThresholds = hud_react_util.setMainIconsLayer(

setSubAndMainIconsLayer(thresholds : Builtin.Type.VisibilityThresholds, componentType : Engine.ComponentType, detailsType : api.gui.SelectionDetails.Type, layer : integer) : Builtin.Type.VisibilityThresholds base/tealdef/gui/hud/hud_react_util.d.tl:34

Call as hud_react_util.setSubAndMainIconsLayer

Notes

Like setMainIconsLayer, but also sets the same layer on the sub-entity entry for detailsType.

Parameter	Type	Description
`thresholds`	`Builtin.Type.VisibilityThresholds`	Thresholds to copy.
`componentType`	`Engine.ComponentType`	Component type of the main-icon entry to change.
`detailsType`	`api.gui.SelectionDetails.Type`	Sub-entity type of the sub-icon entry to change.
`layer`	`integer`	New draw order (lower is drawn in front).

Returns Builtin.Type.VisibilityThresholds: New thresholds object.

Used in the base game: 1 time in 1 file

base/content/gui/gui/line_vehicle_mgmt/line_util.tl:1138

visibilityThresholds = hud_react_util.setSubAndMainIconsLayer(

findComponentEntityThresholds(thresholds : Builtin.Type.VisibilityThresholds, type : api.engine.ComponentType, makeIfNotExisting? : boolean) : Builtin.Type.VisibilityThresholds.OfComponent base/tealdef/gui/hud/hud_react_util.d.tl:41

Call as hud_react_util.findComponentEntityThresholds

Notes

Looks up the thresholds entry for a component type.

Parameter	Type	Description
`thresholds`	`Builtin.Type.VisibilityThresholds`	Thresholds to search.
`type`	`api.engine.ComponentType`	Component type, e.g. `api.type.ComponentType.STATION_GROUP`.
`makeIfNotExisting?`	`boolean`	If true, return a new empty `OfComponent` instead of `nil` when there is no entry.

Returns Builtin.Type.VisibilityThresholds.OfComponent: The entry from thresholds.forComponents (not a copy), a new empty object, or nil.

setComponentEntityThresholds(thresholds : Builtin.Type.VisibilityThresholds, type : api.engine.ComponentType, value : Builtin.Type.VisibilityThresholds.OfComponent) : Builtin.Type.VisibilityThresholds base/tealdef/gui/hud/hud_react_util.d.tl:46

Call as hud_react_util.setComponentEntityThresholds

Notes

Returns a copy of the thresholds with the entry for type replaced by value.

Parameter	Type	Description
`thresholds`	`Builtin.Type.VisibilityThresholds`	Thresholds to copy.
`type`	`api.engine.ComponentType`	Component type whose entry is replaced.
`value`	`Builtin.Type.VisibilityThresholds.OfComponent`	New component thresholds.

Returns Builtin.Type.VisibilityThresholds: New thresholds object.

Details

Only replaces an existing entry; if there is no entry for the component type, none is added.

makeDefaultLineViewerSnapFactors() : LineViewerSnapFactors base/tealdef/gui/hud/hud_react_util.d.tl:56

Call as hud_react_util.makeDefaultLineViewerSnapFactors

Notes

Returns the default line viewer snap factors (view = 0.05, world = 10.0).

Returns LineViewerSnapFactors

Used in the base game: 6 times in 6 files

base/content/gui/gui/line_vehicle_mgmt/line_util.tl:1153

local snapFactor = hud_react_util.makeDefaultLineViewerSnapFactors()

base/content/gui/gui/statistics/statistics.tl:287

local snapFactorRef = react.useRefLazy(function() : HudReactUtil.LineViewerSnapFactors return hud_react_util.makeDefaultLineViewerSnapFactors() end)

base/content/gui/gui/entity_window/station_group/station_group.tl:928

local snapFactorRef = react.useRefLazy(function() : HudReactUtil.LineViewerSnapFactors return hud_react_util.makeDefaultLineViewerSnapFactors() end)

base/content/gui/gui/entity_window/vehicle/vehicle.tl:565

local snapFactorRef = react.useRefLazy(function() : HudReactUtil.LineViewerSnapFactors return hud_react_util.makeDefaultLineViewerSnapFactors() end)

base/content/gui/gui/entity_window/town/town.tl:1056

local snapFactorRef = react.useRefLazy(function() : HudReactUtil.LineViewerSnapFactors return hud_react_util.makeDefaultLineViewerSnapFactors() end)

base/content/gui/gui/entity_window/line/line.tl:173

local snapFactorRef = react.useRefLazy(function() : HudReactUtil.LineViewerSnapFactors return hud_react_util.makeDefaultLineViewerSnapFactors() end)

makeVehicleIconOffsets(vehicleIconOffsets : {string : {number}}) : {Carrier : Vec3f} base/tealdef/gui/hud/hud_react_util.d.tl:58

Call as hud_react_util.makeVehicleIconOffsets

Notes

Converts HudGuiConfig.vehicleIconOffsets (carrier name to {x, y, z}) into a table keyed by Carrier enum value with Vec3f values.

Parameter	Type	Description
`vehicleIconOffsets`	`{string : {number}}`	Offsets keyed by carrier name; names that are not a `Carrier` enum value are skipped.

Returns {Carrier : Vec3f}: Offsets keyed by api.type.enum.Carrier value, ready for the vehicleIconOffsets of the HUD icon manager config.

Used in the base game: 13 times in 12 files

base/content/gui/gui/line_vehicle_mgmt/line_util.tl:1152

local vehicleIconOffsets = hud_react_util.makeVehicleIconOffsets(hudGuiConfig.vehicleIconOffsets)

base/content/gui/gui/main/selector_react_util.tl:208

local vehicleIconOffsets = hud_react_util.makeVehicleIconOffsets(hudGuiConfig.vehicleIconOffsets)

base/content/gui/gui/statistics/statistics.tl:441

local vehicleIconOffsets = hud_react_util.makeVehicleIconOffsets(hudGuiConfig.vehicleIconOffsets)

base/content/gui/gui/entity_window/station_group/station_group.tl:938

local vehicleIconOffsets = hud_react_util.makeVehicleIconOffsets(hudGuiConfig.vehicleIconOffsets)

base/content/gui/gui/entity_window/maintenance_station/maintenance_station.tl:148

local vehicleIconOffsets = hud_react_util.makeVehicleIconOffsets(hudGuiConfig.vehicleIconOffsets)

base/content/gui/gui/entity_window/vehicle/vehicle.tl:568

local vehicleIconOffsets = hud_react_util.makeVehicleIconOffsets(hudGuiConfig.vehicleIconOffsets)

… and 6 more files.

HudReactUtil.LineViewerSnapFactors¶

record base/tealdef/gui/hud/hud_react_util.d.tl:52

record LineViewerSnapFactors

Notes

Snap factors for the line viewer, passed as maxSnapFactorView and maxSnapFactorWorld to the line renderer config (see gui/line_vehicle_mgmt/line_util.tl).

Used in the base game: 6 times in 6 files

base/content/gui/gui/hud/hud_react_util.tl:375

hud_react_util.makeDefaultLineViewerSnapFactors = function() : HudReactUtil.LineViewerSnapFactors

base/content/gui/gui/statistics/statistics.tl:287

local snapFactorRef = react.useRefLazy(function() : HudReactUtil.LineViewerSnapFactors return hud_react_util.makeDefaultLineViewerSnapFactors() end)

base/content/gui/gui/entity_window/station_group/station_group.tl:928

local snapFactorRef = react.useRefLazy(function() : HudReactUtil.LineViewerSnapFactors return hud_react_util.makeDefaultLineViewerSnapFactors() end)

base/content/gui/gui/entity_window/vehicle/vehicle.tl:565

local snapFactorRef = react.useRefLazy(function() : HudReactUtil.LineViewerSnapFactors return hud_react_util.makeDefaultLineViewerSnapFactors() end)

base/content/gui/gui/entity_window/town/town.tl:1056

local snapFactorRef = react.useRefLazy(function() : HudReactUtil.LineViewerSnapFactors return hud_react_util.makeDefaultLineViewerSnapFactors() end)

base/content/gui/gui/entity_window/line/line.tl:173

local snapFactorRef = react.useRefLazy(function() : HudReactUtil.LineViewerSnapFactors return hud_react_util.makeDefaultLineViewerSnapFactors() end)

Fields

Name	Type	Description
`view`	`number`	Value for `maxSnapFactorView` (default 0.05).
`world`	`number`	Value for `maxSnapFactorWorld` (default 10.0).