MakePbo version 1.xx by mikero.
see readmegeneral.txt and fixes
for obfuscation see end of document
also read cfgPatches.ReadMe.htm
ExtractPbo GUI is the gui alternative to makepbo when you simply want to modify an existing file in an existing pbo.
MakePbo is a venerable program that dates back to the origins of OFP's cwc. It maintains full compatibility with those products while creating pbo's for Arma3 (and beyond)
As such, be a little kind when reading the documentation (and some of the idiosyncratic -options). Some of it will not make sense to the context you are trying to achieve, eg making an arma mission or addon.
Makepbo is by no means difficult to use, often simply requiring nothing more than
MakePbo NameOfFolder
Intelligent heuristics
Makepbo uses heuristics in examining the folder contents to 'understand' what you're trying to achieve. This makes it easy for both mission makers and addon makers to use Makepbo without having to remember -options. It figures most of it out dependent on context of the folder and what it contains.
But, you can fine tune this simplicity with a wealth of -option over-rides dependent on what you are trying to achieve (compressed files, altered prefix, un-included files, date-stamps, auto conversion of wav), the list goes on... There's chemistry involved, and you are in control.
ALL pbo types are supported by MakePbo: Ranging from ofp-cwc thru to arma3 & vbs lite. Genuine vbs product is only available to vbs employees.
Be aware, immediately that a 'pbo' can have several different extensions. Specifically
The general case is that MakePbo will decide what extension to use.
Syntax: MakePbo [-options] Full\Path\To\Foldername [destpath and/or pboname[.pbo|ebo|xbo|ifa]]
Despite the wealth of options available, the most common and generally accurate syntax is
makepbo Full\Path\To\Foldername
Foldername.pbo will be produced in the parent folder of foldername
Options: (case INsensitive)
- VBS2 EBO (vbs employees only)
- -Vm1 Vbslite pbo UK Mission
- -Vm2 Vbslite pbo US Mission
- -Vx1 xbo file UK
- -Vx2 xbo file US
Caveat. Bis unbinarised
MakePbo is not a drop in replacement for bis binarise.. Makepbo does not binarise p3d's and wrp files.
What it can do however is detect faults that binbpo does not.
WrpFiles: Makepbo will fail if you attempt to add an unbinarised wrp.
P3DFiles: Makepbo will fail if you attempt to add an unbinarised p3d and do not use the -U option
no files will be compressed if an unbinarised p3d is present
options with arguments
can be stated as
-option space argument OR
-option=argument
the latter allows proper detection of the first genuine non-option file reference
Compress files (see below)
[.lst|.txt|<.ext>] can be either of the defaults, or an explicit extension
Exclude files (see below)
EXTERNAL REFERENCES
-G Check external references
This checks that file\references in any file of the pbo that could contain them are present on the p: drive. Any file means p3d's, wrps', rvmats, mission.sqm, sqf, configs....
This is a confidence check that you haven't created typos. For map making it is almost essential that you use this option.
SHA/CRC SIGNATURES
sha key signatures (Arma) or crc checks (elite) are automatically appended to end of file. when appropriate
PBO PREFIX: This section does not apply to ofp.
Prefixes apply to addons, not mission or campaign pbo's. if mission/campaign pbos have prefixes, they are ignored by the engine. Be careful with this terminology. An addon, can contain missions.
Either a genuine prefix or a presumed prefix is embedded in the header of all addons.
A prefix will be embedded in a pbo by makepbo under the following cascading rules:
A 'mission' pbo is defined as one without a config.cpp AND has a mission.sqm (mission ADDONS have config.cpp's)
makepbo any\where\fred ->prefix = any\where\fred
makepbo fred ->prefix=fred
Bis arma engines allow for a pbo without a prefix to assume a prefix of the name of the pbo.
If and only if
- the pbo is an arma family addon (mission pbo's do not have prefixes)
- the resulting prefix name is a unitary file Ie p:\fred (not a p:\somewhere\fred),
- the resulting unitary file name IS the output filename
- the -$ option is specified,
THEN no prefix will be written. (Otherwise the option is ignored).
CAUTION: '$PBOPREFIX$' and 'PboPrefix.txt' '$PBOPREFIX$.txt'
These are the unfortunate historical names for adjusting the header of a pbo.
The dll adds additional lines to the pbo header using one of the above files. The file itself is never included in a pbo.
variable=value;
The most notable use of above is to specifically state THIS pbo's intended engine
Product=Arma3;
author=I am Famous;
Compression
compression (and obfuscation) is disabled if you pack unbinarised p3d's.
Any pbo can be compressed for ANY engine. Since many low grade pbo extractors 'out there' don't understand compression, this can be used as a mild form of obfuscation.
The results of compressing mission pbos can achieve better than 75% reduction in payload.
For addons, the results are less spectacular (between 5..10%) because pax's (which form the majority of files in an addon) are generally the largest in size and are (mostly) pre-compressed anyway.
Obfuscation automatically implies compression. If no specific compression is specified, it will use the defaults.
syntax:
Default is no compression. (no -z option)
MakePbo -Z="Comma,Separated,Ignore,List" [ otheroptions...] folder....
MakePbo -Z=IgnoreList[<.ext>|.lst|.txt] [ otheroptions...] folder....
Makpbo -Z=default // use the dll's internal context-algorithm
The 1st method uses parameters directly from the command line. This list MUST be enclosed in quotes. (if ,,, or spaced args)
The 2nd method utilises (an often common) ignore list. The content of which should be same as a command line entry (obviously), except quotes in this case are optional.
.lst or .txt extension is optional for the 2nd method. You can alternatively specify a different .extension
compression will only occur to each 'file' if resulting output is smaller that original.
YOU MUST SPECIFY A LIST if using the Z option
If you want DEFAULT files to be compressed use "default"
If you want no files to be compressed, don't specify Z !!!
At time of writing the doc, the dll defaults to ignore are
"thumbs.db,*.txt,*.h,*.dep,*.cpp,*.bak,*.png,*.log,*.pew, *.hpp, init*.*"
to get the ignore list actually used, look in setup-> of pboProject
if you want ALL files compressed use "all" (the dll will not 'see' .all extensions, and hence compress all files)
However, note that, under no circumstances will the dll compress a file to make it LARGER.
This frequently occurs for pax files. The result is, that pax will be stored untouched.
"Comma, Separated, .Ignore, *.List"
The format is pretty much free form. Spacing between args is permitted any of the following forms are mutually equivalent.
Dos wildcard extensions are used. Allowing you to set explicit files, explict extensions and part named files or extensions
*.ogg
.ogg
ogg
*.sq* any sqf or sqs file
Note that compression can take considerable time to achieve. It is 'safe' however to simply allow the dll to attempt to compress it's internal, default, file list.
NOTE for vbs2
encrypted AND compressed files *cannot* co-exist. If compression is specified, the pbo is encrypted along with any uncompressed files. The compressed files (if any) remain unencrypted.
===Optional destination===
can take several forms
*MakePbo [MyPath\]MyAddon // ->output to [MyPath\]MyAddon.pbo
MakePbo [MyPath\]MyAddon ThisAddon // ->output to CurrentDir\ThisAddon.pbo
*MakePbo [MyPath\]MyAddon ThisAddon\ // ->output to CurrentDir\ThisAddon\MyAddon.pbo
MakePbo [MyPath\]MyAddon ThisAddon\ThisPbo // ->output to CurrentDir\ThisAddon\ThisPbo.pbo
MakePbo [MyPath\]MyAddon \ThisAddon // ->output to \ThisAddon.pbo
*MakePbo [MyPath\]MyAddon \ThisAddon\ // ->output to \ThisAddon\MyAddon.pbo
MakePbo [MyPath\]MyAddon \ThisAddon\ThisPbo // ->output to \ThisAddon\ThisPbo.pbo
Note that, under ALL circumstances, if 'ThisAddon' happens to be the name of a folder, it is equivalent to stating 'ThisAddon\'
Note: extension type is not required and has consequence for users specifying an XBO target but, in fact, the dll discovers it's a vbs2 lite mission.
under that, special, unique circumstance, the intended.xbo is renamed to .pbo (a vbs 2 lite quirk)
*MyAddon is subject to pboname.h. see versioning readme
PBO OUTPUT NAME
be aware that the name of the pbo is irrelevant to the engine. it can be called 'spaghetti' for all that it matters.
the rules are as follows
'standard' behaviour is to place an NameOf.pbo in the parent folder of where\ever\NameOf Folder.
example:
makepbo any\where\elephants//-> any\where\elephants.pbo
makepbo elephants//-> elephants.pbo
==specifying output==
makepbo some\elephants any\where ->any\where\elephants.pbo
makepbo some\oranges any\where\elephants.pbo -> any\where\elephants.pbo
NOTE THAT
drives: and or \root\path specifications are as equally valid as relative addressing
-X PBO EXCLUSIONS ignored if -N wyswig
Rules:
In order of precedence:
1) under no circumstances are (dot)xxx folders examined or included. They are what
their intention is :- Hidden
2) Option -N (No rapify, no binarise, no nada) is the wyswig option. No files
are ignored, no files are examined, no files are checked. What you see is truly
what you get.
3) config.cpp
It is very normal to exclude *.cpp *.h and *.hpp. After binarisation, they have
done their job. The best way of including them in a pbo, is to simply not Rapify,
(option -wysywig)
EVEN IF *.cpp is specified to be excluded, a config.cpp file (and any of it's
#includes) are special in that they will binarised to .bin and thus not actually
ignored. Not included, but not ignored.
4) If nothing is specified on the command line, the default exclusions are:
This default list is likely to change in the future as bis keep moving goalposts.
There is an unfortunate but popular use of hpp files as included sqf files. Bis
in their wisdom call files not intended to be in the pbo, (dot)hpp. To
accommodate users of popular and well respected addons such as cba use the
following syntax
-X=thumbs.db,*.txt,*.h,*.dep,*.cpp,*.bak,*.png,*.log,*.pew
Command line options
-X= none
NOTHING will be excluded
-X="comma,separated,list"
When more than one file type is excluded, eg, commas, the list must be specified
between quotes. Spacing is permitted.
-X= An\Exclude\File\Somewhere[.lst|.txt]
Obfuscation. the -! option
Obfuscation is not encryption.
Obfuscation has been introduced to protect people from thievery with arma3 life servers (among others). The weak spot in encryption is once you crack the key, the door is open. Obfuscation uses a different cipher (key) each time the pbo is made. So, unlike encryption, the purpose is not to prevent extraction but make it a frustrating experience to the thief. One of the ciphers is to leave the door half open to let the thief think he's figured it out (and embarrass himself by publishing a how to). That said, obfuscation also attempts to prevent extraction but only as it's first line of defence.
The results range from very difficult to impossible to extract meaningful files. The consequent data is either intentionally misleading,. deliberate garbage, corrupted, 'apparently' corrupted, or simply missing (depends on the cipher sequence employed at the time).
ALL major players writing extractors (including bis) detect an obfuscated pbo and refuse to continue. The intent behind this is to protect the innocent who would otherwise have no indication that they are about to flood their file system with hundreds x hundreds of garbage files. That's a fair enough warning, and won't stop a thief from (hopefully) damaging his file system if he persists.
The dll uses a one time cipher each time a pbo is obfuscated. The same pbo folder obfuscated again will produce a different result making any knowledge gained extracting one pbo can't be applied to another one, even the same one, republished. Obfuscated pbos are approximately 15% larger.
In addition, obfuscated pbos automatically use compression so that plain text data is not immediately visible in a hex editor. If you don't like the defaults, change them with the -Z= option. The defaults for the current dll are visible in the setup page of pboProject (as are files to be excluded).
Control of this process is in your hands. Be particularly wary of compressed sqf files. Most can be. Some can't.
Any easy, but not always practical method is to call any invoked file initxxxxx.xxx. The dll will not compress init*.*
Avoid the temptation to disallow compression for *.sqf. You are exposing your text to the thieves when you do, Take the time and trouble to protect yourself.
What also enhances your protection is calling your files by very strange names. Using Cyrillic rather than English is an excellent choice, so too are any of the European characters, as are simply writing a089s3454.sqf (gibberish)
The dll will mimic your gibberish. If you encode in Cyrillic, it will obfuscate in Cyrillic, if you use numbers, it will use numbers. This makes distinguishing garbage files from real ones an interesting exercise, let alone hiding myGreatElephant.sqf so no one knows it's an elephant.