| document - world document handle, from LoadWorldDocument or CreateWorldDocument |
|
Opens a world document's workspace: the world and every resource it uses, edited together. A world leans on many other documents - materials, prefabs, physics, particles, sounds, presets - and a tool that edits them needs to change several at once, undo them in one step and save them together. The workspace holds the world and every resource document it reaches in memory, with one shared undo history. Nothing is written until you save with SaveWorldDocumentSet. Returns True when the workspace is open; opening it again keeps the workspace and its history. Returns False, with the reason in WorldDocumentError(), when a resource the world needs is missing or invalid - repair the world with the ordinary document commands, then try again. A model, picture, heightmap, sound, shader or collider whose file is missing does not stop the workspace, its edits or its saves. The documents keep naming the file, so the world loads again once the file is back, and ValidateWorldDocument lists it meanwhile. A missing resource document - a material, prefab and so on - does stop it. Then WorldDocumentWorkspaceJson lists the documents and their revisions, EditWorldDocumentWorkspace changes them, WorldDocumentWorkspaceHistory names the undo and redo steps, and LoadWorldResourceDocument opens one resource from the workspace for editing. The World Editor works this way: Save All, Project Dependencies and the shared Undo all use the workspace. For the full story - the edit protocol, Save All, recovery, export plans and limits - see the Saving and exporting resource projects guide. See also: EditWorldDocumentWorkspace, WorldDocumentWorkspaceJson, WorldDocumentWorkspaceHistory, LoadWorldResourceDocument, SaveWorldDocumentSet. |
; 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