Blitz3D+ Command Reference

ApplyResourceDocumentWorldEdit ( document,world_document,edit,revision:Long[,preview_world] )

Parameters

document - resource authoring handle

world_document - world document handle

edit - blitz3d.world-document-edit transaction, version 1, with expectedRevision

revision:Long - the edit revision you last observed with ResourceDocumentRevision

preview_world (optional) - matching ready material snapshot; 0 for none (default)

Description

Commits embedded material or override changes to a world without saving files.

The world transaction must contain the intended definition/binding edits, and all descriptor dependencies and bindings are checked. A supplied preview guards its actual inputs and checks affected effective materials against its prepared shader. An adopted shared source changed since opening rejects the edit.

Returns True on success or 0 with ResourceDocumentError. Success advances only the world revision and leaves it dirty; the resource document, resource revision and disk files remain unchanged, so save the world separately. The caller retains edit and preview_world; imported slot mapping still requires model preparation.

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

Requires Extended mode.

See also: SaveResourceDocumentWithWorldEdit, ApplyWorldDocumentEdit, SaveWorldDocument, ResourceDocumentError.

Example

; SaveResourceDocumentWithWorldEdit Example
; -----------------------------------------
; Requires Extended mode.

; A level (world document) that carries its own inline paint material
q$=Chr(34)
world=CreateWorldDocument("paint-shop","Paint shop")
text$="{'protocol':'blitz3d.world-document-edit','version':1,'expectedRevision':0,'operations':[{'op':'asset.add','asset':"
text=text+"{'id':'paint','kind':'material','loading':'required','inline':{'format':'blitz3d.material','version':1,"
text=text+"'id':'demo.material.paint','name':'Paint','assets':[],'definition':{'model':'classic','color':[0.2,0.6,0.2,1]}}}}]}"
edit=ParseJson(Replace(text,"'",q))
If ApplyWorldDocumentEdit(world,edit)=0 Then RuntimeError WorldDocumentError()
FreeJson edit
Print "World revision after adding the inline paint: "+WorldDocumentRevision(world)

; Edit the paint as its own resource document, recoloured red
paint=CreateResourceDocument("material")
text="{'protocol':'blitz3d.resource-document-edit','version':1,'revision':0,"
text=text+"'operations':[{'op':'set-material-property','property':'color','value':[0.8,0.1,0.1,1]}]}"
edit=ParseJson(Replace(text,"'",q))
If ApplyResourceDocumentEdit(paint,edit)=0 Then RuntimeError ResourceDocumentError()
FreeJson edit

; Commit the red paint into the level's inline asset - no files involved
op=ParseJson(Replace("{'op':'asset.update','id':'paint','asset':{}}","'",q))
payload=JsonObjectGet(op,"asset")
inline=ResourceDocumentJson(paint)
JsonObjectSet payload,"inline",inline
FreeJson inline
JsonObjectSet op,"asset",payload
FreeJson payload
transaction=MakeTransaction(WorldDocumentRevision(world),op)
FreeJson op
If ApplyResourceDocumentWorldEdit(paint,world,transaction,ResourceDocumentRevision(paint))=0 Then RuntimeError ResourceDocumentError()
FreeJson transaction
Print ""
Print "ApplyResourceDocumentWorldEdit committed the red paint into the level"
Print "  world revision: "+WorldDocumentRevision(world)+"   world dirty: "+WorldDocumentDirty(world)
Print "  no file was written; the paint document still has unsaved edits: "+ResourceDocumentDirty(paint)

; Saving the paint to its own file and renaming the level happen together
Print ""
Print "Next, SaveResourceDocumentWithWorldEdit writes demo_paint.material and"
Print "renames the level in one step. Press Y to do this, any other key to skip."
WaitKey
If KeyDown(21)
    op=ParseJson(Replace("{'op':'document.identity','name':'Paint shop (red)'}","'",q))
    transaction=MakeTransaction(WorldDocumentRevision(world),op)
    FreeJson op
    If SaveResourceDocumentWithWorldEdit(paint,world,transaction,ResourceDocumentRevision(paint),"demo_paint.material")=0 Then RuntimeError ResourceDocumentError()
    FreeJson transaction
    Print "Saved: "+ResourceDocumentPath(paint)
    Print "  the level revision advanced to "+WorldDocumentRevision(world)+"; save the level file separately"
    DeleteFile "demo_paint.material"
    Print "Demo file deleted"
Else
    Print "Skipped"
EndIf

FreeResourceDocument paint
FreeWorldDocument world

Print ""
Print "Press any key to close the example"
WaitKey

End

; Wrap one operation in a world-document edit transaction
Function MakeTransaction(revision,operation)
    transaction=ParseJson("{"+Chr(34)+"protocol"+Chr(34)+":"+Chr(34)+"blitz3d.world-document-edit"+Chr(34)+","+Chr(34)+"version"+Chr(34)+":1}")
    expected=CreateJsonInteger(revision)
    JsonObjectSet transaction,"expectedRevision",expected
    FreeJson expected
    operations=CreateJsonArray()
    JsonArrayAppend operations,operation
    JsonObjectSet transaction,"operations",operations
    FreeJson operations
    Return transaction
End Function

Index