|
asset - a ready terrain definition asset, from FindWorldAsset parent (optional) - parent entity for the new terrain; 0 for none (default) |
|
Creates a terrain from a terrain definition, with its heights, look and scattered models. A terrain definition (.terrain file) brings together everything a landscape needs: a heightmap, its size in world units, detail and level-of-detail settings, its material, and a recipe that scatters models such as trees over it. Load the definition with LoadResourceDocument and LoadResourceDocumentAsync, wait for WorldReady, and pass FindWorldAsset(world,"resource"). Each call creates a new, ordinary terrain: shape it with ModifyTerrain, punch holes in it and read TerrainHeight, just as with LoadTerrain. Each terrain has its own copy of the heights and holes, so digging into one leaves every other terrain made from the same definition alone. The scattered models are placed once, where the recipe puts them; they do not follow later changes to the heights. The terrain goes into the selected world, or the parent's world, and keeps working after you free the world that loaded the definition. Free it with FreeEntity. Returns 0 when the asset is not a ready terrain definition, and TerrainResourceError() says why. The World Editor's Terrain tab edits terrain definitions. For the full story, see the Terrain resources guide and its complete TerrainResources.bb sample. See also: ExportTerrainData, ApplyTerrainMaterial, TerrainResourceError, LoadTerrain, ModifyTerrain. |
; CreateTerrainResource Example
; -----------------------------
Graphics3D 640,480,0,2
SetBuffer BackBuffer()
camera=CreateCamera()
PositionEntity camera,67,35,-35
RotateEntity camera,30,0,0
CameraRange camera,0.1,400
light=CreateLight()
RotateEntity light,35,-30,0
AmbientLight 90,95,105
; The hills terrain definition: heightmap, size, layers and trees
document=LoadResourceDocument("../../../samples/terrain-resources/hills.terrain")
If document=0 Then RuntimeError ResourceDocumentError()
library=LoadResourceDocumentAsync(document)
FreeResourceDocument document
While Not WorldReady(library)
If WorldLoadState(library)=WORLD_LOAD_FAILED Then RuntimeError WorldLoadError(library)
UpdateAsyncLoads 2
Wend
asset=FindWorldAsset(library,"resource")
; Two terrains from one definition, each with heights of its own
left_hills=CreateTerrainResource(asset)
right_hills=CreateTerrainResource(asset)
If left_hills=0 Or right_hills=0 Then RuntimeError TerrainResourceError()
PositionEntity right_hills,70,0,0
; The terrains keep everything they need when the loader world goes
FreeWorld library
raised=False
file$="demo_hills.b3height"
message$="E saves the left terrain's heights to "+file
While Not KeyDown(1)
; Space raises or flattens a patch of the left terrain only
If KeyHit(57) Then
raised=Not raised
BeginTerrainUpdate left_hills
For z=24 To 40
For x=24 To 40
height#=TerrainHeight(right_hills,x,z)
If raised Then height=1.0
ModifyTerrain left_hills,x,z,height
Next
Next
EndTerrainUpdate left_hills
EndIf
; E exports the exact heights; a second E finds the file already there
If KeyHit(18) Then
If ExportTerrainData(left_hills,file) Then
copy=LoadTerrain(file)
message="Exported, and LoadTerrain reads height "+TerrainHeight(copy,32,32)+" back"
FreeEntity copy
Else
message=TerrainResourceError()
EndIf
EndIf
; Arrow keys move the camera
If KeyDown(200) Then MoveEntity camera,0,0,0.5
If KeyDown(208) Then MoveEntity camera,0,0,-0.5
If KeyDown(203) Then TurnEntity camera,0,1,0
If KeyDown(205) Then TurnEntity camera,0,-1,0
RenderWorld
Text 0,0,"Arrow keys: move camera Space: raise patch E: export heights Esc: exit"
Text 0,20,"Left height: "+TerrainHeight(left_hills,32,32)+" Right height: "+TerrainHeight(right_hills,32,32)
Text 0,40,message
Flip
Wend
; The exported file was only for this demonstration
If FileType(file)=1 Then DeleteFile file
End