Content Management

From Ultronomicon
Revision as of 01:32, 4 February 2008 by Mcmartin (talk | contribs) (→‎A typical layout: -- added Windows and Mac layouts)
Jump to navigation Jump to search

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.


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.

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 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.6.0-content.uqm
C:\Program Files\The Ur-Quan Masters\content\packages\uqm-0.6.0-3domusic.uqm
C:\Program Files\The Ur-Quan Masters\content\packages\uqm-0.6.0-voice.uqm
C:\Program Files\The Ur-Quan Masters\content\addons\remix\
C:\Program Files\The Ur-Quan Masters\content\addons\remix\
C:\Program Files\The Ur-Quan Masters\content\addons\remix\
C:\Program Files\The Ur-Quan Masters\content\addons\remix\remix1.rmp
C:\Program Files\The Ur-Quan Masters\content\addons\remix\remix2.rmp
C:\Program Files\The Ur-Quan Masters\content\addons\remix\remix3.rmp
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.6.0-content.uqm
/Applications/The Ur-Quan Masters/Contents/Resources/content/packages/uqm-0.6.0-voice.uqm
/Applications/The Ur-Quan Masters/Contents/Resources/content/addons/remix/
/Applications/The Ur-Quan Masters/Contents/Resources/content/addons/remix/
/Applications/The Ur-Quan Masters/Contents/Resources/content/addons/remix/
/Applications/The Ur-Quan Masters/Contents/Resources/content/addons/remix/remix1.rmp
/Applications/The Ur-Quan Masters/Contents/Resources/content/addons/remix/remix2.rmp
/Applications/The Ur-Quan Masters/Contents/Resources/content/addons/remix/remix3.rmp

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)

Current Development Status

The resource system (and thus the content directory) are in flux as the development team works on implemented 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. Keep user settings in the resource-map system. Completed in revision 1916.
  3. Drop requirement on binary resource indices by translating them to text. Completed in Revision 2003.
  4. Unify key configuration into the resource-map. Completed in revision 2705.
  5. Unify Melee configuration into the resource-map.
  6. Unify file-loading with the resource-map system. In progress.
  7. Uniform API for all uses of the resource-map system, merging about six redundant subsystems into one. Previous steps require partial progress, but not currently an explicit target.

Current goals

The immediate goal is to shift away from .lst files (themselves text translations of the old binary .ndx files) to a string-based key-mapping system.

  • Instead of pointing from resource numbers to files, point them to string IDs that the resource map will forward to files. Completed in Revision 2868.
  • Have addon packs modify the resource map, not the underlying file system. Completed in Revision 2871.
  • Self-contained addon packs that own their own directory names. Completed in Revision 2871.
  • Remixes selectable from the Setup Menu, even if general Resource Management UIs don't work. Completed in Revision 2873.
  • Efficiency concerns indicate resmap.c should be using hashtables, not an association list. Completed in Revision 2875.
  • Types of resources should be functions of the resource, not the name. SvdB suggests making the values be something like STRING:starcon.txt. This is probably the Right Thing, but it's not what the integer-based ID system does. This could make life interesting. Completed in Revision 2909, with both systems currently active in parallel for cross-checking.
  • Resource names need to be modified so that resources in the same package have identical prefixes. Abandoned: Replaced with...
  • Resource names for constructed resources -- primarily planet graphics, life forms, and the initial selection of starships -- need to be reorganized so that the resource strings are easy to construct.
  • Switch from 32-bit integers indexed via .ls2 files into direct indices into the .rmp files. A lot of things have to change all at once to do this:
    • RESOURCE changes from DWORD to const char *.
    • Calls to MAKE_RESOURCE need to be modified to work with string resources.
  • It really looks like the RES_INDEX type can actually be safely retired -- there is exactly one point in the entire codebase where the same resource number is intended for use in multiple indices, and it's part of the blank CODE resource.
  • We lack types/handlers for presentations, voice clips, and timestamps. This should change. The easiest way to handle voice clips and timestamps is to have multiple values for the comm resource; something like CONVERSATION:comm/arilou/arilou.txt:addons/voice/arilou:addons/voice/arilou/arilou.ts.
  • Uniform APIs require uniform reference. This is actually part of a different step, but part of it turned out to be necessary for sensibly dropping the indices.
    • Uniform reference to file-type resources. Completed in Revision 2903. This also let us actually start using malloc and free for our memory management directly.
    • Uniform reference between file-type and value-type resources.

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.
    • Note that an SVN update following an SVN move will redownload all content, so we should be very sure about where we're moving the voice packs before actually performing the move.
    • Doing this right really requires at least resource support for voice clips and timestamps. Rehardcoding voice data locations might work as a stopgap.
    • We will require a new option (and new automatic defaults) for automatically detecting the content directory and mounting the addons directory from a separate location (So that one could individually SVN-checkout just source, just source+base content, or everything.)
  • 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.
  • 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.
  • RES_INDEX resources are basically redundant in the new system, but there's no reason they couldn't become const char *s as well. These would go to a new SetResourcePrefix command that replaces SetResourceIndex. Then each ship can load on its own, and can also load ship-specific resources like zapsat.large. Resource saving actually already works like this (you provide a prefix that specifies the root of the key-tree to save); we should extend loading to do the same.
  • 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.