Skip to content

AssetBase Guide

Jump to bottom
Peter Robinson edited this page Aug 18, 2026 · 3 revisions

Introduction

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.

TorqueScript Bindings

AssetBase

Exposed Fields

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.

AssetName (string)

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.

AssetDescription (string)

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.

AssetCategory (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.

AssetInternal (bool)

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.

AssetAutoUnload (bool)

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.

AssetPrivate (bool)

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.

Additional API

The AssetBase exposes a few additional methods that can be useful under certain circumstances.

getAssetId()

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.

Changing and saving an asset

Changing an asset changes it in memory only. The file on disk is not touched until you save it.

It works exactly like a text editor. Typing changes the document on your screen; the file on disk doesn't change until you hit Save. Assets are the same:

// Get the asset.
%asset = AssetDatabase.acquireAsset( "MyModule:playerShip" );

// Change it.  This changes it on screen and in memory.  The file is untouched.
%asset.AssetDescription = "The ship the player flies";

// NOW write it to the file.
%asset.saveAsset();

If you quit without saving, your change is gone. So whenever you change an asset from script and you want that change to stick, call saveAsset().

The engine does give you one guarantee: an asset with unsaved changes will not be quietly unloaded to save memory. It hangs on to the asset until you either save it or deliberately throw the changes away. That's true in any project, whether or not you ever open an editor.

If you happen to be editing through the Asset Manager editor — the tab in the engine's editor, which is a separate thing from the AssetManager described here — it does the saving bookkeeping for you and asks before anything is thrown away. It has no special powers to do that; it calls the same methods you're reading about.

This changed in Torque2D 4.0. Older versions wrote the file the instant you changed any field. That sounds convenient, but it meant a typo was written to disk before you noticed it, and there was no Undo. Now you decide when to save. If you're following an older tutorial that never calls saveAsset(), that's why.

The methods

saveAsset()

Writes the asset to its file. Returns true if it worked.

isAssetDirty()

Returns true if you've changed the asset since it was last saved. "Dirty" is just the usual programming word for "has unsaved changes" — nothing is actually wrong with it.

Handy for asking "should I put a * next to this name?", or for not bothering to save something nobody touched.

revertAsset()

Throws away your unsaved changes and reloads the asset from its file — an "undo everything since my last save" button.

The asset object itself is kept, so any sprite or object already using it keeps working and simply goes back to showing the saved version.

refreshAsset()

Says "I've changed this asset — everyone who's using it should take another look."

Sprites showing the asset redraw with the new version, and any asset built on top of this one (an AnimationAsset built from an ImageAsset, say) is told to catch up too.

It does not write the file. It's the "tell everybody" half; saveAsset() is the "write it down" half. You usually want both, in that order.

Most of the time you don't need to call this at all, because the asset's own set methods already do it for you.

Snapshots (advanced)

A snapshot is a copy of everything the asset is holding right now, kept to one side so you can put it back later. This is how you build an Undo feature — take a snapshot before a change, and if the user doesn't like the result, put it back.

This is what you want if you're writing an asset tool of your own. (The Asset Manager editor builds its Undo out of exactly these two methods.)

// Remember what the asset looks like right now.
%before = %asset.createStateSnapshot();

// ... let the user change whatever they like ...

// Didn't work out?  Put it back.
%asset.restoreStateSnapshot( %before );

// Snapshots are objects, and they're yours.  Delete it when you're finished.
%before.delete();

Some fine print, for when you need it:

  • createStateSnapshot() returns the snapshot object, or 0 if it couldn't take one. Taking a snapshot changes nothing about the asset — it isn't marked as changed and nobody is notified.
  • The snapshot belongs to you. Delete it when you're done or it stays in memory.
  • restoreStateSnapshot() keeps the asset object itself, so anything already using the asset keeps working.
  • Restoring does not decide whether the asset counts as changed — you do, with AssetDatabase.setAssetDirty(). Undo is the one thing that knows whether the state it just put back is the saved one.

More on all of this, including saving every changed asset at once and finding out what's unsaved across a whole project, is in the Asset Manager Guide.

Clone this wiki locally