Setting Up an Asset Repository
From Multiverse
| Asset Management |
|
Overview and Setup • Download an Asset Repository • Using Asset Importer • Using Asset Packager • Team Development |
| Reference |
|
Anatomy of a Repository • Asset Definition Files • Asset List Files |
Contents |
What is an asset repository?
An asset repository is a directory containing all the media assets for a world, including 3D model mesh files, textures, particle and shader scripts, UI files, Client Python scripts, fonts, icons, sounds, and so on. A world's asset repository contains all the media and scripts that the Multiverse Client uses at run-time.
An asset repository is a single directory that contains:
- An
AssetDefinitionsdirectory, containing an asset definition file for each asset in the repository. See below for an introduction to asset definition files. - A set of sub-directories containing the media assets referenced by the asset definition files. Each type of asset goes in a separate directory; for example, meshes go in the
Meshes. For a complete list of directories, see Asset Definition Files. - A manifest file,
mv.patch. The Multiverse client uses the manifest file to determine which assets it needs to download each time it connects to the world. See Creating a manifest file.
For more information, see Anatomy of an Asset Repository.
Prebuilt asset repositories
Multiverse provides three prebuilt asset repositories that you can use as starting points for your asset repository:
- Sampleworld asset repository contains all the assets required by Sampleworld. Generally, most developers should download and start with this asset repository.
- World Editor asset repository contains all the assets required by the Multiverse tools. It is the bare minimum that you need to be able to create and work with a world file; but it doesn't contain any UI code or scripts, so is not suitable for runtime use by the Client.
- Fantasy world asset repository contains all the assets and scripts required by Demo Fantasy World.
For more information and download locations, see Download an Asset Repository.
Asset definition files
Media assets typically require a specific set of files to work properly. For example, a Multivese model is defined by a mesh file, but the mesh file references a material file, and may also reference other files such as a physics file and a skeleton file. The material file in turn may reference texture files and shader scripts. If all the required files are not available, then the model will not appear or function properly.
Also, certain files may be referenced by multiple files; for example, a rock texture might be used by a house mesh and a wall mesh. Likewise, a material may be used by many meshes.
The Multiverse asset definition file encapsulates all the dependencies for an asset, so you can create and modify game assets easily. Each game asset has a corresponding asset definition file (with .asset filename extension) that specifies the files that the asset requires, and contains other information used by Multiverse tools, such as the type and description of the asset. Use the Multivese Asset Importer tool to create and modify asset definition files; for more information, see Using Asset Importer.
For detailed information on asset definition files, see Asset Definition Files.
Asset repository restrictions
Each asset repository has a fixed set of sub-directories, each of which is intended to contain assets of a particular type.
The Multiverse Client will read all assets from any of these directories, with the following restrictions:
- Python scripts must be in
/Scripts. - Shader programs must be in
/GpuPrograms. - UI files and event handler scripts must be in
/Interface/FrameXML. - Imagesets must be in
/Interface/Imagesets.
Otherwise, asset files can go anywhere. However, the the Client will not load assets from:
- Nonstandard asset repository sub-directories, in other words, sub-directories other than
/Font,/GPuPrograms,/Icons, and so on. - New subdirectories of the asset repository sub-directories. For example, the Client won't read files from a
/Meshes/MyMeshsubdirectory.
See Asset Definition Files for more information.
Designating an asset repository
Both the Multiverse tools and the Multiverse Client require you to designate at least one valid asset repository. Both tools and Client can have multiple asset repositories.
For both tools and the Multiverse Client, you may designate more than one asset repository. When you do this, the asset repositories have a strict order, and the tool or Client checks for an asset in each repository in turn, starting with the first specified asset repository, then the second, and so on.
NOTE: When you are first getting started, it is best to use one of the prebuilt asset repositories (generally, Sampleworld) before trying to create your own asset repository.
Designating an asset repository for the Multiverse tools
When you first run one of the Multiverse tools, it will prompt you to specify an asset repository. All the Multiverse tools will then use this asset repository, until you designate a different one. Later, you can change it by choosing File | Designate Asset Repository.
The tools store the location of the asset repository in the Windows registry key HKEY_CURRENT_USER\Software\Multiverse\AssetRepository\RepositoryDirectory.
Designating an asset repository for the Multiverse Client
There are several ways to designate an asset repository for the Multiverse Client.
Connecting to a local server
When you are running the client on the same machine as the tools and the server, desginate the the asset repository with a command line option and use the --world localhost option to connect to the local server.
NOTE: The --world localhost option will only work if the machine is online. To work offline (not connected to the internet), you must use a world settings file instead.
The simplest way is to run the client with the --development command-line option. This option makes the client use the default tools asset repository previously designated as described above. Only use this option when you are running the tools and client on the same system.
Thus, the full command to run a development client is:
MultiverseClient.exe --development --world localhost
More advanced developers may want to specify both a source asset repository and a local asset repository. The client downloads new and updated assets from the source asset repository before it logs in to a world; it saves the assets in the local asset repository for its use at runtime. The source location may be a network URL or a local directory, but the local asset repository is always a local directory. The --repository_path command line option specifies location of the local asset repository. The default is client-home\Worlds\worldname, where worldname is the world to which the client is connecting.
For more information on client command-line options, see Running the Client from the Command-Line.
Connecting to a remote server
When you are ready to create and use your own assets, then you must register your world with the Multiverse network, then use the --world worldname client command line option to specify your world. The client will then download assets from the asset repository specified in the world's registration with the Multiverse Network database.
By default the client first connects to the Multiverse master server; then the user logs in and chooses a gameworld, and the master server returns the URLs for the world server and corresponding asset repository. In this case, you must set up a network asset repository accessible through a web server.
For more information on the client connection process, see How a Client Connects to a World.
Setting up an asset repository
There are two types of asset repositories. A local asset repository that will be used by only the local Client and tools, and a network asset repository that multiple remote Clients can use.
Setting up a local asset repository
A local asset repository is simply an asset repository that exists on the same machine as the Multiverse Client (or tools) that will use it. A local asset repository is only for development and testing, not production use. To set up a local asset repository either:
- Download and extract one of the prebuilt asset repositories on the Client machine.
- Create your own asset repository on the Client machine, as described in Creating your own asset repository.
Then, follow the instructions above to designate the local asset repository for the tools and Client.
Setting up a network asset repository
Once you have set up a local asset repository, the next step is to set up a network asset repository that remote developers (and ultimately, users/players) can access. Follow these steps:
- Install a web server, for example Apache. You can install the web server on the same system as your Multiverse server, or a different system.
- Create a directory accessible to the webserver that will contain your asset directory.
- Copy the contents of the local asset repository directory to the web server.
- To make a client download assets from this location, do one of the following:
- Recommended: Edit the world registration in the Multiverse Network master server and set the Media URL to the asset repository URL; all Clients that access the world with the --world command line option will then automatically download assets from the specififed URL. See Registering a World with the Multiverse Network for details.
- Alternatively, edit the client's world settings file and set the
<update_url>tag to refer to the URL, for example
-
<update_url href="http://update.yourdomain.com/yourworld/"/> - In general, this technique is not recommended, because it is more error-prone than simply specifying the world name on the command line.
-
IMPORTANT: When you add new assets to your asset repository, you must recreate the manifest file as described in the following section for the Client to download the new assets.
Using HTTP Compression
The Multiverse Client supports HTTP compression to speed downloading world assets. When enabled, the server compresses data before sending to the Client. This may result in download speeds up to three times faster than without compression. You must configure your asset repository web server for HTTP compression. The specific configuration change varies depending on the web server you are using.
For Apache, add a clause in the httpd.conf to enable compression. For example:
<Location /world_assets/>
# Insert filter
SetOutputFilter DEFLATE
# Netscape 4.x has some problems...
BrowserMatch ^Mozilla/4 gzip-only-text/html
# Netscape 4.06-4.08 have some more problems
BrowserMatch ^Mozilla/4\.0[678] no-gzip
# MSIE masquerades as Netscape, but it is fine
# BrowserMatch \bMSIE !no-gzip !gzip-only-text/html
# NOTE: Due to a bug in mod_setenvif up to Apache 2.0.48
# the above regex won't work. You can use the following
# workaround to get the desired effect:
BrowserMatch \bMSI[E] !no-gzip !gzip-only-text/html
# Don't compress images
SetEnvIfNoCase Request_URI \
\.(?:gif|jpe?g|png|mpe?g)$ no-gzip dont-vary
# Make sure proxies don't deliver the wrong content
Header append Vary User-Agent env=!dont-vary
</Location>
Note: For the above to work, you must remove the pound sign (#) from the following two lines of the httpd.conf: #LoadModule headers_module modules/mod_headers.so
#LoadModule deflate_module modules/mod_deflate.soAdditionally, more information about the <Location> tag is available in the online Apache manual.
For Internet Information Server (IIS), Microsoft has instructions for enabling HTTP compresssion.
Creating your own asset repository
Once you have gotten proficient working with the prebuilt asset repositories, you can create your own asset repository for your gameworld. To create your own asset repository:
- Create an empty asset repository with Asset Packager.
- Import your models into the asset repository with Asset Importer.
- Create your world file with World Editor. When you save the file, World Editor will also save a world assets file that lists all the assets
- Create one or more asset list files that list additional assets your world requires.
- Using Asset Packager, create an asset repository containing all these assets.
- Create a manifest file for your asset repository, as described below.
Depending on your development process, you may use slightly different techniques, for example merging asset repositories created by several different model creators.
Creating a manifest file
The manifest file, mv.patch, describes all assets the client must have before entering the world. The client keeps a local copy of the manifest to determine which assets it needs to download when it enters a world.
To create the manifest file, run the Python script build_manifest.py that reads the layout of your asset files and directories to create the mv.patch file.
If you are using Linux or Cygwin on Windows, make sure the Python package is installed. If you are using Windows without Cygwin, you must download and install Python. Add the installation directory to your PATH environment variable. For information on how to set environment variables, see Setting Environment Variables.
Then create the manifest file by running the manifest build script, build_manifest.py provided in the Multiverse server /bin directory.
This script does not depend on any other scripts or executables, so you can copy it and run it anywhere.
Run the manifest build script as follows:
build_manifest.py RepositoryDir
where RepositoryDir is the Cygwin/Unix path to the asset repository. For example, if your asset repository is in c:\multiverse\Asset Repository then the path would be /cygdrive/c/multiverse/Asset Repository.
On Windows without Cygwin, run the manifest build script as follows:
C:\PythonInstalDir>python.exe build_manifest.py C:/RepositoryDir
Note the direction of the slashes. Do not use a repository directory path containing spaces.
The manifest build script creates an mv.patch file at the top level of your repository. The client downloads this file when it first connects to a world, and compares it to its local manifest file(mv.patch.cur), if it has one. Then, based on the differences, it downloads additional assets.
mv.patch.cur must match what is in the Client world folder. Any differences may cause an error when the Client attempts to patch.Note: the above described behavior should be revised on the back end so that when the patcher launches, it first makes sure that the mv.patch.cur matches the client world folder. If it doesn't, then it updates (adds/removes) based on it and THEN updates new data from there server as it does now.
