
	SoCPUP Manual for Version 1.0

SoCPUP (Shadow of Chernobyl Patcher/Unpacker/Packer) can 
be used to manipulate and reconfigure the STALKER Shadow 
of Chernobyl (retail/Steam) gamedata.dbn game database 
files, permitting the extraction of game assets for 
examination and editing, as well as repacking those 
extracted assets for customized versions of the game.

The tool also includes a simple file patcher to permit  
limited modification of files for use with the game.

This combination may allow one to distribute the program 
with batch files and patch files instead of the extracted 
and patched game resources, some of which are fairly large.

*********************************************************
  Please make a backup of your gamedata files before
  using this program.  Some extraction options can 
  overwrite your custom files.  Some protections are
  provided; read this document for details.
*********************************************************

SoCPUP is intended for use in a command prompt shell on a 
Windows-based PC (e.g., one that can run STALKER).

Put the executable in the STALKER SoC install directory, 
or copy the gamedata.dbn files you wish to examine/modify 
to a directory where you have write permission, and put the 
SoCPUP executable there.

You can use the program with batch files.  If the batch 
files are supplied by a third party, be sure to examine 
them in a text editor to see what operations are intended. 
Double-click on the batch file (or right-click and select 
Open) to run it.  Also examine any patch files.

You can click Start, then Run... and type cmd.exe to open 
a command shell.  Or you can find and open the Command 
Prompt utility (in XP, click Start, All Programs, and 
Accessories).  You will need to change directories (and 
maybe the drive as well) to navigate to the location where 
you will be running the program.

