class_name TerrainGroundSample
extends RefCounted

## Immutable result of a terrain ground-height query in Godot world units.
## An unavailable sample carries a stable failure code instead of overloading a
## numeric height with `NAN` at the public boundary.

var is_available: bool:
	get:
		return _is_available

var height_units: float:
	get:
		return _height_units

var failure_code: StringName:
	get:
		return _failure_code

var _is_available: bool
var _height_units: float
var _failure_code: StringName


## Creates an available ground sample in Godot world units.
static func available(height_units_value: float) -> TerrainGroundSample:
	return TerrainGroundSample.new(true, height_units_value, &"")


## Creates an unavailable sample with a stable diagnostic code.
static func unavailable(failure_code_value: StringName) -> TerrainGroundSample:
	return TerrainGroundSample.new(false, 0.0, failure_code_value)


## Normalizes factory inputs so available samples are finite and unavailable
## samples always carry a non-empty failure code.
func _init(
		is_available_value: bool,
		height_units_value: float,
		failure_code_value: StringName
) -> void:
	_is_available = is_available_value and is_finite(height_units_value)
	_height_units = height_units_value if _is_available else 0.0
	if _is_available:
		_failure_code = &""
	elif not is_finite(height_units_value):
		_failure_code = &"terrain_height_not_finite"
	else:
		_failure_code = failure_code_value if not failure_code_value.is_empty() else &"terrain_unavailable"