class_name RenderedGroundSample
extends RefCounted

## Immutable result of sampling currently loaded render terrain in Godot world units.
## This diagnostic value is renderer-owned and is not authoritative gameplay collision.

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

const SCRIPT_PATH := "res://src/render/terrain/rendered_ground_sample.gd"


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


## Creates an unavailable rendered-ground sample with a stable failure code.
static func unavailable(failure_code_value: StringName) -> RefCounted:
	return load(SCRIPT_PATH).new(false, 0.0, failure_code_value)


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 = &"render_terrain_height_not_finite"
	else:
		_failure_code = (
			failure_code_value
			if not failure_code_value.is_empty()
			else &"render_terrain_unavailable"
		)