|
document - reusable resource authoring handle flags (optional) - WORLD_LOAD_DEFAULT (default), or the flags of LoadWorldDocumentAsync added together, such as WORLD_LOAD_PLACEHOLDERS |
Sound definitions prepare PCM without initializing effects or playing it. A spatial sound preview has a listener and an entity named "emitter"; select its audio world explicitly before PlaySoundEmitter. Mix previews only prepare data; use BeginAudioMixPreview/EndAudioMixPreview to apply and restore it explicitly. See audio resources.
Environment and postfx resources also create a disposable camera/sphere/light preview. The environment applies only to that world; effects apply to its camera (FindWorldEntity(world, "camera")). Unmet HDR/tone-map prerequisites fail preparation without changing application settings. See appearance presets.
|
Starts loading a runtime world from a snapshot of a resource document. Returns an ordinary async world handle, or 0 if an initial snapshot cannot be made. The document may be edited or freed immediately afterwards. Service UpdateAsyncLoads and check WorldReady and WorldLoadError. The resource alias is "resource", and a prefab placement root is "instance". A single-body physics descriptor also creates an "instance" body; a multi-body descriptor is prepared without placement because it needs target bindings in a world. Loading does not select this world or start simulation or audio. Release the snapshot with FreeWorld. With WORLD_LOAD_PLACEHOLDERS, a picture, model, heightmap, sound, shader or collider data that the resource names and whose file is missing or cannot be read loads as a placeholder - a picture is a magenta checker, collider data a box - and WorldAssetError on that asset says why. An editor uses it so that a resource that has lost a file can still be previewed, changed and saved. Without it, such a file fails the load. For the full story, see the reusable resources guide, which covers resource formats, ownership, editing and the save workflow. See also: UpdateAsyncLoads, WorldReady, WorldLoadError, FreeWorld, LoadResourceDocument. |
; EntityMaterial Example
; ----------------------
Graphics3D 640,480,0,2
SetBuffer BackBuffer()
; Author a blue material in memory (nothing is written to disk)
document=CreateResourceDocument("material")
If document=0 Then RuntimeError ResourceDocumentError()
text$="{'protocol':'blitz3d.resource-document-edit','version':1,'revision':0,"
text=text+"'operations':[{'op':'set-material-property','property':'color','value':[0.15,0.35,0.8,1]}]}"
edit=ParseJson(Replace(text,"'",Chr(34)))
If ApplyResourceDocumentEdit(document,edit)=0 Then RuntimeError ResourceDocumentError()
FreeJson edit
; Prepare it as a runtime world, then take its material as a brush
prepared=LoadResourceDocumentAsync(document)
If prepared=0 Then RuntimeError ResourceDocumentError()
FreeResourceDocument document
While WorldReady(prepared)=0
If WorldLoadState(prepared)=WORLD_LOAD_FAILED Then RuntimeError WorldLoadError(prepared)
UpdateAsyncLoads 2
Wend
paint=WorldAssetMaterial(FindWorldAsset(prepared,"resource"))
FreeWorld prepared
camera=CreateCamera()
PositionEntity camera,0,0,-6
light=CreateLight()
RotateEntity light,25,35,0
; Two crates share the authored paint
left_crate=CreateCube()
PositionEntity left_crate,-1.5,0,0
right_crate=CreateCube()
PositionEntity right_crate,1.5,0,0
If EntityMaterial(left_crate,paint)=0 Then RuntimeError MaterialError()
If EntityMaterial(right_crate,paint)=0 Then RuntimeError MaterialError()
; Slot 99 does not exist: validation fails safely and explains why
bad=ValidateEntityMaterial(right_crate,paint,99)
bad_reason$=MaterialError()
; What a tool could list: slots, shader parameters and Standard properties
slots=EntityMaterialSlots(right_crate)
schema=MaterialPropertySchema()
slot_count=JsonCount(slots)
property_count=JsonCount(schema)
FreeJson slots
FreeJson schema
shader_params=MaterialShaderSchema(paint)
shader_param_count=JsonCount(shader_params)
FreeJson shader_params
shader=GetBrushShader(paint)
FreeBrush paint
damaged=False
While Not KeyDown(1)
; Space gives the right crate its own red copy of the material, and back
If KeyHit(57)
damaged=Not damaged
copy=GetEntityMaterial(right_crate)
If damaged Then BrushColor copy,220,50,30 Else BrushColor copy,38,89,204
If ValidateEntityMaterial(right_crate,copy)=0 Then RuntimeError MaterialError()
If EntityMaterial(right_crate,copy)=0 Then RuntimeError MaterialError()
FreeBrush copy
EndIf
TurnEntity left_crate,0.3,0.6,0
TurnEntity right_crate,0.3,-0.6,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: recolour the right crate Esc: exit"
Text 0,20,"EntityMaterial: both crates share one authored material; right crate red: "+damaged
Text 0,40,"ValidateEntityMaterial(crate,paint,99) = "+bad+" MaterialError: "+bad_reason
Text 0,60,"EntityMaterialSlots: "+slot_count+" MaterialPropertySchema entries: "+property_count
Text 0,80,"MaterialShaderSchema entries: "+shader_param_count+" GetBrushShader(paint) returned a shader: "+(shader<>0)+" (a classic material has none)"
Flip
Wend
If shader Then FreeShader shader
End