|
kind$ - "material", "prefab", "physics", "particles", "environment", "postfx", "sound-definition", "audiomix", "animset", "terrain-definition" or "native-ui" file$ (optional) - path that also sets the base for relative dependencies; "" leaves the document untitled (default) world_document (optional) - world document whose staged dependency snapshot is used for validation and preview; default 0 uses disk dependencies |
|
Creates a new reusable resource document for editing. A sound-definition draft requires a WAV/Ogg source before preparation or saving; audiomix starts with neutral defaults. See audio resources. Environment and camera presets use environment and postfx; see the appearance guide. Resource documents are how tools author reusable content: a paint material, a crate prefab, a physics assembly. The new document is dirty; the file is written only when saved, and an untitled document needs an explicit path on its first save. Returns 0 with ResourceDocumentError on failure. Free the handle with FreeResourceDocument. For the full story, see the reusable resources guide, which covers resource formats, ownership, editing and the save workflow. See also: LoadResourceDocument, SaveResourceDocument, FreeResourceDocument, CreatePrefabDocument, ResourceDocumentError. |
; CreateResourceDocument Example
; ------------------------------
; Create an untitled material document in memory; nothing touches the disk
document=CreateResourceDocument("material")
If document=0 Then RuntimeError ResourceDocumentError()
Print "New material document"
Print " path: '"+ResourceDocumentPath(document)+"' (untitled)"
Print " dirty: "+ResourceDocumentDirty(document)
Print " revision: "+ResourceDocumentRevision(document)
; Recolour it with an edit transaction made at the revision we observed
revision=ResourceDocumentRevision(document)
text$="{'protocol':'blitz3d.resource-document-edit','version':1,'revision':"+revision+","
text=text+"'operations':[{'op':'set-material-property','property':'color','value':[0.9,0.4,0.1,1]}]}"
edit=ParseJson(Replace(text,"'",Chr(34)))
If ApplyResourceDocumentEdit(document,edit)=0 Then RuntimeError ResourceDocumentError()
Print ""
Print "ApplyResourceDocumentEdit succeeded; revision is now "+ResourceDocumentRevision(document)
; The same edit is now stale, so it is rejected and nothing changes
Print "Applying it again returns "+ApplyResourceDocumentEdit(document,edit)
Print " ResourceDocumentError: "+ResourceDocumentError()
FreeJson edit
; Broken replacement text is rejected too, with diagnostics
If ReplaceResourceDocumentSource(document,"{",ResourceDocumentRevision(document))=0
diagnostics=ResourceDocumentDiagnostics(document)
Print ""
Print "ReplaceResourceDocumentSource rejected '{' with "+JsonCount(diagnostics)+" diagnostic(s)"
FreeJson diagnostics
EndIf
; Validation reports on the document without changing it
report=ValidateResourceDocument(document)
valid=JsonObjectGet(report,"valid")
Print ""
Print "ValidateResourceDocument valid: "+JsonBoolean(valid)
FreeJson valid
FreeJson report
; Read the colour back from a JSON snapshot of the document
snapshot=ResourceDocumentJson(document)
definition=JsonObjectGet(snapshot,"definition")
Print "Authored definition: "+JsonStringify(definition)
FreeJson definition
FreeJson snapshot
Print "Source text length: "+Len(ResourceDocumentSource(document))+" characters"
; Diagnostics of the latest operation in this program, handle or not
latest=ResourceDocumentLastDiagnostics()
Print "Latest operation diagnostics: "+JsonCount(latest)
FreeJson latest
FreeResourceDocument document
Print ""
Print "Press any key to close the example"
WaitKey
End