Content Management

This page is guaranteed to be spoiler free. It is safe for you to read this page even if you have not completed playing The Ur-Quan Masters. Links you follow from this page do not share this guarantee unless they also include this text.

Introduction

The game still uses a virtual file system as before: see Content Management for information on this. However, starting in 0.6.4, the "layering" effect of the directory system is no longer used to index files for the purposes of regular addons. The concept of addon shadow packages was introduced in 0.6.6 as a stop-gap since the resource system is not yet finished.

Hey, my remixes don't work!

UQM 0.6.4 (SVN revision 2869) changed addon pack mechanics incompatibly. Your remix zips are still OK, but you will need to perform these steps:

• Move the addons directory from content/packages to content/
• Download the appropriate .rmp files from http://sc2.sourceforge.net/remix-rmp/ and put them in the same directory as the remix zips.
• Ensure that the remix directory is, in fact, addons/remix.

Detailed description

Still needs to be done.

A typical layout

On Windows

A typical The Ur-Quan Masters installation on Windows looks like this:

C:\Program Files\The Ur-Quan Masters\uqm.exe
C:\Program Files\The Ur-Quan Masters\content\packages\uqm-0.7.0-content.uqm
C:\Program Files\The Ur-Quan Masters\content\addons\uqm-0.7.0-3domusic.uqm
C:\Program Files\The Ur-Quan Masters\content\addons\uqm-0.7.0-voice.uqm
C:\Program Files\The Ur-Quan Masters\content\addons\uqm-remix-disc1.uqm
C:\Program Files\The Ur-Quan Masters\content\addons\uqm-remix-disc2.uqm
C:\Program Files\The Ur-Quan Masters\content\addons\uqm-remix-disc3.uqm
C:\Program Files\The Ur-Quan Masters\content\version

On Mac OS X

A typical The Ur-Quan Masters installation on Mac OS X looks like this:

/Applications/The Ur-Quan Masters/Contents/PkgInfo
/Applications/The Ur-Quan Masters/Contents/Info.plist
/Applications/The Ur-Quan Masters/Contents/Frameworks/Ogg.framework
/Applications/The Ur-Quan Masters/Contents/Frameworks/SDL_image.framework
/Applications/The Ur-Quan Masters/Contents/Frameworks/SDL.framework
/Applications/The Ur-Quan Masters/Contents/Frameworks/Vorbis.framework
/Applications/The Ur-Quan Masters/Contents/MacOS/The Ur-Quan Masters
/Applications/The Ur-Quan Masters/Contents/Resources/The Ur-Quan Masters.icns
/Applications/The Ur-Quan Masters/Contents/Resources/content/version
/Applications/The Ur-Quan Masters/Contents/Resources/content/packages/uqm-0.7.0-content.uqm
/Applications/The Ur-Quan Masters/Contents/Resources/content/addons/uqm-0.7.0-voice.uqm
/Applications/The Ur-Quan Masters/Contents/Resources/content/addons/uqm-remix-disc1.uqm
/Applications/The Ur-Quan Masters/Contents/Resources/content/addons/uqm-remix-disc2.uqm
/Applications/The Ur-Quan Masters/Contents/Resources/content/addons/uqm-remix-disc3.uqm

On Linux

A typical The Ur-Quan Masters installation on Linux looks like this:

/usr/local/bin/uqm        (wrapper script)
/usr/local/lib/uqm/uqm    (the actual executable)
/usr/local/share/uqm/content/packages/uqm-0.7.0-content.uqm
/usr/local/share/uqm/content/addons/uqm-0.7.0-3domusic.uqm
/usr/local/share/uqm/content/addons/uqm-0.7.0-voice.uqm
/usr/local/share/uqm/content/addons/uqm-remix-disc1.uqm
/usr/local/share/uqm/content/addons/uqm-remix-disc2.uqm
/usr/local/share/uqm/content/addons/uqm-remix-disc3.uqm
/usr/local/share/uqm/content/version

Content directories

The following list shows which directories are mounted in the game in 0.7. The later mentioned ones are mounted on top of the earlier mentioned ones.

Directory	Mounted on	flags
default packages, in alphabetic order	/	read-only
add-on packages, in alphabetic order	/addons/[name]	read-only
content base directory	/	read-only
add-on shadow packages, in specified order	/	read-only
user data directory	/	read-write
temporary directory	/tmp	read-write

Note that addon packages are now mounted in their own tree branches, with one exception. The only way to override (or shadow) the content is with an add-on shadow package. This is necessary in cases like extending fonts or supplying different menu keys because the resource system is not yet finished.

Add-on layout

This is better illustrated with an example:

addons/russian-trans-2.0.zip

Where russian-trans-2.0.zip contains:

