SpatialHit

public readonly struct SpatialHit

The result of one spatial cast from a rendering node (TransformNodeWrapper.Cast, TransformNodeWrapper.CastTo). COMPONENT-AGNOSTIC: it knows nothing about rangefinders, reflectance pairs or beam-breaks; it reports geometry and lets the author name what they want to know about the surface. Everything is expressed in the CASTING node’s frame and in SI metres, so a part’s logic never has to deal in world coordinates.

Hit alone is a beam-break. Distance alone is a rangefinder. Normal and Incidence are what make an oblique surface behave like an oblique surface (specular dropout). SampleSurface is the whole “what is there” question, deferred to names the author owns on both ends.

Properties you read and set

Hit

public bool Hit { get; }

False when the ray reached its full length without striking anything, OR when no query was possible (nothing physical exists outside Play, before it or after Reset; the sensor is not yet registered; the call came from a place where the world cannot be asked). The other fields then read zero and SampleSurface returns its fallback. Never throws.

Distance

public double Distance { get; }

TRUE SI metres from the casting node’s origin to the strike point. 0 when !Hit.

Point

public Vector3 Point { get; }

The strike point, in metres, in the casting node’s own frame (scale removed).

Normal

public Vector3 Normal { get; }

Unit surface normal at the strike, in the casting node’s own frame.

Incidence

public double Incidence { get; }

|cos| of the angle between the ray and the surface normal: 1 = square-on, 0 = grazing. The one derivation every reflective or acoustic model makes.

None

static

public static SpatialHit None { get; }

The no-hit result.

Methods you call

SampleSurface

public double SampleSurface(string name, double fallback);

EXPLICITLY sample a named property of the surface that was struck - the surface fields its author typed on the body’s physics config (“IrReflectance: 0.05”). Names are free strings invented on both ends; the engine ships no list. Case-insensitive. Returns fallback when nothing was hit or the struck body declares no such field; pass the component’s own property so the inspector knob IS the bench value.

HasSurfaceField

public bool HasSurfaceField(string name);

True when the struck surface declares the named field.

ToString

override

public override string ToString();

A short readable form for a log line: the distance in metres and the incidence, or “no hit”.

Generated from the CRUMB source, commit fcec660d, 2026-10-29.