|
world_document - world document whose workspace the resource belongs to file$ - path of the resource file, such as "stone.material" repair (optional) - True to keep a file that fails validation, so its text can be corrected; False to refuse it (default) |
|
Opens a resource for editing as the world's workspace has it, unsaved changes and all. When the world has a workspace that holds the resource, the resource is read from there - with its edits, undos and new files that are not saved yet. Otherwise it is read from disk, as LoadResourceDocument does. Either way you get an ordinary resource document: an independent draft to edit, validate and preview, then free with FreeResourceDocument. Validation and LoadResourceDocumentAsync see the other files as the workspace has them too. Saving the draft with SaveWorldDocumentSet records the resource and the world together, as one step in the shared undo history. A picture, model, heightmap, sound, shader or collider data whose file is missing does not stop the resource opening, with or without repair, as it does not stop the world's workspace. The draft can be edited and saved, keeping the file's path, so the resource mends when the file is back; an edit that names a missing file anew is refused (ReplaceResourceDocumentSource). ValidateResourceDocument lists each missing file, and LoadResourceDocumentAsync with WORLD_LOAD_PLACEHOLDERS previews the resource with a placeholder for each. A missing resource document still stops it. Returns 0 when the resource cannot be opened, and WorldDocumentError() says why. For the full story - the edit protocol, Save All, recovery, export plans and limits - see the Saving and exporting resource projects guide. See also: OpenWorldDocumentWorkspace, LoadResourceDocument, SaveWorldDocumentSet, FreeResourceDocument. |
; OpenWorldDocumentWorkspace Example
; ----------------------------------
; Everything here happens in memory: no file is written
world=LoadWorldDocument("../../../samples/courtyard/courtyard.world")
If world=0 Then RuntimeError WorldDocumentError()
If Not OpenWorldDocumentWorkspace(world) Then RuntimeError WorldDocumentError()
stone_file$="../../../samples/courtyard/stone.material"
; The report lists the world and every resource it uses
report=WorldDocumentWorkspaceJson(world)
documents=JsonObjectGet(report,"documents")
Print "Workspace revision "+WorldDocumentWorkspaceRevision(world)+": "+JsonCount(documents)+" documents"
FreeJson documents
FreeJson report
; Warm up the stone material, starting from its staged text...
staged=LoadWorldResourceDocument(world,stone_file)
stone=ResourceDocumentJson(staged)
FreeResourceDocument staged
definition=JsonObjectGet(stone,"definition")
colour=ParseJson("[0.95,0.6,0.4,1]")
JsonObjectSet definition,"color",colour
JsonObjectSet stone,"definition",definition
stone_text=CreateJsonString(JsonStringify(stone))
FreeJson colour
FreeJson definition
FreeJson stone
; ...and give the world a new name
scene=WorldDocumentJson(world)
name=CreateJsonString("Warm courtyard")
JsonObjectSet scene,"name",name
scene_text=CreateJsonString(JsonStringify(scene))
FreeJson name
FreeJson scene
; One edit changes both; a fresh workspace has every document at revision 1
text$="{'protocol':'blitz3d.document-workspace-edit','version':1,'operation':'edit',"
text=text+"'label':'Warm up the courtyard','expectedRevision':"+WorldDocumentWorkspaceRevision(world)+","
text=text+"'changes':[{'path':'stone.material','revision':1},{'path':'courtyard.world','revision':1}]}"
edit=ParseJson(Replace(text,"'",Chr(34)))
changes=JsonObjectGet(edit,"changes")
For index=0 To 1
change=JsonArrayGet(changes,index)
If index=0 Then JsonObjectSet change,"source",stone_text Else JsonObjectSet change,"source",scene_text
JsonArraySet changes,index,change
FreeJson change
Next
JsonObjectSet edit,"changes",changes
If Not EditWorldDocumentWorkspace(world,edit) Then RuntimeError WorldDocumentError()
FreeJson changes
FreeJson edit
FreeJson scene_text
FreeJson stone_text
Print "After the edit, revision "+WorldDocumentWorkspaceRevision(world)+"; undo would undo '"+WorldDocumentWorkspaceHistory(world)+"'"
; Opening the material again reads the staged text, not the file
staged=LoadWorldResourceDocument(world,stone_file)
stone=ResourceDocumentJson(staged)
definition=JsonObjectGet(stone,"definition")
colour=JsonObjectGet(definition,"color")
Print "The staged stone colour is "+JsonStringify(colour,0)
FreeJson colour
FreeJson definition
FreeJson stone
FreeResourceDocument staged
; Preview the world that undo would give back, changing nothing
preview=ParseJson(WorldDocumentWorkspaceUndoSource(world))
old_name=JsonObjectGet(preview,"name")
Print "Undo would bring back the name '"+JsonText(old_name)+"'"
FreeJson old_name
FreeJson preview
; Undo is an edit too, checked against the current revision
text="{'protocol':'blitz3d.document-workspace-edit','version':1,'operation':'undo','expectedRevision':"
undo=ParseJson(Replace(text,"'",Chr(34))+WorldDocumentWorkspaceRevision(world)+"}")
If Not EditWorldDocumentWorkspace(world,undo) Then RuntimeError WorldDocumentError()
FreeJson undo
Print "After undo, redo would redo '"+WorldDocumentWorkspaceHistory(world,True)+"'"
FreeWorldDocument world
Print ""
Print "Press any key to close the example"
WaitKey
End