mirror of
https://github.com/1dot13/gamedir.git
synced 2026-07-22 13:40:25 +02:00
Wanne
89ffa5f5ec
- Updated XML files in Data\TableData - Moved Document files to new folder named "Docs" git-svn-id: https://ja2svn.mooo.com/source/ja2_v1.13_data@1134 4f8fa57e-7814-0410-bad4-adc449f26b7c
343 lines
12 KiB
Plaintext
343 lines
12 KiB
Plaintext
|
|
------------- Howto setup the Virtual File System (VFS) -------------
|
|
|
|
v 1.0 by BirdFlu
|
|
|
|
***********************************
|
|
I. Introduction
|
|
***********************************
|
|
The Virtual File System (VFS) manages file handling and offers a unified
|
|
view on the file system at game runtime. All files are accessible through
|
|
a path inside the VFS. During the setup, files and directories can be mapped
|
|
to a specified location in the VFS independent of its real location on the
|
|
hard disc. Additionally to the mapping of real files and directories, also
|
|
file archives can be mapped. Only SLF and uncompressed 7z archives are
|
|
supported right now.
|
|
|
|
The current layout of the VFS is based on the original Ja2 game data directory,
|
|
i.e. the data directory is the root directory of the VFS. Further, there are
|
|
directories that are defined by the original SLF archives (Anims, BigItems,
|
|
Sounds etc.). These archives build the basic layer and on top of that come the
|
|
files from the Data directory. So, whenever a file is accessed (with path/filename
|
|
e.g. Tilesets/0/smguns.sti), the game looks in the Data directory first, and when
|
|
the file cannot be found there, it looks in the according archive (tilesets.slf
|
|
in this case).
|
|
|
|
The 1.13 Mod adds another layer on top, which is the Data-1.13 directory that
|
|
behaves in the same way as the Data directory. That is, when a file is accessed,
|
|
the game looks in the Data-1.13 directory first and only then continues with the
|
|
previously described steps.
|
|
|
|
The VFS extends this system even further. It externalizes the definition and
|
|
configuration of these layers or profiles (as they are called in the VFS jargon)
|
|
and allows for an unlimited number of them. Additionally the 7z file (uncompressed)
|
|
archive format is supported. Now the order of inclusion of the profiles and the
|
|
actual files and directories lie in the hands of the user. Thus a proper
|
|
configuration of the VFS is required.
|
|
|
|
***********************************
|
|
II. Configuration
|
|
***********************************
|
|
The configuration of the VFS is done in an ini file (vfs_config.ini). You can
|
|
specify the filename in ja2.ini in key VFS_CONFIG_INI (section : Ja2 Settings).
|
|
If you don't do it, it defaults to vfs_config.ini.
|
|
|
|
But lets define some basic terms(bottom to top), first.
|
|
|
|
II.1 Glossary
|
|
===================================
|
|
Location : A location can either be a real directory or a file archive. All files
|
|
inside these loactions are mapped into the VFS (recursively, i.e. contents of
|
|
subdirectories are also mapped). The user can specify the path inside the VFS
|
|
into which the external files are mapped.
|
|
|
|
Profile : A profile is a named collection of locations. It is encouraged to define
|
|
a new profile for every mod and it is also encouraged to keep the data of this
|
|
mod "together". That is, the profile can define a profile root directory to
|
|
which the location directories are appended during initialization. (Keeping the
|
|
profile root empty gives you the possibility to stick together directories from
|
|
very different places on your hard disc. A better solution is to define a new
|
|
profile for non-related directories).
|
|
|
|
Profile List (Stack) : Finally, the VFS is build from a list of profiles, where
|
|
the list is proccessed from left to right, i.e. the leftmost will be included
|
|
first and the rightmost profile will be included last (on the top of the stack).
|
|
During file access, the profiles are processed in reverse inclusion order. A
|
|
file search will start in the rightmost profile and will continue to the left.
|
|
|
|
Profile mode : a profile can be defined as read-only (default) or as read-write.
|
|
You cannot write to a read-only profile. As there are some files that have to
|
|
be written (temporary file, savegames, logs, etc.) you have to define at least
|
|
one profile as read-write. Usually this should be the top (rightmost) profile.
|
|
Otherwise you could end up blocking a writable file with a read-only file.
|
|
|
|
II.2 Basic configuration
|
|
===================================
|
|
Lets start with a basic configuration.
|
|
|
|
II.2.1 main section
|
|
-----------------------------------
|
|
The ini file start with
|
|
[vfs_config]
|
|
PROFILES = profile1, profile2, profile3, ...
|
|
|
|
The value of the key PROFILES is a list of profile names. For every element
|
|
(profile) in this list another section must exist that has the format
|
|
[PROFILE_$name], where $name is a value from the profile list
|
|
(e.g. [PROFILE_profile1].
|
|
|
|
II.2.2 profiles
|
|
-----------------------------------
|
|
[PROFILE_profile1]
|
|
NAME = Some Arbitrary Name (probably a mod's Name)
|
|
LOCATIONS = location1, location2, loaction 3
|
|
PROFILE_ROOT = Profiles\mod1
|
|
WRITE = TRUE
|
|
|
|
Each profile definition must have a NAME key and also a LOCATIONS key. The value
|
|
of NAME can be used inside the game to access the data of the specified profile.
|
|
The value of LOCATIONS is again a list of location names. Additionally a
|
|
PROFILE_ROOT path can be specified that will be prepended to all paths defined
|
|
in the location sections. A profile can have the WRITE property (default is FALSE).
|
|
At least one such profile must exist, as this is the place where temporary files
|
|
will be saved. Usually the top profile will have the WRITE property.
|
|
|
|
Obviously a file must be saved in a real directory, so one of the locations is
|
|
supposed to have the TYPE = DIRECTORY. This directory should be mapped as root
|
|
(MOUNT_POINT = ). The most simple case is to define only one location with the
|
|
described properties. Thus the written temporary files will be saved in one place,
|
|
instead of being scattered over multiple unrelated directories.
|
|
|
|
II.2.2 locations
|
|
-----------------------------------
|
|
[LOC_location1]
|
|
TYPE = DIRECTORY
|
|
PATH =
|
|
MOUNT_POINT =
|
|
|
|
[LOC_location2]
|
|
TYPE = LIBRARY
|
|
PATH = profiles/libs/archive.slf
|
|
VFS_PATH = archive.slf
|
|
MOUNT_POINT =
|
|
|
|
A location section name is build from an element from the LOCATIONS list of the
|
|
profile that is prepended with LOC_, e.g. [LOC_location1]. For every location the
|
|
TYPE has to be specified and can either be DIRECTORY or LIBRARY.
|
|
|
|
For a DIRECTORY you can specify the PATH (directory) and the MOUNT_POINT. The
|
|
PATH value is appended to the PROFILE_ROOT path and decided where your files will
|
|
be located in the real file system. With the MOUNT_POINT value you can influence
|
|
the location of your files in the virtual file system. So, real path
|
|
PROFILE_ROOT/PATH/local_dir/file.name
|
|
will be mapped to
|
|
/MOUNT_POINT/local_dir/file.name
|
|
(accessible by just MOUNT_POINT/local_dir/file.name)
|
|
|
|
A library is similar to a directory from the initialization point of view. But,
|
|
additionally, it has another key, VFS_PATH, which is similar to the PATH (file)
|
|
value. If the PATH value is not defined (= empty) or the specified file cannot
|
|
be opened, then the VFS_PATH value is evaluated. In order for this to work, you
|
|
have to have processed a location that contains the specified files. While this
|
|
is a more complex configuration process, it gives you the possibility to integrate
|
|
archives that are located in another archive themselves.
|
|
|
|
II.3 Use Cases
|
|
===================================
|
|
|
|
II.3.1 main game files
|
|
-----------------------------------
|
|
The main use case is the setup of the main files for the game.
|
|
|
|
##############
|
|
[vfs_config]
|
|
PROFILES = Libs, Data
|
|
##############
|
|
[PROFILE_Libs]
|
|
NAME = Ja2 game libraries
|
|
LOCATIONS = Anims, ..., Faces, ..., Tilesets, ...
|
|
PROFILE_ROOT = Data
|
|
|
|
[PROFILE_Data]
|
|
NAME = Ja2 game files
|
|
LOCATIONS = Files
|
|
PROFILE_ROOT = Data
|
|
##############
|
|
[LOC_Files]
|
|
TYPE = DIRECTORY
|
|
PATH =
|
|
MOUNT_POINT =
|
|
##############
|
|
[LOC_Anims]
|
|
TYPE = LIBRARY
|
|
PATH = anims.slf
|
|
MOUNT_POINT =
|
|
|
|
[...]
|
|
|
|
[LOC_Tilesets]
|
|
TYPE = LIBRARY
|
|
PATH = tilesets.slf
|
|
MOUNT_POINT =
|
|
|
|
##############
|
|
|
|
So, basically, you have the profile that specifies the game libraries as described
|
|
in (I.). Following is the profile with the Data directory. Since you need to have
|
|
a writable profile, we define a user profile that will contain only user data (the
|
|
other profiles contain only game data).
|
|
|
|
[vfs_config]
|
|
PROFILES = Libs, Data, UserProfile
|
|
|
|
[Libs and Data as before]
|
|
|
|
[PROFILE_UserProfile]
|
|
NAME = User files
|
|
LOCATIONS =
|
|
PROFILE_ROOT = Profiles\UserProfile
|
|
WRITE = true
|
|
|
|
If LOCATIONS is empty and WRITE is set to TRUE, then a writable directory in
|
|
PROFILE_ROOT will be initialized automatically.
|
|
|
|
II.3.2 "1.13 Mod"
|
|
-----------------------------------
|
|
Adding a mod is simple. We take the 1.13 Mod as an example.
|
|
|
|
[vfs_config]
|
|
PROFILES = Libs, Data, v113, UserProfile
|
|
|
|
[Libs, Data and UserProfile as before]
|
|
|
|
[PROFILE_v113]
|
|
NAME = v1.13
|
|
LOCATIONS = datav113_dir
|
|
PROFILE_ROOT =
|
|
|
|
[LOC_datav113_dir]
|
|
TYPE = DIRECTORY
|
|
PATH = Data-1.13
|
|
MOUNT_POINT =
|
|
|
|
The new profile for the Mod 1.13 is inserted into the profile list after the
|
|
Data profile, but before UserProfile. So, whenever a file is accessed, it
|
|
will be taken from the "Data-1.13" directory (when it exists there of course).
|
|
If not, the game will search in the following profiles ("Data", then "Libs").
|
|
|
|
II.3.3 User Mods
|
|
-----------------------------------
|
|
Instead of adding game data, the user can also add or replace the writable
|
|
profile (user profile). Thus, he can try out a new mod (that uses the VFS system)
|
|
without risking to overwite his savegames (and other temporary files).
|
|
|
|
#################
|
|
[vfs_config]
|
|
PROFILE = Libs, Data, v113, ExperimentalMod, UserProfile_exp
|
|
|
|
#################
|
|
[Libs, Data, v113 as before]
|
|
|
|
#################
|
|
[ExperimentalMod as in II.3.2]
|
|
[PROFILE_ExperimentalMod]
|
|
NAME = Files for experimental Mod
|
|
LOCATIONS = ExpMod_Libs, ExpMod_Files
|
|
PROFILE_ROOT = Profiles/ExpMod
|
|
|
|
[LOC_ExpMod_Libs]
|
|
TYPE = LIBRARY
|
|
PATH = exp_mod.7z
|
|
MOUNT_POINT = Tabledata
|
|
|
|
[LOC_ExpMod_Files]
|
|
TYPE = DIRECTORY
|
|
PATH = ModFiles
|
|
MOUNT_POINT = Interface
|
|
|
|
#################
|
|
[PROFILE_UserProfile_exp]
|
|
NAME = User file for ExpMod
|
|
LOCATIONS =
|
|
PROFILE_ROOT = Profiles\User_ExpMod
|
|
WRITE = true
|
|
|
|
(NOTE: the user directories have to exist, even if they are empty)
|
|
|
|
Since you can define the filenames for you VFS configuration file in ja2.ini,
|
|
you can create a couple of vfs config file and switch between then fairly
|
|
easy
|
|
|
|
############# ja2.ini
|
|
[Ja2 Settings]
|
|
;VFS_CONFIG_INI = vfs_config.main.ini
|
|
;VFS_CONFIG_INI = vfs_config.my_mod.ini
|
|
VFS_CONFIG_INI = vfs_config.ExpMod.ini
|
|
|
|
-----------------------------------------------
|
|
|
|
//**********************************
|
|
Combine INIs:
|
|
//**********************************
|
|
|
|
It is possible now to use += in an ini file, which appends a value to a previously set entry, making it a essentially list. Additionally,
|
|
in ja2.ini you can specify a list of ini files instead of only one file. Of course only one value works too, so everything is optional.
|
|
|
|
This gives us the possibility to define an ini file for every mod (or to combine inis as we like, as long as the ordering is the same.) I'll give you an example.
|
|
|
|
--------- vfs_config.vanilla.ini ---------
|
|
[vfs_config]
|
|
PROFILES = SlfLibs, Vanilla, UserProf
|
|
|
|
[PROFILE_SlfLibs]
|
|
....
|
|
|
|
[PROFILE_Vanilla]
|
|
....
|
|
|
|
[LOC_...]
|
|
....
|
|
....
|
|
--------- ---------
|
|
|
|
--------- vfs_config.v113.ini ---------
|
|
[vfs_config]
|
|
PROFILES += v113
|
|
|
|
[PROFILE_v113]
|
|
NAME = v1.13
|
|
LOCATIONS = datav113_dir
|
|
PROFILE_ROOT =
|
|
|
|
[LOC_datav113_dir]
|
|
TYPE = DIRECTORY
|
|
PATH = Data-1.13
|
|
MOUNT_POINT =
|
|
--------- ---------
|
|
|
|
--------- vfs_config.user.ini ---------
|
|
[vfs_config]
|
|
PROFILES += UserProf
|
|
|
|
[PROFILE_UserProf]
|
|
NAME = Player Profile
|
|
LOCATIONS =
|
|
PROFILE_ROOT = Profiles\UserProfile
|
|
WRITE = true
|
|
--------- ---------
|
|
|
|
So, in ja2.ini we would have the following entry for Vanille
|
|
|
|
VFS_CONFIG_INI = vfs_config.vanilla.ini, vfs_config.user.ini
|
|
|
|
and for v1.13
|
|
|
|
VFS_CONFIG_INI = vfs_config.vanilla.ini, vfs_config.v113.ini, vfs_config.user.ini
|
|
|
|
and for any other mod
|
|
|
|
VFS_CONFIG_INI = vfs_config.vanilla.ini, vfs_config.v113.ini, mod1.ini, mod2.ini, vfs_config.user.ini
|
|
|
|
Of course, the user.ini can be adjusted to every mod, so that savegames are not mixed. So, if you (=inexperienced user) want to add a small mod, you don't have to struggle with a big incomprehensible ini, but instead just take the provided mod ini (which will work if all files are in default directories) and add it to the ini list in ja2.ini.
|
|
|