First of all, Serious Engine requires that all the files it manages reside in one directory, or any of its subdirectories. It is not allowed to load or save a file from outside that directory, or from some other disk. We call that directory 'engine directory' (engine dir for short). This keeps all the files in one place and prevents the possible problem of using the absolute paths in inter-file dependencies. Any file is uniquely identified by its path relatively to the engine dir.
On each computer, the directory can have a completely different name; you can even have more than one copy of the engine at the same time coexisting on the same system.
When the game or any of the editors is started, the engine auto-detects the path from where it is started. In the entire engine dir and its directories, there are no files with any references to the absolute path of the engine dir. That way, you can simply make a copy of the entire engine dir to another directory, disk or computer, and it will automagically work.
When working in a team, you will usually want to share that directory to be visible to the other members of your team through network, so that they don't need to take care where you put it. Also, you may want to make a master directory on a fileserver for keeping the newest version of all the files (artwork, sounds, levels, etc. there).
If you have installed Serious Sam and the Serious Engine tools, you probably have engine dir like 'C:\Program files\Croteam\SeriousSam\'
It is very important that you remember that you cannot load any file out of that directory. If you try to do so in an editor, a warning message box will pop up telling that 'the file resides outside of xyz directory and it cannot be loaded', where xyz is your engine dir. To load the file, first copy it somewhere inside the engine dir.
Inside the engine dir, directory structure is more or less free. Some files must be in specific directories, but the rest is flexibile. Here, I will describe the structure used for Serious Sam in detail:
Bin\
The binaries of engine, game, entities and editors must reside in this directory.
Bin\Debug\
Debug versions of the binaries are located here.
Classes\
Entity class links (.ecl) files are located here. Those are used to identify individual entity classes.
Data\
Misc data files, like file lists, config files etc. are saved here.
Data\Translations
Translation files for language localization are located here.
Data\Var
Some specific variables that need to work independently of the usual persistent symbol storage scheme are put here saved as text files.
Fonts\
Font files and their respective textures.
Levels\
World files for the game.
Models\
Put model '.mdl' files here and in the subdirectories.
Models\Editor\
Some specific model files required by WorldEditor and Modeler must be here.
Music\
Music .mp3 files.
Players\
Player configuration files (players name and appearance for each player).
SaveGame\
Savegames are saved here sorted in different directories for each player, plus one directory for split-screen multiplayer saving and one for network multiplayer.
Screenshots\
Screenshot are auto-saved here when you press F11.
Scripts\
Script files for the console startup.
Scripts\GLSettings\
Special scripts for automatic adjustment of GL settings for each 3D card.
Sound\
Sound files (.wav)
Temp\
Engine, game and editors save various temporary files there. For example, quick-saved demos, editor undo/redo files and clipboards, and similar are saved there.
Textures\
.tex files
Thumbnails\
Thumbnails (.tbn) for each entity class that can be inserted in the world.
VirtualTrees\
WorldEditor saves your custom virtual directory trees for the browser there.
If you are just making additional content for the Serious Sam, you will have to respect this structure in order to have the things work. If you have licenced the engine, perhaps you may want to change it thoughly if you need to. (Maybe you don't need player configurations, savegames and such things, which are Serious Sam dependent.)
Each file by itself is a separate module and the engine does not rely on any kind of packages. Still, there are some things that you have to take care of before moving files around. The files are refered to by their paths relative to the engine dir. If, e.g. a world 'levels\mylevel.wld' uses a texture 'textures\wall01.tex', and you decide to move the texture to 'textures\walls\bricks.tex', the world will not be able to load any more. To enable you to do that, Serious Engine supports automatic file replacement.
The file 'Data\BaseForReplacingFiles.txt' maps names of original files to the paths where they have been moved to. In the above example, if you add a line:
"textures\wall01.tex" "textures\walls\bricks.tex"
to that file, the world mylevel.wld will be loaded automatically replacing the the old path name for the new one. If you try to load the world without making the replacement file in the game, the loading will fail. But, if you try to load it in the WorldEditor, it will ask you to browse for the new file. If you do that once, it will remember the replacement in the aforementioned text file, so if you try to load another world with the same texture, the replacement will work automatically without your intervention. At the end, you will be noted that some replacements were made.
This is a usefull tool if you rename/move your files sometimes. However, sometimes you may not want that to happen. Perhaps, you want to know that you don't have some file on disk. If you use the replacement feature, you may want to check the remap manually in a text editor from time to time, to make sure you know what is going on. Also, take extensive care not to create recursive remappings!
Usual dependencies are that the worlds depend on all the textures, models, sounds and classes used in the world. Classes depend also on the models, textures and sound used by the classes. Etc.
Those dependencies are saved in each file that engine uses in a special tagged format. The Depend utility (depend.exe) can later be used to extract those dependencies and see what is dependent on what. This is useful for updating new versions files, for distribution of new content and similar.
For example, once you have created a level, lets say 'levels\mylevel.wld', you can use Depend utility to recursively extract all the files needed to run that level. If you then want to distribute that level, you know that you must include all those files in the distribution. You can also check those files against some previous distribution of the game which did not contain that level and find only those files that are newer or added, etc.
For more information on how to use Depend utility, see its own documentation.
Serious Engine, its editors and the game will work very well having all the files put in directories like said above. However, putting several hundreds of files in their directories is both inconvenient for the end user (due to the mess itself, and potential induced slack-space) and impractical for distribution.
To solve that, you can zip a group of files together in one large '.gro' file. Group files are just ordinary zip files, which you can create using your favorite zip utility (like InfoZip, PKZip, WinZip, WindowsCommander, etc.). After compressing it, rename the file to give it a '.gro' extension, and put it in the engine directory (in the root of it). At startup time, the engine will scan for all the group files in its engine dir and add them to an internal search list.
When loading a file, engine uses following scheme:
If MOD is started
- it first tries to directly open the file on the disk, but relative to corresponding mod directory (i.e. Mods\MyMod\Models\Player\SeriousSam\...)
- if file isn't found, engine tries to locate it in all .gro files in mod root (Mods\MyMod\) directory, following reversed alphabetical order logic (newer versions by alphabetical order have priority)
If MOD is not started
- it tries to directly open the file on the disk (in its corresponding directory)
- if file doens't exist on disk, it searches on CD
- if the file is not there, it looks in each of the group files in the reversed alphabetical order
- if the file was not find even in the group files, it tries to look for the replacement file path if the replacement is found, return to 1) and try again with the new path
- if no replacement is found it asks the user to locate a replacement file (only if editors are installed)
- if the file is still not found, an error is reported
So when you add a group file with a completely new content, you can generally give it any name you like, provided it has the '.gro' extension and that it is located in the engine dir root.
But, if you want to create a group file which will override some older file, you must make sure that:
1) The file that needs to be overridden does not exist on the disk. Physical files on the disk always override all group files.
2) The name of the group file is _after_ (in the alphabetical order) all the other group files that might contain the file to be overridden.