Navigation
Community
Configuring
Creating
FAQ - General
Info for Sauerbraten Users
Introduction
Known Issues
Main Page
Notes
Playing
Troubleshooting
 

Assets

Assets are files, or bundles of files, that contain game-related content and are downloaded automatically. For example, a map asset contains a map geometry file, map script, and other files needed for running a map; a character model asset would contain the mesh, textures, animations, and so forth.

Creating Assets

To create a new asset, go to the 'Assets' tab on the website and either select 'Create new asset', or click on an existing asset and clone it. Cloning creates a copy of the asset which you can then modify, without changing the original.

Asset Locations

Every asset has a location, which is shown (and you can edit) when you view an asset on the website. The location is the path to where the asset will be downloaded to, relative to /packages/ under the home directory. So if you run the client with home directory local/client, a path of textures/stone.jpg would make the file be downloaded to local/client/packages/textures/stone.jpg.

An asset can also be a bundle of files - an archive asset. Assets whose location ends in .tar.gz are archive assets, and they will therefore be automatically unpacked when downloaded, into a directory of the same name (but without .tar.gz). For example, a map asset with location base/mymap.tar.gz would be unpacked into base/mymap/ (as a map asset, it would have files like map.js, map.ogz, etc. - see
Creating a New Map).
  • Important: Archive assets need their files to be files in the root directory of the archive. That is, the archive should simply contain the files, instead of the archive containing a directory which contains the files.

In general you can pick any location for your assets. Some kinds of content need specific types of paths, however:
  • Map assets must be under base/
  • 3D Models must be under models/
  • Sounds must be under sounds/
In general, for all assets it's a good idea to pick clear and consistent locations. See the existing assets for examples.

Uploading Assets

After you create an asset, you can upload content for it. Select the asset on the main website, and click 'Upload content'. If the asset is a archive, upload the .tar.gz file.

If you created the asset by cloning an existing asset, it will already contain content - a copy of the content of the original asset that you cloned. You can upload new content to replace that content (the original asset that you cloned will not be affected).

Map assets can also be uploaded from within the client program. When you select 'Upload map...' in the client (when running a map), it packages the map files into an archive - the map asset - and uploads that. (You can also do so manually, that is, create a .tar.gz archive yourself with the appropriate files and upload it on the website.)

You can also upload archive assets in the client program with the cubescript comment /upload_asset PATH.tar.gz, for example /upload_asset textures/my_pack.tar.gz will upload the asset textures/my_pack.tar.gz. The asset will be packaged (the files in its directory will be prepared in an archive), and uploaded. Note that this method of uploading assets only works for assets the client program is 'familiar' with, and accordingly the uploading is done from the directory of the asset - so this only makes sense if the asset has been downloaded in the past. You must also be logged in to the master to do an upload in this way, as otherwise you have not proven your identity to the master server (but you don't need to be connected to a server instance running a map).

Note that when you let the client program package an archive for you (when doing 'Upload map...' or /upload_asset), it will include all files in the directory, except for backups files (with extension BAK or ~). So if you have a texture package that includes JP2 files from which PNGs are generated, the PNGs will be included, which probably isn't what you want. In that case, either 'clean' the directory before uploading from the client program, or create the archive yourself manually..

Asset Downloading

Assets are downloaded in the following manner:
  • Every activity (like a game) has a 'map asset' - the asset which is the map for that activity, see Creating a New Map. When you play that activity, the asset is downloaded.
  • Every asset - including map assets - can have dependencies. Dependencies are assets that will be downloaded with an asset. For example, if your activity uses a custom character model, make the map asset have that character model as a dependency.
  • Dependencies are processed recursively, that is, if a dependency itself has dependencies, they will also be downloaded. So, to continue the previous example, if your custom character model has a dependency on a model for a gun, then when the map is played the map asset, character model and gun model will all be downloaded.
The latest version of an asset is always downloaded: If the existing version is not up to date, the newer one will be downloaded instead. If the existing version is up to date, it will not be downloaded twice. Note that what is actually checked is whether the version you have matches the version the main website believes is the latest. So, if you change a file but don't upload it, and you then run a map that uses that asset, the client program will decide that your version doesn't match what the main website believes is the latest version - and it will download that (older) version, overwriting yours.

Checking if an asset is the latest version is done using a hash - a 'signature' of the file. In general you don't need to understand how this works, but for archive assets there are some special rules:
  • For archive assets, the signature is of the .tar.gz file, not the unpacked directory and files. This makes sense in that the archive is the actual asset, and the unpacked files are just for convenience.
  • This means that if you change the unpacked files, the asset system will not decide that the asset you have is different from the latest version on the main website. The asset system only notices changes to the asset file itself, that is, changes to the .tar.gz file.
  • This is a feature, not a bug. For example, it is useful for the mapping process.



Updated on Oct 5, 2009 by Alon Zakai (Version 12)