 |
Fellow adventurers! This guide is a direct upload from the original author and is no longer supported by Microsoft or Gas Powered Games. It is also not supported by the wikia's administration or members. Any errors encountered are a result of the original publication. |
Introduction[]
The "Resource System" is comprised of files that contain the code for loading all of the resources that Dungeon Siege and the tools in the Tool Kit need to operate, such as textures, models, and .gas files.
Resources can be stored as:
- Individual files on the hard drive, which we call "bits"
- In a compressed, optimized meta-file called a "tank". Tank files are similar in concept to .zip files generated by WinZip™. Modifying Dungeon Siege, which includes map creation, always involves creating at least one tank file.
What You Need For This Tutorial[]
- Dungeon Siege (of course)
- Siege Editor
- Siege Editor Manual (comes bundled with Siege Editor)
- Siege U: 100 (optional)
What This Tutorial Assumes You Have Already Learned[]
What This Tutorial Will Teach You[]
- About tanks: What are tanks? How are they made? What are they for?
- About "bits"
- Default DS tanks
- How to build and use a tank
- How to retrieve files out of tank
- Combining resources
All About Tanks[]
What are Tank Files?[]
Tank files are compressed, optimized meta-files that are used to store resources for Dungeon Siege so that they can be located and loaded more efficiently by the engine. They are similar in concept to .zip files generated by WinZip™. Modifying Dungeon Siege, which includes map creation, always involves creating at least one tank file from individual files called "bits". Tanks are analogous to Doom's™ ".WAD" files, Unreal's™ ".U" files, or Total Annihilation's™ ".HPI" files.
There is nothing particularly special about tank files. The binary data has:
- A header
- A table of what the files are inside of it
- The actual file data itself
The extension for a tank file is irrelevant, but our convention is to have .dsres files for resource files that are mounted when the game starts and .dsmap files for map files that are mounted on the fly when you choose a map. DO NOT put anything from a /world/maps directory into anything other than a .dsmap file -- it will just cause you grief. Other tanks include the .dsparty files and .dssave files, for save games.
How Tank Files Are Made[]
Tanks are made in Siege Editor using the "Save Map as .dsmap…" and "Save Folder as .dsmod…" functions. Note that the interface for making tanks in SE is a prototype and may be a bit quirky. A community tool called "Rapid Tank Creator" (available at http://www.game-editing.net/) also makes tanks; however, Rapid Tank Creator is not a Gas Powered Games tool and no GPG support is offered for it.
Important Notes:[]
- The .dsmod files are not yet supported in the game.
- When making tanks, rename to .dsres or .dsmap.
- Options that are set in the tank creation dialog in SE are preserved in subsequent tank builds, which can create unexpected results. For example, if you use "Save Map as .dsmap…" and then "Save Folder as .dsmod…", the prefix /world/maps is retained in the dialog the second time around.
What "Bits" are and how Dungeon Siege Tool Kit (DSTK) tools use them[]
"Bits" are what we call individual files that are stored on the hard drive outside of tanks (but in the same layout that the tanks have), similar to an extracted .zip file. Bits are convenient for content development because you can avoid the extra steps of building a tank and restarting the application to "see" the new resource. One of DS's main requirements was to let people develop as rapidly as possible, and one of the ways we do that is to permit dropping files right into a bits folder for immediate usage. It doesn't work with the retail game (DungeonSiege.exe), but that's what DSMod.exe is for. For fastest results, all content development should use DSMod.exe and bits overrides.
Important Notes:[]
- The retail version of DS does not use bits. DSMod.exe and the other DSTK tools support both bits and tanks.
- When bits are available and used, they will override the resources stored in tanks.
- The default bits folder is in \My Documents\Dungeon Siege\Bits. Any file placed in there will take precedence over the files of the same name and path in any tanks that the game uses.
- Most people who are going to play your mods will be using the retail EXE, therefore, you'll probably want to compile your work into tanks for distribution on to the Internet or to friends.
Default Tank Files[]
Several different tank files ship with Dungeon Siege. This section explains what they are called and what they contain.
Logic.dsres: This contains all the core logic to glue the game together. All skrits, the contentdb, the rules, the UI configuration, and anything that is not a raw resource is stored here.
Objects.dsres: This has the art resources in the game, for example object meshes, animations, and bitmaps, plus all the movies. Terrain resources are separate and are found in Terrain.dsres.
Sound.dsres: This has non-localizable sound resources, such as sound effects and music.
Terrain.dsres: This has all the art resources required for terrain, such as bitmaps, nodes, and the node index (note: the index is now obsolete as of v1.1).
Voices.dsres: Because voice samples require localization, we separated them out so the loc teams could translate all the voices easier and only have to replace one tank file. This file contains all spoken text samples.
These five files contain all the resources that are required to run DS, except for the map files.
MpWorld.dsmap: This is the multiplayer world Utraean Peninsula.
World.dsmap: This is the single player campaign Kingdom of Ehb.
The .dsmap files are swapped in and out as the system needs them. You might be wondering, "Why not mount them all simultaneously?" Well, we always try to keep memory usage at a minimum. The index required to maintain a tank file takes up space (storing all the names of those files, etc.), and only mounting the .dsmap files as needed satisfies this objective.
How to build a Tank and use it[]
Building a tank depends on what you want to accomplish. Let's use make a map first because it's the easiest thing to do.
Create a "Map" Tank[]
- All you have to do to create a map tank is use the "Save Map as .dsmap…" command to save your map to a ".dsmap" file. Pretty straightforward. The game is already configured to look in the \My Documents\Dungeon Siege\Maps folder.
- If you don't know how to create a map in Siege Editor, refer to Siege U: 100.
Build a Mod[]
Building a mod is more complicated due to the multiplayer CRC check we do. Let's say you override a file in the contentdb, and change a particular template. This will change the content in such a way that your game will not be compatible with others in multiplayer. That means that everyone will have to have the same .dsres file installed in order to play together, even if they are not playing your mod! So the solution is to do what we did on Yesterhaven (and what other games like Quake™ used to do with their mods). Take the mod and put it into its own subfolder of the Dungeon Siege directory and launch the game with a different shortcut that says where to find the mod. This removes the tank file from the general collection so that you can play the regular GPG-created .dsmap files with anyone, yet you can also run your mod by starting with that separate shortcut.
This all applies to the current engine. We hope to resolve this issue in the future, where we will permit re-mounting of tanks on the fly and dependency mappings to say that a particular map requires a particular mod, etc. So hang tight there!
Mod Recipe[]
- .dsres file containing your "bits" directory for the modifications you've made, minus the /world/maps directory within it. This means that when you make a tank of your bits directory, you need to temporarily move the /world/maps folder out.
- .dsmap file containing your map. This one is easy, just use the "Save Map as .dsmap…" function in Siege Editor.
- Shortcut or .bat file to launch DS for your mod. It should launch Dungeon Siege with a command line that has "res_paths=<modname> map_paths=!<modname>" where the .dsres and .dsmap files you created are stored in a subdirectory of Dungeon Siege with the name "modname". The res_paths command line option says "add this additional path to the set of available paths to find .dsres files in". So it will look in \Dungeon Siege\Resources as well as \Dungeon Siege\<modname>. Your .dsres file's priority will cause its files to take precedence over anything else in the system. The map_paths command line option is about the same, except that the "!" in the front means "ignore the \Dungeon Siege\Maps folder". This means that only your map will be available when you run the game. This prevents the map from being chosen by accident without having the .dsres file available (which may cause a crash depending on your mod).
Retrieve Files Out of Tanks[]
There are 2 ways to retrieve files ("bits") out of tanks:
- The best way is with Dan Strandberg's TankViewer tool, available at www.game-editing.net.
- The other option is the Siege Editor (SE). It has an extract dialog that will let you extract the contents of a tank to your hard drive. The SE dialog is simple. Just tell it what "source" tank to use and then the "destination folder" where you want the files stored. It will just extract everything it finds, replicating the tank's file structure exactly.
Note: if you want to extract all of the DS tanks to the same folder, you can run SE directly from it using just the bits.
How the Resources are combined to form The Unified File Table[]
It's pretty simple. At game startup time, the resource system goes through all the .dsres tanks it can find and then sorts them by priority (there is a flag in the tank for this that you see in that SE tank builder dialog). Tanks with the same priority will get sorted by build time.
Starting with the highest priority tank, the resource system gets file directories for each one and adds them to a single master directory of all the resources available to the game. If a resource has already been found, it is only used once. When the system is looking for a file of that name, or it is asking for all the files in that directory, it will come up with the highest priority tank's version to load in.
For example, say that tank 1 has a file jooky.gas in it, and tank 2 has one also. Whichever tank has priority will get looked at first. That version of the jooky.gas file will "win" and the second tank's version will be ignored. Modding in Dungeon Siege works by having the files in your mod override the factory versions that ship on the CD.
Bits are similar except they are stored in individual files on the hard drive. Since bits are not used in DungeonSiege.exe (the retail version), the bits folder will effectively be invisible to it. That's why it's necessary to "tank up" your bits folder for the retail game to see it.
Bits will always override tanks. If you have a file "/world/contentdb/defaults.gas" in your "bits" folder, it will always override the equivalent file stored in any tank that gets loaded.
Important: this system is completely arbitrary. There are no requirements for which files go into which tanks. I recommend putting all of your files into a single tank for your mod (and the map in a second one) but the resource system doesn't really care if you put sounds into a file called bitmaps.dsres. The system just reads in everything it can find and merges it all into a single file table.
Conclusion[]
That's it for this tutorial. You should now have an understanding of the Resource System, "bits" and "tanks", the default tanks that ship with DS, and how resources are combined to form a unified file table. You should also be able to retrieve files out of tanks, create a map, and build a mod. Additional advanced topics are covered in other Siege 200 and 300 tutorials for more modding pleasure.
And if you're curious, there is a detailed discussion of the predecessor to the Dungeon Siege file system at https://www.drizzle.com/~scottb/gdc/its-still-loading-paper.htm
