Blitz3D+ Command Reference

EntityMaterial ( entity,brush[,slot] )

Parameters

entity - target hierarchy

brush - brush supplying the material

slot (optional) - one-based surface slot; 0 applies to all surfaces (default)

Description

Assigns a material brush to an entity's surfaces after validating it.

All affected slots and LOD mappings are validated first, then independent brush instances are assigned - use it to reskin a car or swap a wall to its damaged material. Returns True on success, or 0 with MaterialError on failure; failure preserves the existing assignments.

The caller retains ownership of brush. This is a runtime edit and does not rewrite any world or resource document.

For the full story, see the reusable resources guide, which covers resource formats, ownership, editing and the save workflow.

Requires Extended mode.

See also: ValidateEntityMaterial, GetEntityMaterial, EntityMaterialSlots, MaterialError, PaintEntity.

Example

; EntityMaterial Example
; ----------------------
; Requires Extended mode.

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

Index