You can change the starting directory in the Command Prompt 
shortcut to open in your STALKER directory or in your 
working directory like Documents.  Right-click-drag the 
Command Prompt shortcut and drop it on your desktop ("Copy 
Here") and then right-click the desktop shortcut and select 
"Properties" to change the "Start in" directory.

Run SoCPUP without parameters to see a short list of syntax 
options:

-----------------------------------------------------------
Shadow of Chernobyl database patcher/unpacker/packer 1.0 (Jan 12 2012)
   derived by NatVac from bardak's X-Ray game asset converter's database i/o

Usage: socpup <common-options> <format-specific-options> <input-object>

Common options (optional):
 -ro		perform all the steps but do not write anything on disk
 -verbose	list all files and directories processed
 -out <PATH>	output file name (DB pack), default: dir as extension
 -dir <PATH>	output folder name (DB unpack), default: extension
 -extract[x] <PATH>	specific file or folder name (DB unpack)

DB options:
 -unpack	unpack game archive (expects file name)
 -pack		pack game archive (expects folder name)
 -patchfile	patch extracted game archive (expects file name)
 -2947ru	assume CIS release version format
 -2947ww	assume world-wide release version format (default)
 -xdb		assume .xdb archive format
 -11xx or -2215 or -2945	assume 1114/1154, 2215, 2945/2939 (unpack only)
-----------------------------------------------------------

Here are some details on those options.

__________
-ro

Use the -ro option first for any operation, to test what 
the program will do without any disk writing.  While the 
program has some safeguards built in, you should still 
use this option for the first attempt just in case.

__________
-verbose

If you want to see more details on what the program is 
doing when packing or patching, include the -verbose 
option.

__________
-unpack gamedata.dbn

This extracts all the files in gamedata.dbn, where n is 
a number or letter.  The retail version and patches 1.0001 
through 1.0004 have gamedata.db0 through gamedata.db9, 
gamedata.dba and gamedata.dbb.  Patch 1.0005 (Steam) also 
includes gamedata.dbc, and patch 1.0006 adds gamedata.dbd.

The "-unpack" specifier is actually optional when 
extracting from retail gamedata.dbn files.  The program 
will understand that unpacking is intended when a file 
is given as the target.  See the "-dir" option below.

SPECIAL NOTE:  When extracting multiple database files 
into the same target directory (e.g., gamedata), you must 
extract them in order:  .db0 first, then .db1, etc. 
through .db9, then .dba, then .dbb, then optionally .dbc 
followed by .dbd.  The reason for this is that later files 
are intended to override earlier ones by the same name.


-----------------------------------------------------------
You may need to use one of the format-specific options:
 -2947ww	assume world-wide release version format (default)
 -2947ru	assume CIS release version format
 -xdb		assume .xdb archive format
 -11xx		assume 1114/1154 (unpack only)
 -2215		assume 2215 (unpack only)
 -2945		assume 2945/2939 (unpack only)

Note that if the format-specific options are omitted, the 
program will attempt to determine the format from any non-
retail file extension as follows:

 .xrp		assume 1114/1154 (unpack only)
 .xpn (n=alphanumeric)	assume 2215 (unpack only)
 .xdbn (n=alphanumeric)	assume .xdb archive format

If the file extension is .dbn, the program assumes 2947ww 
format.  If you are extracting data from a CIS version of 
the game, you must explicitly specify the -2947ru option.

-----------------------------------------------------------
You can use -unpack with the following common options:
 -ro (read-only operation; see explanation above)
 -dir <path>
 -extract or -extractx <relative path or file>

__________
-dir <path>

The program will use <path> as the target directory for 
the extraction.  Use this option with caution, as the 
extraction will proceed without regard to any pre-existing 
files in the target directory.

If -dir is not supplied, the program uses the extension 
without the period as the target directory for the 
extraction. So "-unpack gamedata.dbb" will create the 
subdirectory dbb and put the gamedata files in it.

In this case, if the target extension-dir already exists, 
the extraction will not continue, to protect any work you 
might have already done on that directory.

The idea is that you might want to repack the extracted 
directory when you are finished.

__________
-extract <relative_path>

Use this option to extract just the subdirectory or 
subdirectories indicated by <relative_path>*.  This means 
that all paths within the archive that start with 
<relative_path> will be extracted.  Example:
-extract sounds\characters_voice gamedata.db4
will extract the sounds\characters_voice\human_* 
directories and the dialogs.rar file, while
-extract sounds\characters_voice\human gamedata.db4
will only extract the subdirectories.

__________
-extractx <relative_path_to_file>

Use this option to extract a single file.  Only the file 
that matches exactly will be extracted.  Example:
-extractx textures\mtl\mtl_garage_pryp_02.dds gamedata.db7 
will put textures\mtl\mtl_garage_pryp_02.dds in db7.

-----------------------------------------------------------
Packing

Packing is the complement of unpacking, reversing the 
process -- to a degree.  The mechanism supported by 
bardak's algorithm does not re-compress the database files 
themselves, but it does compress (-xdb, -2947ru, -2947ww) 
the directory structure and optionally encrypts it for the 
Russian version of the game (-2947ru) or the worldwide or 
North American version of the game (-2947ww, default).

Because the files are not compressed when repacked, you 
can expect the larger archives to grow by about a third.

So why pack?  Well, packed database files don't need the 
fsgame.ltx change, for one thing.

For another, there are a lot of unused resources that are 
still being processed in the original files -- about half 
the scripts are not used in the vanilla game, but they are 
still loaded by the game. Unpacking by itself does not 
remove those useless files.

Interestingly, the -xdb format should be compatible with 
all distributions of the retail game.

__________
-pack <folder_name>

The program will attempt to rename any existing target 
file by replacing the period with an underscore.  Once 
renamed, the original will not be overwritten by the 
program in subsequent packs.  Example:  The original 
gamedata.dbb becomes gamedata_dbb.

Why the underscore?  STALKER SoC will process any file 
that starts with "gamedata.db", so gamedata.dbb_not_used 
would still be loaded.

While the packing process is occurring, you will see a 
listing of the directories being "packed" followed by a 
series of dots.  These dots are provided to indicate the 
packing progress.  While they correspond to the actual 
files and directories, there is often not a one-to-one 
match; a file might be processed (one dot) followed by 
a directory (new line) followed by the files in that 
folder (one dot each) followed by the files in the parent 
folder, yet the output will still show those dots on the 
child folder line.

You can use -pack with the following common options:
 -ro (read-only operation; see explanation above)
 -verbose (adds dir listing; see explanation above)
 -out <filename>

__________
-out <filename>

This option tells SoCPUP what the name of the destination 
archive will be.  Example:  -out gamedata.dbe

If the option is omitted, SoCPUP will use the directory 
name as the extension following "gamedata.".  If the 
subdirectory is dbb\, the default output would be 
gamedata.dbb.

If you are using the WW/NA version, packing a database 
file can be as simple as "SoCPUP db4" because the 
format-specific option defaults to -2947ww.  Otherwise 
you will need to include the format option.


-----------------------------------------------------------
Patching 

Rather than make another executable to patch the files 
extracted with SoCPUP, the program itself has been 
extended to include a rudimentary file patcher.

__________
-patchfile <patch_file>

This directive will open <patch_file> and process it, 
expecting a list of commands, one per line, telling it 
what to do. The commands are either stand-alone directives 
or they take one parameter, which is currently the rest of 
the line after a separating space.  Commands are case-
insensitive.

Initial whitespace on the line (leading spaces or tabs) 
is ignored.  If the first printable character is not 
alphabetic, the line is treated as a comment, so you can 
use your favorite symbol for comments: #, --, //, ;, etc.

The commands supported are:

ExitAlreadyPatched - stops the patch process and returns 
with an error code of 1 for batch file processing.  It 
does not know if the file is already patched itself.  See 
the If* commands.

ExitNotFound - stops the patch process and returns 
with an error code of 5 for batch file processing.  It 
is simply an exit directive; it does not know if anything 
was not found.  See the If* commands.

The If* commands each perform a test.  If the result is 
true, the next line is executed.  Otherwise it is skipped.

IfMatch <string_to_match> - compares the <string_to_match> 
with the data at the current offset in the memory image of 
the file to patch.  If the string is matched, the next 
line in the patch_file is executed, skipped otherwise. 
The number of characters in the comparison is set by the 
length of <string_to_match>.  Example:
  IfMatch <string>def_shaders\def_vertex/mtl\fixx_mtl_garage_pryp_02

IfNotMatch <string_to_match> - same as IfMatch but the 
test is inverted.  If the string is not matched, the next 
line in the patch_file is executed, skipped otherwise. 
Example:
  IfNotMatch def_shaders\def_objects_lod/mtl\mtl_garage_pryp_02


LoadFile <relativefilepathname> - reads the file to patch 
into memory. Example:
  LoadFile gamedata\levels\l11_pripyat\level

ReplaceWith <replacement_string> - overwites the memory at 
the current offset with <replacement_string>.  Currently 
the replacement is one-for-one; there is no change in the 
size of the file image.  Example:
  ReplaceWith def_shaders\def_vertex/mtl\fixx_mtl_garage_pryp_02

RenameOriginal <new_name> - renames the disk-based copy of 
the file loaded via LoadFile with <new_name>.  Does 
nothing if renamed file already exists.  Example:
  RenameOriginal gamedata\levels\l11_pripyat\level.orig

SaveFile - saves the memory image to the original file 
name.  If you wish to preserve the original, rename it.

SaveFileAs <filename> - saves memory image to <filename>. 
Example:
  SaveFileAs gamedata\levels\l11_pripyat\level

Seek <offset> - expects a decimal value.  This value will 
be used to index into the file's data in memory for future 
operations.  Example:
  Seek 4431388

SeekHex <offset> - like Seek but expects a hexadecimal 
value.  Example:
  SeekHex 00439E1C

SoCPUP_Version <version> - indicates the minimum file
patcher version required to process the patch_file.
Example:
  SoCPUP_Version 1.0

See the _PripyatLevelFix.patch file for an working example 
of most of these commands.

Enhancements are in the works for the file patcher, like 
the ability to use hexadecimal parameters in searches and 
replacements.  Support for these commands is also planned 
or under consideration:

IfFind <string_to_find> - begins looking at current offset 
+1 for <string_to_find>.  Returns true if found, false 
otherwise. Sets new offset if found. NOT YET IMPLEMENTED

IfFindNext - uses string from IfFind. NOT YET IMPLEMENTED

IfNotFind <string_to_find> - like IfFind, but returns true 
if the string is not found, false if it IS found. NOT YET 
IMPLEMENTED

The file patcher functionality is subject to change at the 
whim of the developer(s) as a result of feedback from you.

You can use -patchfile with the following common options:
 -ro (read-only operation; see explanation above)
 -verbose (echos each patch command; see explanation above)


-----------------------------------------------------------
Other notes:

__________
Output redirection:

Most displayed output is actually "printed" to stderr, so 
normal '>' redirection on the command line won't work.  
Use '2>' to redirect the stderr output to a text file:

SocPUP gamedata.db4 2>db4.txt

This will extract the files in gamedata.db4 using the 
default NA/WW format, put them in the db4 subdirectory, 
and write the feedback info to the file db4.txt.

__________
Listing the contents of an archive:

To obtain the directories and files in an archive without 
actually extracting them, use the -ro option.  Example:

SocPUP -ro gamedata.db4 2>db4.txt

If the extraction destination directory already exists, use 
the -dir option:

SocPUP -ro -dir list gamedata.db4 2>db4.txt
