|
file$ - the heightmap file that worlds and resources name, an image or a .b3height file; for a tiled terrain, its tile folder; it need not exist terrain - terrain entity whose heights and holes to use in its place |
|
Has worlds and resources loaded from now on use a copy of a terrain's heights in place of a heightmap file, and returns True, or False with the reason in TerrainResourceError(). It is how an editor shows heights it has not saved yet. The World Editor's Sculpt mode keeps sculpted heights in memory and sets them as the override, so the preview it rebuilds after each stroke - with its scattered trees and colliders - shows the new ground, and so does the terrain's own tab. Save writes the file with ExportTerrainData. The heights are copied when you call it; change the terrain afterwards and call it again to update the override. The file need not exist yet: a world or terrain definition may name it, and checks that referenced files exist count it as present while the override stands. Terrains already loaded keep their heights, and LoadTerrain still reads the file itself. For a tiled terrain, from CreateTiledTerrain, file$ is the folder of its tiles: each tile changed since it was read gets an override of its own file in that folder, and worlds that load the folder read those tiles from the overrides. Clearing the folder clears all of its tiles' overrides. ClearHeightmapOverride ends an override; HeightmapOverridden says whether a file has one. See also: ClearHeightmapOverride, HeightmapOverridden, ExportTerrainData, CreateTerrainResource, SculptTerrain. |
; SetHeightmapOverride Example
; ----------------------------
Graphics3D 640,480,0,2
SetBuffer BackBuffer()
camera=CreateCamera()
PositionEntity camera,32,40,-30
RotateEntity camera,40,0,0
CameraRange camera,0.1,400
light=CreateLight(1)
RotateEntity light,50,-30,0
; Loads the island's terrain definition into a terrain of its own, or 0
Function LoadIsland(document)
library=LoadResourceDocumentAsync(document)
If library=0 Then Return 0
While Not WorldReady(library)
If WorldLoadState(library)=WORLD_LOAD_FAILED Then
FreeWorld library
Return 0
EndIf
UpdateAsyncLoads 2
Wend
island=CreateTerrainResource(FindWorldAsset(library,"resource"))
FreeWorld library
Return island
End Function
SeedRnd MilliSecs()
; An island shaped in code and never saved: its heights are in memory only
sketch=CreateTerrain(64)
HideEntity sketch
SculptTerrain sketch,1,32,32,24,0.5,0.8
; Loads of this file, which does not exist, use the sketch's heights instead
file$="demo_island.b3height"
SetHeightmapOverride file,sketch
; A terrain definition that names the file, kept in memory too
document=CreateResourceDocument("terrain-definition","demo_island.terrain")
text$="{'format':'blitz3d.terrain','version':1,'id':'demo.island',"
text=text+"'assets':[{'id':'height','kind':'heightmap','source':'"+file+"'}],"
text=text+"'definition':{'heightmap':'height','dimensions':[64,12,64],'shading':true}}"
If ReplaceResourceDocumentSource(document,Replace(text,"'",Chr(34)),ResourceDocumentRevision(document))=0 Then RuntimeError ResourceDocumentError()
island=LoadIsland(document)
If island=0 Then RuntimeError ResourceDocumentError()
message$="The island was loaded from heights that are not on disk"
While Not KeyDown(1)
; Space adds a hill to the sketch, which stands in for the file again
If KeyHit(57) Then
SculptTerrain sketch,1,Rnd(8,56),Rnd(8,56),Rnd(4,10),0.3,0.8
SetHeightmapOverride file,sketch
FreeEntity island
island=LoadIsland(document)
message="Reloaded with the sketch's new heights"
EndIf
; C clears the override: now the file is missing and loading fails
If KeyHit(46) Then
ClearHeightmapOverride file
reloaded=LoadIsland(document)
If reloaded=0 Then
message="Without the override: "+Left(ResourceDocumentError(),60)
Else
FreeEntity reloaded
EndIf
EndIf
If island<>0 Then TurnEntity island,0,0.05,0
; Arrow keys move the camera
If KeyDown(200) Then MoveEntity camera,0,0,0.1
If KeyDown(208) Then MoveEntity camera,0,0,-0.1
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: add a hill and reload C: clear override Esc: exit"
Text 0,20,"HeightmapOverridden("+Chr(34)+file+Chr(34)+") = "+HeightmapOverridden(file)
Text 0,40,message
Flip
Wend
ClearHeightmapOverride
FreeResourceDocument document
End