|
document - world document handle, from LoadWorldDocument or CreateWorldDocument resources - JSON array of the resource drafts to save, each an object with document (a resource document handle) and revision (its ResourceDocumentRevision); an empty array saves the world alone revision:Long - the WorldDocumentRevision you expect the world to be at project_directory$ - the project folder; every file saved must be inside it world_file$ (optional) - where to save the world, needed for a world's first save or to save it as a new file; "" keeps its own file (default) expected_destination_revision$ (optional) - when world_file$ names a different file that exists, the SHA-256 you saw it with, so a file you have not seen is never overwritten; "" (default) |
|
Saves a world and its changed resources together, as one checked set. This is Save All. The world, the resource drafts you list and the changes waiting in the world's workspace are checked together, and then all written - or none. Before anything is replaced, the new files, backups of the old ones and a journal are put in a .b3d-save-journal folder in the project, so RecoverWorldDocumentSet can undo or finish a save that was interrupted. Each draft needs a file of its own and an up-to-date revision, and every file you opened must still be as it was on disk: a file another program changed stops the save. Up to 255 drafts can go in one save, and 256 documents in all. A model, picture, heightmap, sound, shader or collider whose file is missing does not stop the save: the documents keep its path, so the world loads again once the file is back. A successful save clears the world's and the saved drafts' dirty flags and records their new disk revisions. Saving the world to a new world_file$ moves the workspace there, updating its references, and starts a new history; the old world file is kept. Draft entries can also have publish, preview and worldEdit fields, which save an embedded resource or an object's settings as part of the world, as the World Editor does. Returns True, or False with the reason in WorldDocumentError() and the details in WorldDocumentDiagnostics(). For the full story - the edit protocol, Save All, recovery, export plans and limits - see the Saving and exporting resource projects guide. See also: RecoverWorldDocumentSet, ExportWorldProject, OpenWorldDocumentWorkspace, SaveWorldDocument, ResourceDocumentRevision. |
; SaveWorldDocumentSet Example
; ----------------------------
Print "This example saves a tiny project into demo_project next to itself,"
Print "exports a copy into demo_export, then deletes both folders."
Print "Press Y to continue, any other key to skip."
WaitKey
If KeyDown(21)
; A world that uses a paint material: the project's first two files
CreateDir "demo_project"
paint_text$="{'format':'blitz3d.material','version':1,'id':'paint','assets':[],"
paint_text=Replace(paint_text+"'definition':{'model':'classic','color':[0.2,0.5,0.9,1]}}","'",Chr(34))
scene_text$="{'format':'blitz3d.world','version':1,'id':'scene','entities':[],"
scene_text=scene_text+"'assets':[{'id':'paint','kind':'material','source':'paint.material','loading':'required'}]}"
WriteTextAtomic "demo_project/paint.material",paint_text
WriteTextAtomic "demo_project/scene.world",Replace(scene_text,"'",Chr(34))
world=LoadWorldDocument("demo_project/scene.world")
paint=LoadResourceDocument("demo_project/paint.material")
; Repaint the material in memory: a draft that is not saved yet
ReplaceResourceDocumentSource paint,Replace(paint_text,"0.2,0.5,0.9","0.9,0.3,0.1"),ResourceDocumentRevision(paint)
Print ""
Print "Before saving, the paint draft is dirty: "+ResourceDocumentDirty(paint)
; Save the world and the paint together, as one checked set
text$="[{'document':"+paint+",'revision':"+ResourceDocumentRevision(paint)+"}]"
drafts=ParseJson(Replace(text,"'",Chr(34)))
If Not SaveWorldDocumentSet(world,drafts,WorldDocumentRevision(world),"demo_project") Then RuntimeError WorldDocumentError()
FreeJson drafts
Print "SaveWorldDocumentSet returned True; the paint is dirty: "+ResourceDocumentDirty(paint)
; A save that was cut short leaves a journal folder to recover from
If FileType("demo_project/.b3d-save-journal")=2 Then
If Not RecoverWorldDocumentSet("demo_project") Then RuntimeError WorldDocumentError()
Print "Recovered an interrupted save"
Else
Print "No save was interrupted, so RecoverWorldDocumentSet has nothing to do"
EndIf
; Export the world and everything it needs into a new folder
text="{'format':'blitz3d.resource-export','version':1,'projectRoot':'.','roots':['scene.world']}"
WriteTextAtomic "demo_project/export.json",Replace(text,"'",Chr(34))
manifest=ExportWorldProject("demo_project/export.json","demo_export")
If manifest=0 Then RuntimeError WorldDocumentError()
files=JsonObjectGet(manifest,"files")
Print "ExportWorldProject copied "+JsonCount(files)+" files into demo_export"
FreeJson files
FreeJson manifest
FreeResourceDocument paint
FreeWorldDocument world
RemoveDemoFolder("demo_export")
RemoveDemoFolder("demo_project")
Print "Demo folders deleted"
Else
Print "Skipped"
EndIf
Print ""
Print "Press any key to close the example"
WaitKey
End
; Delete a folder this example made, with the files in it
Function RemoveDemoFolder(folder$)
listing=ReadDir(folder)
Repeat
file$=NextFile(listing)
If FileType(folder+"/"+file)=1 Then DeleteFile folder+"/"+file
Until file=""
CloseDir listing
DeleteDir folder
End Function