This document is about: QUANTUM 2
SWITCH TO

Dynamic Asset Injection

Level 4
Available in the Gaming Circle and Industries Circle
Circle

Overview

The Asset Injection addon is a set of utilities built on top of the Quantum SDK allowing to deterministically add assets (Map, EntityPrototype, ...) to Quantum's dynamic database during simulation.

The Asset Injection addon is a regular project, including an reference implementation. The utility scripts can be used in any project using Quantum 2.1 or up.

Asset injection should only be used for small assets, using it for large files as map or navmesh will create a heavy toll on realtime communication and snapshot synchronization. It is recommended to replace these assets before starting the Quantum simulation.

Note:

  • Assets injected into the database can be created at runtime (for example a Map created by a player).
  • The dynamic database is part of the game state and will be transferred to late-joiners as part of the snapshot; thus there is no need for additional synchronization code for late joiners.

Download

Version Release Date Download
2.1.0 May 11, 2023 Quantum asset-injection 2.1.0 Build 196

Quantum

The Quantum-side of the addon handles the compression of the asset, the asset injection command definition as well as the system receiving and injecting the asset into the dynamic database.

Compression

Quantum's built-in compression utility is used for compression of injected data to reduce the amount of data sent via commands. This is done automatically.

InjectAssetCommand

The InjectAssetCommand is used to deterministically share data with other players. A single command can hold up to 4 kB of data. If the data exceeds this limit, the asset is automatically split into multiple smaller chunks and sent in several commands. Commands are attached to the a particular by the server, which is why only one command can be received per simulation frame. This will result in a delay as the simulation needs to wait for an amount of ticks equal to the amount of parts the command has been split into.

InjectionSystem

The InjectAssetSystem handles InjectAssetCommands and injects the asset into Quantum's dynamic database. If an asset was sent via multiple commands, the InjectAssetSystem stores the data chunks from each partial commands. Once all parts have been received, the asset is reassembled and injected into the database.

Unity

The Unity-side of the project shows how to send Commands.

Sending assets via commands

The AssetInjectionUtility is used to send any type of Quantum asset that is meant to be injected into the simulation's dynamic database. Simply call the InjectAsset() method with the required parameters and the AssetInjectionUtility will take care of the rest - including splitting large data into multiple commands if necessary.

C#

    public static void InjectAsset(QuantumGame game, PlayerRef player, string assetName, byte[] data);

Special Assets

Two common special assets used when working with Quantum are Map and Entity Prototypes assets. To facilitate the serialization and deserialization of these types of assets two additional utilities have been provided:

  • MapUtlity can be used for creating Unity assets from Simulation assets.
  • PrototypeUtility can be used for serialization/deserialization of entity prototypes.

These utilities can be used for example to handle entity prototypes created as user generated content.

Who is allowed to inject assets?

In general anyone can send a InjectAssetCommand to inject any sort of asset into the database. In the example provided in the addon package, anyone can inject a map asset, but only one specific player can activate the new map.

If injecting or manipulation of the injected assets should be somehow restricted, the players allowed to do so have to be deterministically identified as such in the simulation. For instance, a flag could be set in each player's RuntimePlayer to specify whether they are allowed to inject and / or manipulate assets in the dynamic database.

Injecting Assets deterministically generated Assets

In case of deterministically created assets, such as a map deterministically generated from a seed inside of Quantum, it is possible to inject the asset into DB directly from within simulation without sending it via commands.

Known Limitations

If the asset contains a reference to another asset (which is not already in the DB) the referenced asset has to be injected as well; depending on the use-case, the referenced asset has to be injected before the asset referencing it.

Back to top