b3dTerrainHeight

Queries terrain height at world X/Z position (bilinear interpolation, returns world Y coordinate). Takes entity (terrain entity handle), worldX/worldZ (world space coordinates). Returns height (world Y coordinate at that position, terrain.position.Y if out of bounds). Converts world to local terrain space (subtract entity position, divide by scale), samples heightmap with bilinear interpolation (4 nearest samples, smooth between pixels), applies scales (entity.scale.Y * terrain.terrainScale.Y multiply height). Use for object placement (spawn objects on terrain surface, align to height), character ground position (footIK, character placement), AI pathfinding (query height for navigation), or visual effects (position particles at terrain level). Bilinear interpolation: finds 4 surrounding height samples (pixelX/Z floor and ceiling), interpolates horizontally (lerp between X samples), interpolates vertically (lerp between Z results), smooth continuous height (no stepping, pixel-accurate). Out of bounds: returns entity.position.Y if outside terrain (worldX/Z beyond terrain edges, fallback to base height), clamps to valid range (0 to heightmapWidth-1, 0 to heightmapHeight-1). Heightmap inversion: samples (1.0 - heightSample) to match GPU shader (white = high, black = low after inversion). Scale application: result = pos.Y + interpolatedHeight * scale.Y * terrainScale.Y (base position + scaled height, world space result). Use cases: spawn objects on surface (y = b3dTerrainHeight(terrain, x, z), b3dPositionEntity(object, x, y, z)), character placement (player.Y = b3dTerrainHeight(terrain, player.X, player.Z)), AI pathfinding (query heights along path, avoid steep slopes), projectile impact (determine impact height, spawn effects at terrain level). Performance: O(1) operation (constant time, 4 height samples and interpolation), safe to call per-frame (query for many objects, negligible cost <0.001ms), CPU-side query (doesn't involve GPU, immediate result). Coordinate systems: worldX/Z in world space (absolute coordinates, not relative), returned height in world space (entity.position.Y + offset, absolute Y). Validation: returns entity.position.Y if entity not terrain (invalid handle or wrong type), returns entity.position.Y if out of bounds (worldX/Z outside terrain area), no error messages (silent fallback to base height). Related: b3dCreateTerrain creates terrain (heightmap loaded, samples available for queries), b3dCreateTerrainPhysics creates physics (physics-based height queries alternative, raycasts), b3dPositionEntity positions objects (use queried height to place objects on terrain).