I have a fascination with "dot" files. Every once in a while I look inside my home directory to see if an application I’ve run has created one of these files (or directories) and peek inside just for the fun of it. At times, it’s come in really handy to know what’s going on inside of them — there’s been plenty of times I’ve had to erase a "lock" file or clear a cache and couldn’t quite figure out how through the application itself.
So, in that spirit, I figured I would walk through how Wonderland uses its own "dot" directory — .wonderland/. The Wonderland client creates its own .wonderland/ directory in a user’s home directory. In fact, you can have it use other directories too — it’s a Java system property that controls which (wonderland.dir property, see WonderlandConfigUtil.getWonderlandDir() for more information).
Some disclaimers first: I did not author this part of the code, so my analysis below is a deconstruction of the mechanism. So if you are in the know, feel free to make corrections by posting a comment. Also, modify the .wonderland directory at your own risk! As this is not part of any official Wonderland specification, anything posted here is subject to change without notice.
But, here goes…
The .wonderland/ directory essentially contains two items: a database and cache of assets and avatar configuration information. In this blog post, I’ll describe the asset database and cache of assets and leave the avatar configuration information to Part II of this post.
Asset database and cache
Wonderland tracks each asset it has downloaded and cached using a DerbyDB database. The database itself is located in the AssetDB/ subdirectory (there is also a log file derby.log). To view the entries in the database, run ant run-dbtest. You should entries that look something like this:
[java] SkyBox/Back.png http://188.8.131.52/textures IMAGE
Each entry corresponds to a file cached within the cache/ subdirectory. The third column — the file type — is either IMAGE, FILE, or MODEL. All IMAGE files are stored within the cache/textures/ subdirectory, all FILE files are stored within the cache/files/ subdirectory, and all MODEL files are stored within the cache/models/ subdirectory.
The MODEL files are the 3D geometry files, in v0.3-v0.4, these are binary, gzipped Java 3D scene graphs. IMAGE files seem to encompass textures, the sky box, and slides for in-world presentations (which I guess can be thought of as textures), while FILE files seems to contain all of the .rtg files (for the avatars and animated cells). These asset types are not arbitrary strings: they are defined by the AssetType.java enumeration.
Each database record contains four entries: the asset file name (max length 120), the base URL (max length 120), the checksum (max length 40), and the asset type (MODEL, FILE, IMAGE; max length 10). The asset file name is the primary key in the database table, so it cannot be null, and it must be unique — it is the relative path within the resource repository (and listed in the 2nd column above). The base URL (3rd column above) gives the URL of the asset repository from which the asset was loaded. In the listing above, I’m using a remote repository; using a local repository is also possible (set wonderland.useLocalArt = true).
The asset database is represented by the AssetDB.java class. Every time the client starts (or rather when an instance of the AssetDB.java class is created, that happens in AssetManager.initialize()), it checks to see whether this database exists. If so, it opens a connection to the database, if not, it creates the database. (To check whether the database exists, it only checks whether the AssetDB/ directory exists.)
Asset Manager Use of the Asset Database and Cache
Within the Wonerland client, it is only the asset manager (AssetManager.java) that makes use of the asset database. As one might expect, before fetching a resource from a repository, Wonderland first checks whether it is in its cache by querying the database for an entry matching the resource file name. If it does not find it in its local cache, it downloads the asset (either from a remote or local repository) and writes the new file to the cache and updates the database properly. When fetching the asset from the local cache, the Wonderland client makes use of the checksum for only certain types of assets: models and files, but not for images. (Also, it seems that it is only for models that Wonderland pays attention to the "ignore_checksum" flag.)
Mucking with the Asset Database and Cache
It probably goes without saying: proceed at your own risk! But it’s probably worth it to talk about ways you can clear the cache in case something goes wrong. Certainly, deleting the entire .wonderland directory will clean out the cache, but that may also clean out other local state, such as your Avatar configuration, so it’s probably not the best way to go. Deleting the AssetDB/ directory will likely clean out the cache, since the asset manager consults it first to find cached entries. It may be in good order to also clean out the cache/ directory as well — but if an asset is not in the database, then the Wonderland client will assume it is not cache and rewrite over any existing file in the cache/ directory anyhow.
Simply deleting an entry in the cache/ subdirectory may cause problems — based upon my reading of the code, if a model fails to load from the cache/ subdirectory, then the Wonderland client re-fetches it from the repository, however, for files and images, it just seems to give up and throw an exception (but I welcome corrections here).
To be continued in Part II…