|
entity - target hierarchy brush - brush supplying the material slot (optional) - one-based surface slot; 0 checks all surfaces (default) |
|
Checks whether EntityMaterial would succeed, without changing anything. The hierarchy, slots, LOD mapping and surface shader compatibility are checked. Returns True on success, or 0 with MaterialError on failure. It does not inspect an authored modelRevision; that check belongs to world loading. A successful preflight does not lock source files or prevent later runtime changes. For the full story, see the reusable resources guide, which covers resource formats, ownership, editing and the save workflow. See also: EntityMaterial, MaterialError, GetEntityMaterial. |
; 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