This is a comprehensive guide on how to use the package in your own project.
You can use it together with the Demo Project to learn how to use the package.
To install the package you can just put it in your projects Packages folder.
An alternative is to install it via the Unity Package Manager via the git URL. (It's possible to specify an exact commit in the URL.)
Add the QuickSaveAuthoring component to a gameobject in a SubScene and click the 'Create QuickSave Settings'.
If the Initial Setup was followed there will now be 2 assets in the 'Assets/QuickSave/Resources/QuickSave' folder.
On the QuickSaveSettingsAsset you will define every ECS component that you might want to save & load.
For BufferElementData you'll also have to define the max amount of elements that can be saved.
On the QuickSaveArchetypeCollection asset you can optionally define named combinations of types.
These definitions are useful to reduce authoring work, add consistency and make later modifications easier.
QuickSave also tracks if the component is enabled or not (see IEnableableComponent).
For IComponentData it tracks whether the component is on the entity or not (especially useful for TagComponents).
For IBufferElementData there's no tracking for the component being added or not, BUT it tracks the amount of entries and their data. You'll have to empty you buffers instead of removing them!
The reason for this is performance related.
There are restrictions to what can get saved. ComponentData & BufferElementData are supported as long as they don't container pointers, blobassetreferences or references to other entities. The restrictions are there because it doesn't make sense to persist any of these things in their raw form. If for example your pointer field is part of the state of your entity, it's up to the user to quicksave some kind of serializable field like a GUID and quicksave that instead. The user can then make a system that automatically fixes up the pointer based on whatever the GUID is.
With QuickSave you can decide per Authoring Gameobject (and thus per Entity) what state gets saved specifically.
This doesn't mean that there should be lots of authoring work though.
The authoring component QuickSaveAuthoring can get added to Prefabs & multi-object editing is fully supported.
QuickSaveAuthoring should get added to any authoring gameobject for which their resulting Entity you want to save & load their state. The options in the inspector are what you defined in the previous step 'Defining what can get saved'. You can select one of the presets you made (Preset is the same as a QuickSaveArchetype). Or you can make a custom combination of types directly on the component.
To make this first test simple I recommend using a physics object & saving at least the LocalTransform + PhysicsVelocity.
When you added a QuickSaveAuthoring component with some definition of what to save, you can close the subscene.
QuickSave has a useful utility component QuickSaveSubScene, add this to your subscene gameobject.
You can now enter playmode and use the QuickSaveSubScene inspector on the subscene to 'Reset To Initial State', you can also use it to load & unload your subscene. Resetting a SubScene to its initial state is the only feature that works out of the box with 0 coding.
In the next parts we delve into more detail on how QuickSave works and how it can be used.
The Demo Project also shows these things and how to:
- Save/Load the state of a subscene at any time.
- Save the state to a file & load it from a file.
- Create a Replay System
There's even more than that you can do, but that's up to the creativity of the developer!
Once you learn the API, there's little limits to it.
When QuickSave saves the state of your entities it copies the data to a single array per SubScene. It just looks at the SceneSection component on the entities to decide in which container the data ends up.
Per SubScene, QuickSave creates only 1 container automatically, the 'Initial Container', this is where the initial state of the subscene gets stored. This gets done by the QuickSaveSceneSystem & QuickSaveBeginFrameSystem.
A container is just an entity that stores all its data in a buffer component of type QuickSaveDataContainer.Data. It also has the QuickSaveDataContainer component with some info about the container.
You can create new containers for a subscene simply by instantiating an existing valid container entity. When a subscene is loaded the first time, QuickSave automatically creates 1 valid container with the intial state of the subscene. So to create your first own container you'll need to duplicate/instantiate that entity. The QuickSaveAPI class has some handy methods to do this, but feel free to work with the container entities directly. Getting the initial container for a subscene can be done by grabbing the QuickSaveSceneSection component on the SceneSection entity.
To apply the data from a container to the entities (or the reverse) you use the DataTransferRequest component on a container.
There are 2 default systems that will execute your DataTransferRequest: QuickSaveBeginFrameSystem & QuickSaveEndFrameSystem.
For common usage these can be enough, but if you want your requests to be executed at another time in the frame you can create your own QuickSaveSystem by simply inheriting from QuickSaveSystemBase.
You can use the Unity component RequestSceneLoaded on SceneSection entities just as you would normally. QuickSaveSceneSystem will auto-detect when scenes are loaded that use QuickSave.
QuickSave does provide 2 handy components to simplify auto-saving & auto-loading of state.
AutoApplyOnLoad & AutoPersistOnUnload.
If you decide to use AutoPersistOnUnload you will need to unload your subscene by adding the RequestSceneUnloaded component.
This is to give QuickSave time to save the state before the scene gets unloaded.
QuickSave comes with serialization support, so you can write your containers to disk. The RequestSerialization & RequestDeserialization components can be added/enabled on a quicksave container for this purpose.
If you need custom serialization you can disable the DefaultQuickSaveSerializationSystem & create your own system based on it.
QuickSaveAuthoring: The authoring component to put on gameobjects in subscenes.
QuickSaveBaker: Baker for QuickSaveAuthoring
QuickSaveBakingSystem: Finishes the baking from QuickSaveBaker.
QuickSaveDataContainer: ComponentData on container entities that describes the container.
QuickSaveDataContainer.Data: BufferData on container entities that contains all the raw container data.
QuickSaveArchetypeDataLayout: BufferData on container entities that described the data layout of the raw data.
DataTransferRequest: BufferData that can be added to a container to request a QuickSaveSystemBase to apply or save the data.
QuickSaveAPI.IsInitialContainer: Utility function to check whether the container is the auto-created initial container for a subscene.
QuickSaveAPI.InstantiateContainer: Utility function to duplicate a container.
QuickSaveSystemBase: Abstract class to inherit from when in need of a custom QuickSaveSystem.
QuickSaveSceneSystem: System that detects subscene loads, creates the initial container & does other crucial work on subscene load.
QuickSaveSceneSection : ComponentData on SceneSections that holds a reference to the initial container entity.
QuickSaveArchetypeIndexInContainer: ComponentData on user entities that holds a primary index into the containerdata array.
LocalIndexInContainer: ComponentData on user entities that holds a secondary index into the containerdata array.
QuickSaveMetaData: Small struct that lives in front of every piece of data in the containerdata array.
QuickSaveSettings: Static runtime equivalent to the QuickSaveSettingsAsset.
QuickSaveSettingsAsset: Asset which contains the user defined types & some options.
QuickSaveArchetypeCollection: Asset which contains the user defined type combination presets.