lang-russian/russian.rmp
lang-russian/uqmpack.nfo
lang-russian/shadow-content/russian-shadow.zip (see notes below)
lang-russian/comm/commander.txt
lang-russian/comm/arilou.txt
[etc., files with layout of author's choosing, all under lang-russian/ ]

and is mounted like so:

/addons/lang-russian/russian.rmp
/addons/lang-russian/uqmpack.nfo
/addons/lang-russian/comm/commander.txt
/addons/lang-russian/comm/arilou.txt
[etc.]

And russian-shadow.zip contains:

base/fonts/micro.fon/
base/fonts/player.fon/
[etc.]

and is mounted like so:

/base/fonts/micro.fon/
/base/fonts/player.fon/
[etc.]

A shadow content zip works like the add-ons worked in the prior versions: the file structure must match the default content layout, and the files in the zip will shadow (or override) the default content.

russian.rmp contains:

comm.arilou.dialogue = CONVERSATION:addons/lang-russian/comm/arilou.txt:addons/3dovoice/arilou/:addons/3dovoice/arilou/arilou.ts 
comm.commander.dialogue = CONVERSATION:addons/lang-russian/comm/commander.txt:addons/3dovoice/commander/:addons/3dovoice/commander/commander.ts 
[etc., resource identifiers of author's choosing; see content/uqm.rmp for resource strings]

An add-on must contain at least one .rmp file or it will not be loaded. Note that CONVERSATION resource type has three parts: the subtitles file, the voice ogg directory, and the timestamps file. If the last two are omitted, the voices will not play when this add-on is loaded. See the 3domusic and 3dovoice standard add-on for more examples. You may add completely new resource identifiers if you plan to add brand new content in your mod.

uqmpack.nfo contains:

name=Russian Pack
author=John Doe
version=2
description=Russian translation of the game.
year=2011
min_uqm_version=0.7

While uqmpack.nfo file is not currently required in the add-on, we ask that you add one for the future online add-on management. This will make your add-on more user-friendly.

Shadow content

Shadow content works like the add-ons worked in the prior versions: the file structure must match the default content layout, and the files will shadow (or override) the default content.

Currently, add-on shadow-content directory must contain .zip (or .uqm) files. Only zipped files will be mounted under the root directory. This means that in order to create a single zipped add-on file with shadow content, you have to put a zip inside a zip. In that case, it may be a good idea to zip the shadow content with method store (no compression) in order to improve the in-game performance. Please note that we intend to remove this limitation in v0.7.1. We hope to release the 0.7.1 with bugfixes as quickly as we possible, so modders may want to wait for it.

Current Development Status

The resource system (and thus the content directory) are in flux as the development team works on implementing a new resource system. This should remove a lot of the more brittle components from the legacy system and make addons easier to add, and mods to the source easier to make work. Detailed goals, milestones, and comments are in this section.

Top-Level Roadmap

This actually may migrate over time as we see what works and what doesn't, but it will at least mark where we've been and where we think we're going.

1. Implement a generic string-based key-to-value system for doing resource lookups. Completed in Revision 1916.
2. Drop requirement on binary resource indices by translating them to text. Completed in Revision 2003.
3. Replace the integer-based resource system with string-based key mappings that are easier to extend. Completed in Revision 2963.
4. Rework resource types to allow for a wider range of resources. Migrate all 3DO content into standalone addon packs. Completed in Revision 3104.
5. Uniform API for all uses of the resource-map system, merging about six redundant subsystems into one. In progress.

Current goals

It's now feasible to start moving hardcoded data like the starship constants and the starmap itself into .rmp files. It's not clear how much of this is wise for 0.7.0 itself, but we should probably do at least a little to gather interest.

• Keep user settings in a resource-map. Completed in Revision 1916.
• Keep key configuration in a resource-map. Completed in Revision 2705.
• Allow loads of resource files to be placed into isolated submaps to keep values separated. Completed in Revision 3105.
• Allow saves to strip some or all of the common prefix to save only the "submap" component. Completed in Revision 3105.
• Merge user settings and key configuration into the main resource map, eliminating the now-redundant mapres.c routines. Completed in Revision 3108.
• Turn melee data (teams, current situation) into resource maps like the other two.

Other work

This is a bit more nebulous since we haven't advanced far enough to see what's a good idea and what isn't.

• Massive, cathartic violence against the content directory structure, ending in convenient subprojects. Incomplete, but started in revision 2870.
• Let .rmp files include other ones to make uqm.rmp less monolithic. This could also be used to automatically include addon packs (such as, say, a Cyrillic Font Pack) if necessary.
  • At the moment we just load all .rmp files in any given directory. This may be good enough.
• The hack to make the remix packs work is kind of ugly. A more permanent fix would allow special variable expansion to map to wherever uio elected to put it, giving each extension its own space for files. Best of all would be a magic variable for "The home of the extension named X." Implementing this would give us full namespaces and namespace imports.
  • It's only ugly under the surface, though, and will only affect mod writers, and that rather minimally. The users just shove packages blindly into content/addons.
• Online configuration of which extensions to use.
• It would be nice to have an offline application for building extensions.
• A more "self-aware" resource system should give us a much better handle on the remaining resource-related bugs.
• Can we leverage this for improving save game formats?
• Planet data is aliased in #defines and structure initializers when it should probably be in the resource map.
• Ship data is *not* aliased, requiring a bunch of structure initializers that probably (though less probably than in the planet data case) should be name normalized.