Blitz3D+ Command Reference

TerrainHeight# ( terrain,terrain_x,terrain_z )

Parameters

terrain - terrain handle

terrain_x - grid x coordinate on the terrain

terrain_z - grid z coordinate on the terrain

Description

Returns the stored height of one point on a terrain's grid, in the range 0 to 1.

This is the exact counterpart of ModifyTerrain: it reads back the raw value you wrote, at a whole grid point, in the terrain's own 0 to 1 height scale. Use it whenever you are working with the height field itself - reading the ground before you raise or lower it, saving a sculpted landscape out to a file, checking whether a spot is high enough to be a mountain before you plant a tree on it.

It is not the command for "how high is the ground under my player". That is TerrainY, which takes world coordinates, interpolates between grid points, and hands back a world y that already accounts for the terrain's position, rotation and scale. TerrainHeight only ever looks at whole grid indices and only ever returns 0 to 1, so to turn its result into world units you have to multiply by the terrain's y scale yourself.

Grid coordinates run from 0 to the value TerrainSize returns. Index grid_size shares its storage with index 0 because the height field wraps, so those two always read the same value. Anything outside that range returns 0 rather than raising an error, which is easy to mistake for genuinely low ground - range-check your own coordinates if that distinction matters.

Heights are stored as 16-bit numbers, so what you read back can differ from what you wrote in the sixth decimal place: write 0.5 and you get 0.500008. That is harmless for a landscape but it means you should never compare heights with = when deciding whether a point has been modified. Compare against a small tolerance, or keep your own copy of the data.

See also: ModifyTerrain, TerrainY, TerrainSize, CreateTerrain.

Example

; TerrainHeight Example
; ---------------------

Graphics3D 640,480,0,2
SetBuffer BackBuffer()

; Terrain layout: 32 grid squares, scaled to 10 units per square
terra_size=32
x_scale=10
y_scale=50
z_scale=10

; Overlook the terrain from a fixed camera
camera=CreateCamera()
PositionEntity camera,(terra_size*x_scale)/2,120,-60
RotateEntity camera,35,0,0

light=CreateLight()
RotateEntity light,45,45,0

; Create a terrain and sculpt a few hills to explore
terrain=CreateTerrain(terra_size)
ScaleEntity terrain,x_scale,y_scale,z_scale
For x=0 To terra_size
    For z=0 To terra_size
        ModifyTerrain terrain,x,z,(Sin(x*33)+Cos(z*28)+2)*0.15
    Next
Next

; Texture the terrain
grass_tex=LoadTexture("media/MossyGround.BMP")
EntityTexture terrain,grass_tex

; A red marker that rides the terrain surface
marker=CreateSphere(8)
EntityColor marker,255,60,60
EntityFX marker,1

marker_x=terra_size/2
marker_z=terra_size/2

While Not KeyDown(1)

    ; Cursor keys step the marker across the terrain grid
    If KeyHit(205) And marker_x<terra_size Then marker_x=marker_x+1
    If KeyHit(203) And marker_x>0 Then marker_x=marker_x-1
    If KeyHit(200) And marker_z<terra_size Then marker_z=marker_z+1
    If KeyHit(208) And marker_z>0 Then marker_z=marker_z-1

    ; TerrainHeight returns the stored height (0 to 1) at a grid point
    height#=TerrainHeight(terrain,marker_x,marker_z)

    ; Use the returned height to sit the marker on the ground
    PositionEntity marker,marker_x*x_scale,height*y_scale+2,marker_z*z_scale

    RenderWorld

    Text 0,0,"Cursor keys: move the marker over the hills   Esc: exit"
    Text 0,20,"TerrainHeight(terrain,"+marker_x+","+marker_z+") = "+height

    Flip

Wend

End

Index