-
Notifications
You must be signed in to change notification settings - Fork 111
AssetBase Guide
All assets are known engine types that allow instances to be created at runtime. The asset system defines a base type from which all assets are derived named "AssetBase". This type implements all the fundamental features required for the type to work with the asset system.
The AssetBase type exposes the following fields:
- AssetName
- AssetDescription
- AssetCategory
- AssetInternal
- AssetAutoUnload
- AssetPrivate (Never persisted with Taml)
In the list above, only "AssetName" is mandatory, all others are completely optional.
Here's an example of all these being used by an ImageAsset type:
<ImageAsset
AssetName="NinjaImages"
AssetDescription="Really cool Ninja enemy images."
AssetCategory="Enemy"
AssetInternal="true"
AssetAutoUnload="true"
...
/>The following is a complete description of each of these fields.
This forms the second-part of the full Asset-Id as described in the Asset Manager Guide with the first part being the Module-Id in which the asset is located.
It is a mandatory field, without it the asset will not be registered with the asset system and produce a warning when encountered.
The name can contain any character with the exception of the asset-scope token which is currently ":" but may change in the future. It is highly recommended that the name be as short as possible, with no spaces or other non-alpha-numeric characters. Try to use CamelCase, preferably upper Camel-case. Of course, you are free to use whatever standard you so choose however avoiding non-alpha-numeric characters should be seriously considered to avoid future conflicts.
Once an asset is added to the asset system, this field cannot be changed as it forms its immutable asset-Id. The asset system provides renaming capabilities for this that not only update the asset itself but also any references to the asset, fully automatically.
The name must be unique within the same module otherwise it would produce the same asset-Id. If a name conflict is encountered within the same module then a warning is issued and the asset is ignored. In this case, only the first asset that didn't conflict with other asset names in the same module will be valid.
Asset names do not have to be unique across modules however as the asset-Id starts with the unique module-Id.
This is a description of the asset itself in plain language. There are no restrictions on the contents of this field and the asset system does not use it internally. It can be used for editors and other presentation to end-users.
The default is an empty string.
This allows the asset to be categorized alongside all other assets in the system. The category can be any string with no restrictions. Whilst the asset system does not use this field actively, it does allow filtering on this field via the asset query system.
The default is an empty string.
This allows the asset to be flagged as an "internal-use" asset. Whilst the asset system does not use this field actively, it does allow filtering on this field via the asset query system.
The default is false.
This flag controls whether the asset should automatically unload or not when the asset has no references actively being used. As described in the Asset Manager Guide this can be overriden globally.
The default is true.
This is a read-only field and indicates whether the asset is currently marked as private. Private assets are discussed in the Asset Manager Guide and exist dynamically in memory only i.e. they have no asset definition file on disk or elsewhere. They are also not associated with any module.
The AssetBase exposes a few additional methods that can be useful under certain circumstances.
This method allows you to retrieve the asset-Id of an asset object instance. Most of the time you won't actually be handling an actual asset object instance but rather its asset-Id. You assign or retrieve these asset-Ids to other objects but these are just strings and not the actual assets.
There are circumstances however when you do have an asset object instance and this method allows you to retrieve its asset-Id.
This is a method that should be used with care. It is an advanced asset method used to tell the asset to take its current state in memory and update its asset definition on disk. This call is just a convenience and actually gets process by the asset system itself.
In most cases, assets automatically update their asset definition on disk whenever any of their properties change. This means that if you were to modify something such as an "[ImageAsset](https://github.com/TorqueGameEngines/Torque 2D/wiki/ImageAsset-Guide)" so that you changes the "ImageFile" it used then the asset would automatically refresh.
The refresh would also notify all assets that refer to this asset such as would be the case if this asset was referenced by an AnimationAsset.
Also, anything currently using the asset would immediately be notified that the asset has changed which would cause objects in a Scene to render the new asset etc.
Asset refreshing is a very powerful mechanism but during actual game-play, it is assumed that assets will generally be left unmodified and treated as immutable (although as this indicates, that isn't technically the case).
More details on asset refreshing and how it can be controlled can be found in the Asset Manager Guide.