Blitz3D+ Command Reference

SaveResourceDocument ( document[,file$][,expected_destination_revision$] )

Parameters

document - resource authoring handle

file$ (optional) - Save As destination; "" saves to the adopted path (default)

expected_destination_revision$ (optional) - current SHA-256 digest of a different existing destination you intend to replace; "" (default)

Description

Validates and atomically saves a resource document.

Returns True on success or 0 on failure. Save As rebases relative dependencies. A changed adopted file is rejected, so another tool's edits are never overwritten silently. An existing different target requires its current SHA-256 digest; a new target does not.

Saving one resource does not save any parent world that references it.

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

Requires Extended mode.

See also: ResourceDocumentPath, ResourceDocumentDiskRevision, ValidateResourceDocument, SaveResourceDocumentWithWorldEdit, Sha256File.

Example

; SaveResourceDocument Example
; ----------------------------
; Requires Extended mode.

Print "This example saves demo_paint.material next to itself, then deletes it."
Print "Press Y to continue, any other key to skip."
WaitKey
If KeyDown(21)

    file$="demo_paint.material"
    document=CreateResourceDocument("material")
    If document=0 Then RuntimeError ResourceDocumentError()

    ; An untitled document needs a path on its first save (Save As)
    If SaveResourceDocument(document,file$)=0 Then RuntimeError ResourceDocumentError()
    Print "Saved: "+ResourceDocumentPath(document)
    Print "  dirty after saving: "+ResourceDocumentDirty(document)
    Print "  disk revision: "+Left(ResourceDocumentDiskRevision(document),16)+"..."
    FreeResourceDocument document

    ; Load the file back as an editable document
    reloaded=LoadResourceDocument(file$)
    If reloaded=0 Then RuntimeError ResourceDocumentError()
    Print ""
    Print "LoadResourceDocument reopened it; the disk revision matches: "+Left(ResourceDocumentDiskRevision(reloaded),16)+"..."
    FreeResourceDocument reloaded

    ; A missing file returns 0, with the reason and diagnostics retained
    missing=LoadResourceDocument("no_such_paint.material")
    Print ""
    Print "Loading a missing file returned "+missing
    Print "  ResourceDocumentError: "+ResourceDocumentError()

    DeleteFile file$
    Print ""
    Print "Demo file deleted"

Else
    Print "Skipped"
EndIf

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

End

Index