Skip to main content

Editor Documents

In the editor nearly everything that you work with is a dedicated document. Most documents are backed by a file, which is usually in OpenDDL format.

Documents are an editor specific representation of things like scenes, prefab, materials and so on. The document format is not understood by the runtime and therefore cannot be loaded by applications like Player directly.

A document can represent any type of data. However, the most common case is, that it represents data that shall be converted (or transformed) from its source representation into something that the engine runtime can use. For example a texture must be transformed from a source JPG format to a more optimized DDS format. These types of documents are called assets in Plasma and they are by far the most common type of document.

The only exception to documents in the editor are things like project settings and editor settings, which are not handled by documents.

Saving documents​

The File menu of a document has these save commands:

CommandShortcutDescription
SaveCtrl+SSaves the document to its file.
Save As...Saves a copy of the document under a new name and opens the copy.
Restore Previous Version...Brings back the version the file had before its latest save.
Save AllCtrl+Shift+SSaves every modified document.

Saving is safe against failures: the editor writes the new content to a temporary file first and only replaces the document's file once that has succeeded. If saving fails, the file on disk is left as it was and the document stays modified.

Unsaved work is also protected by autosave, which keeps a snapshot of every modified document and offers it after a crash.

Save As​

Save As... writes the document's current state, including unsaved changes, straight to the new file. The original document and its file are not changed: the original stays open, with its unsaved changes, and the copy opens as a second document.

If Save As fails, the editor tells you, and adds The original document and file were not changed.

Some documents consist of more than one file, for example a scene with layers. Save As copies such extra files as they are saved on disk. If one of them has unsaved changes, the status bar says Saved as a copy. Unsaved changes of N were not included and lists the files. Save those documents first if the copy should include their changes.

Save All​

Save All tries to save every modified document, even when some of them fail. When everything was saved, nothing else happens. Otherwise the Save Results window lists each document with its result:

ResultMeaning
SavedThe file holds the document's content.
FailedSaving was tried and failed, for example because the file is write-protected. The reason is shown.
CancelledYou, or a save request such as version control, declined to save the document.
SkippedThe document is read-only and was not saved.

Documents that were not saved stay modified. Retry Failed saves the failed documents again, Copy Details copies the result of every document to the clipboard, and Close leaves the unsaved documents as they are.

When you close the editor or a project with modified documents, the editor asks which documents to save. If some of them can't be saved, it says N document(s) could not be saved. Fix them and press Save All again, or choose Don't Save.

Restoring the previous version​

Every time a document is saved, the editor keeps the version the file had before that save as a backup. There is one backup per document, and each save replaces it. The backup lives in the project's Autosave folder, next to the autosave snapshots.

To bring it back, choose File > Restore Previous Version.... The Restore Previous Version dialog shows when the Previous save and the Last save were made, and what the previous version has that the saved file does not. Restore opens the previous version as the document, marked as unsaved. The file only changes when you save it, so you can still close the document without saving to go back to the latest save.

  • The command is greyed out until a document has a previous version. A document gets one with its second save.
  • If the document has unsaved changes, the dialog warns that restoring discards them.
  • If the backup can't be updated during a save, the document is still saved and the status bar says Document saved, but the previous-version backup could not be updated.

Undo history​

Every document has its own undo history. Undo (Ctrl+Z) and Redo (Ctrl+Y) step through it. The arrow next to the Undo and Redo toolbar buttons lists the steps, so you can undo or redo several at once.

Where the saved state is​

The status bar of a document shows whether it is saved and how far away the saved state is:

StatusMeaning
SavedThe document is the same as its file.
Unsaved: saved state 3 steps backUndoing three steps brings the document back to what was saved. ahead means redoing gets there.
Unsaved: saved state no longer in historyThe saved state is older than the oldest undo step that is still kept.
UnsavedThe document was changed in a way that is not in the undo history.

The tooltip of this readout shows how many undo steps the document has, roughly how much memory they use, and the limits. In the Undo and Redo lists the step that leads to the saved state is marked (saved state).

How much history is kept​

Undo steps take memory, especially steps that delete many objects or paste large amounts of data. The editor therefore limits the history. When a limit is reached, the oldest steps are removed. The limits are in Tools > Preferences... > Application: General, group Undo History:

PreferenceDefaultRangeDescription
Max Undo Steps50010 to 10000How many undo steps a document keeps.
Max Undo Memory MB25616 to 4096Roughly how much memory the undo steps of one document may use.
Max Total Undo Memory MB102464 to 16384Roughly how much memory the undo steps of all open documents may use together. Over this budget, the oldest steps of any document go first, but no document drops below 10 steps that way.
Undo Memory In Use(read-only)How much memory the undo history of all open documents uses now.

A lower limit applies to the open documents as soon as you change it. The editor then reports Undo history trimmed: N steps removed in the status bar of each document that lost steps.

When steps are removed because of the memory limits, the first time in a document the status bar says Note: Oldest undo steps removed to stay under N MB. An edit that is larger than the memory limit on its own shows a warning notification, Large edit: undo history trimmed. When older steps were removed, the Undo list ends with a row Older steps removed (limit N steps).

See Also​