mirror of
https://github.com/1dot13/gamedir.git
synced 2026-07-22 13:40:25 +02:00
Wanne
dbd84f211e
- Disabled Real-Time Sneak per default git-svn-id: https://ja2svn.mooo.com/source/ja2_v1.13_data@1170 4f8fa57e-7814-0410-bad4-adc449f26b7c
401 lines
14 KiB
Plaintext
401 lines
14 KiB
Plaintext
|
|
------------- Howto setup the Virtual File System (VFS) -------------
|
|
|
|
v 1.1 by BirdFlu
|
|
|
|
|
|
* Table of Contents *
|
|
---------------------
|
|
I. * Introduction
|
|
|
|
II. * Configuration
|
|
II.1 - Glossary
|
|
|
|
II.2 - Basic Configuration
|
|
II.2.1 main section
|
|
II.2.2 profiles
|
|
II.2.3 locations
|
|
|
|
II.3 - Use Cases
|
|
II.3.1 main game files
|
|
II.3.2 "1.13 Mod"
|
|
II.3.3 User Mods
|
|
|
|
II.4 - Extension
|
|
II.4.1 += Extension
|
|
|
|
III. * Points of Discussion
|
|
|
|
***********************************
|
|
I. Introduction
|
|
***********************************
|
|
The Virtual File System (VFS) manages file handling and offers a unified
|
|
view on the file system to the game at 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, 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.3 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 directory has to exist, even if it is 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 them 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
|
|
|
|
|
|
II.4 Extensions
|
|
===================================
|
|
|
|
II.4.1 += Extension
|
|
-----------------------------------
|
|
In an ini file it is possible to use the += operator, which appends a value to
|
|
a previously set entry, making it a essentially list. This is possible, because
|
|
internally a data structure (PropertyContainer) is used that contains a set of
|
|
mappings, that in turn map two keys to a property
|
|
[key1][key2] = property
|
|
This data structure can be initialized from an ini file, which make 'key1' a
|
|
section, 'key2' a key and 'property' the value of that section-key pair in that
|
|
ini file. This data structure can also be initialized from multiple ini files,
|
|
where the += operator appends a new value to an already defined entry.
|
|
|
|
This extenstion is used in the configuration of the VFS, such that the definition
|
|
of the VFS_CONFIG_INI value in in ja2.ini accepts a list of configuration files. As
|
|
one value makes a one-valued list, this extension fits nicely in the system without
|
|
requiring modifications to existing configuration files.
|
|
|
|
So, a possible application of this extension could be the stand-alone configuration
|
|
of a mod, where each mod brings an own configuration file that is merged with
|
|
configuration files from other mods. Thus, it is easy to create a valid configuration
|
|
for a larger number of mods, where otherwise for every mod combination an own
|
|
configuration file would have to be created. And even for a small amount of
|
|
(combinable) mods the total number of configuration files would increase very fast.
|
|
|
|
For the default mod combination (Vanilla, 1.13) there would be two mod and one user
|
|
configuration file
|
|
|
|
############# vfs_config.ja2.ini
|
|
[vfs_config]
|
|
PROFILES = SlfLibs, Ja2Data
|
|
|
|
[PROFILE_SlfLibs]
|
|
...
|
|
|
|
[PROFILE_Ja2Data]
|
|
...
|
|
|
|
[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 = User Profile
|
|
LOCATIONS =
|
|
PROFILE_ROOT = Profiles\UserProfile
|
|
WRITE = true
|
|
##############
|
|
|
|
The actual combination of mods would be done in the file ja2.ini, where
|
|
|
|
############# ja2.ini
|
|
[Ja2 Settings]
|
|
VFS_CONFIG_INI = vfs_config.ja2.ini, vfs_config.user.ini
|
|
|
|
would be the Vanilla game configuration, and the following
|
|
|
|
############# ja2.ini
|
|
[Ja2 Settings]
|
|
VFS_CONFIG_INI = vfs_config.ja2.ini, vfs_config.v113.ini, vfs_config.user.ini
|
|
|
|
would be the setup for the "1.13" mod.
|
|
|
|
Other mods can be added by simply entering its configuration file
|
|
in the list
|
|
|
|
############# ja2.ini
|
|
[Ja2 Settings]
|
|
VFS_CONFIG_INI = vfs_config.ja2.ini, vfs_config.v113.ini, mod1.ini, mod2.ini, vfs_config.user.ini
|
|
|
|
In order to avoid mixing savegames and temporary files of different mod combinations,
|
|
a separate user profile directory can be used, where every user profile is defined
|
|
in an own user configuration file. The user profile can be selected by adding the
|
|
according configuration file at the end of the mod configuration file list.
|
|
|
|
***********************************
|
|
II. Points of Discussion
|
|
***********************************
|
|
|
|
TODO: ...
|
|
|