Author: Mikero
All Mikero tools 'behave', install, and operate in an identical manner. You are strongly advised to read the General Readme once.
Any mention of 'binpbo' also means 'addon builder' for arma3 or dayz.
pboProject is Addon Builder on steroids.
pboProject allows you to build one, or dozens of pbos in one operation. (A 'pbo' is an .xbo, .ebo, .ifa, or .pbo, dependent on engine type selected)
It has been in existence for some years as the tool behind Cold War Revisited 1,2 & 3, Ace/Cba, Cup, UnSung, Savage Game Design, and a host of other major mods.
pboProject is not just a 'makepbo'. It creates (and signs) MODS. (which include addons, missions, and campaigns).
pboProject is designed for multi engine packing from ofp thru to vbs, dayz and the Arma series. It is garanteed to remain compatible with older engine development. Mikero's tools, in general, are always backward compatible.
The basic philosophy is:
P:/MyProject
P:/MyProject/MyObjects
P:/MyProject/MyObjects/MyPlants
P:/MyProject/MyObjects/MyBuildings
P:/MyProject/MyObjects/MyRoads
P:/MyProject/MyObjects/MyIsland
P:/MyProject/MyMissions
P:/MyProject/MyMissions/MissionOne
P:/MyProject/MyMissions/MissionTwo
P:/MyProject/MyMissions/MyCampaign
*Selecting any one of the above 'Source Folders' will generate one, or, multiple pbos determined by the content of that folder and it is children (if any).
Selecting:
P:/MyProject -> (re)builds everything
P:/MyProject/MyMissions -> (re)builds all the missions only
P:/MyProject/MyObjects/MyPlants -> (re) builds a single plants pbo
There is no restriction in depth. MyPlants, could be separated into (at least) two other pbos MyPlants,/MyBushes, and MyPlants/MyTrees
For simple use, clearly, if there are no child folders of consequence in MyProject, then only MyProject.pbo is built.
Folders of consequence: The presence of a config.cpp/bin, mission.sqm. or desc.ext (for campaign) marks the beginning of a pbo for that folder and all it is children (if any).
Note that any subsequent configs in child folders are NOT pbo's in their own right. They become part of the classic, 'multiple addons within a single pbo'. This is the method by which you initially release one big pbo, and for subsequent patches to plants (eg) you merely repack plants!!! This is the method of providing patch pbos. Bis call it hotpatching. One huge pbo later followed by smaller ones only containing a child folder or three.
The other major features of pboProject are:
The most forbidding of all errors is your addon works, but unknown to you at the time, destroys all others. The dll wont let you. Expect to be frustrated and thank me later.
The dll is quite likely to give you a specific reason for the bad result, and it expects you to fix it. 'Errors' range from simple typos to known, under-the-covers issues with the engines(plural) that break if you create a p3d with no geolod (exaggerated licence used).
A no nonsense auto installer saving you sweat and tears.
Do not run this, or any tool from bis, as administrator.
'Admin' is not what you think it is, it is an alias for 'Microsoft Office Use only'.
Consider yourself warned.
Grab the self installers for these here
Either:
? | show syntax and options+/-$ | do/don't allow no prefix for pbo-A | Remove appid+A=123 | Set appid+/-B | Do/Don't binarise sqm or cpp+/-C | Clear/Don't clear temp\project folder+/-D | Do/Don't delete png after processingE=whatever | Engine is arrowhead arma3 or dayz+/-F | disabled: was (don't)rebuild required addons+/-G | Do/Don't convert wav/wss to ogg.+/-H | Disable/Enable png conversion. (Dayz only)+I=some\folder | see wrp config documentation-I | turn off+/-J | Do/Don't Automake stale pbos (wrp only)+/-K | enable/disable signing+K=whatever.bikey | use this keyL=name | label for pbo's name. (folder name by default)M=SomeFolder | mod output+/-N | Noisy to log on/off+/-! | Obfuscate on/off (same as O)+/-O | Obfuscate on/off (same as !)+/-P | do not pause+/-Q | do/don't delete wav/wss after conversionR | Restore original settings after this session+/-S | do/don't stop processing after any error+/-T | do/don't truncate (shrink) p3d. Dayz only+/-W | warnings are errors on/offX | exclude from pbo:comma,separated,list (else use gui settings)+/-Z | do/don't compress (use gui settingsZ= | exlude from compresscompression:comma,separated,listpboProject only uses bis binarise.exe for UNbinarised p3'ds, wrps and rtm. All other file types are handled by the dll.
pboProject distinguishes between:
The differences result in:
Similar to all other Mikero Dos tools pboProject will operate in dos mode command line when parameters are specified.
Like all Mikero dos tools, options are CasEinSenSitive and follow expected conventions.
In it's simplest form:
pboProject.exe SourceFolder
will use the existing parameters previously set up in the Gui in a separate session (such as the mod folder, and other options), to create the relevant pbo(s).
It is equivalent to being in the gui in the first instance, selecting a source folder, followed by a Crunch. The difference being the gui is not displayed.
For batch mode operation use the -P option
pboProject.exe -P SourceFolder
In this mode, control is returned (after processing) to the underlying batch file with good, or bad, status as appropriate. pboProject is closed.
It is highly recommended that you initially set up the parameters you want in the gui and use the above simple syntax.
Note that you can get genuine bad status but no error displayed because the temporary dos console has been closed. You can fix this by NOT using the -Pause option to discover the source of the error.
All options are optional.
The default for all options (other than -P) is the previously stored values during a gui session of pboProject
Syntax: (baccus naur format)
pboProject [+/-options...] SourceFolder [+/-moreOptions....]
Options (and the sourcefolder) may appear in any order or sequence on the command line. The intent is to allow intuitive use by the user, or to assist in easy scripting for a batch file.
The source folder is mandatory. For addons, it must be located in the correct position on a 'Pdrive'. A 'Prive' is any drive:\ (such as P:\ or Z:)
Both + and - are option indicators. The meaning is context sensitive. Thus:
Quotes are required for spaced file names
Most options can be specified in short or long form.
option=anything ends this option string
Example:
-e="arma3" -Mod="\some\where\else" more options....
Mod Folder : AnyDrive:\any\where
This is the mod folder. It is NOT the destination of the pbo, it is the root of the destination(s).
The mod folder can be anywhere. It is intended to be the same specification as you supply to the arma -mod= command line
The packer will create pbo's in:
Also see the setup panel for creating a mod.cpp for your entire mod.
Source folder: workspace\your_tag\some\where
Is always specified from the root drive.
The full path to the source folder must be specified. This autoatically establishes a pboPrefix (when relevant).In addition the drive where this project exists is ALSO the 'P' drive. This has consequences when checking that external files exist.
Examples are shown in the foreword above
There are variations on this simple folder topology based mostly on your own creativity and imagination.
Note that configs within configs are not deemed to be pbo's in their own right. It is a reasonably common practice to have multiple addons (configs) in the same pbo.
The practice of BI to sometimes NOT provide a cfgPatches class in a pbo is unacceptable. Having an addon name prevents crash to desktops and assists in correct loading order.
The detection of a config establishes the prefix of the pbo (but see comments re $pboprefix$.txt at end of document)
Crunch:
Should be obvious.
View Output
You can view the output with mild interest to see whether specific files are being compressed eg, or rapified eg, or simply being excluded. At the end of the day, EITHER, you get no errors, OR, you will get an error listed as the last message on the console and an accompanying messageBox to warn you of the failure.
View BinLog(s):
bis binarize.exe can produce a storm of messages which fill it's own 'binlog'. The information varies from useless to simply confusing. striplog.bat is invoked after binaraise to clean out the noise in theis file. Bis to return anything except good status.
Because binarise never reports an error (via status) pbo project inspects the contents of the binlog after binarise has completed and warns you of any errors or warnings listed in that log. It does NOT stop processing.
Options
Noisy Output
Sign Pbos
Full Build
Note that wrps are always rebuilt. painfully slow. but not as slow as changes you make having no effect because it wasn't rebuilt.
Compress:see the MakePbo readme
Will compress specific file types in a pbo depending on context of the pbo (mission,addon,engine type). Up to 50% reduction for map addons, 80% for missions and 10...30% for standard p3d addons.
Obfuscation: see the MakePbo readme.
Be aware that:
- an obfuscated pbo cannot be extracted.
- obfuscation means compression too.
The reason for compression is to protect you from the thief 'seeing' your plain text in a hex editor.
Files that are #included or called in any init*.sqf cannot be compressed. Since this varies from user to user, you have to manually tell pbo project which ones to exclude. Failure to do so inevitable causes the mission not to work as you expected.
You can take the cheap option and simply exclude *.sqf from compression, but that will leave you unprotected.
Encrypt: only available for vbslite
Don't Binarise: mission.sqm or cpp
For mission.sqm's
Under some circumstances the bis engine cannot accept binarised mission.sqms in addons.
Use this option when you strike trouble.
Note than the dll always binarises a mission.sqm to check for errors, but it is converted back to plain text for the pbo.
for config.cpp's
Some config.cpp's cannot be binarised because they contain Eval/Exec statements that are only known AFTER game loads.This option is only useful in single pbo packing because it is unlikely all your pbos need a cpp in them. the same comment for missions applies here too. pboProject WILL binarise the cpp to check for errors but discard the result.
Mission Folder is?
pboProject cannot distinguish between SP and MP missions. You need to tell it where to place the resulting pbo (if any) in the mod folder.
Sets less used parameters that are not normally changed between sessions such as location of your private bikey and which engine you're compiling for.
Engine
Establishes the correct 'pbo' as required:
AppId
Provided for dlc product entries. Unless you are creating paid for dlc content, you should leave this field empty.
On Completion
Provided to signal a very long pack has completed. Options available are to flash the screen in some way and/or provide a musical beep to alert you to a failure or success. You can provide your own tunes or turn them off.
Delete all temp files
drastic
A last chance warning message is provided.
Bis heavily rely on the temp folder to contain all objects and other assets that you use in your current project. They are not necessarily built or related to the current project, but must be there.
Over time, this temp folder fills with either stale, no-longer-used, data, or stuff that should have been rebuilt but hasn't been. (by you)
This is an all-bets-are-off approach to ensure that you are starting off with pristine objects and is an excellent way of pboProject notifying you that some other pbo's have yet to be built, let alone, preventing bis binarise getting oh-so-confused.
Note that unlike bis tools, pboProject does not allow you to arbitrarily decide where this folder is. It is hard-wired, and the reason for being so is that ALL projects, even the ones you made last year MUST point to the one common temp. In the bis dev world (not your world) the temp folder is the game engine.
The gui warns you that deleting everything out of here, while beneficial, is a drastic step. No harm will come to your pc in doing so, but caveat emptor.
Delete all mod files
drastic
A last chance warning message is provided.
There is no way of automatically deleting 'stale' pbo's. One's that you know longer build or called them a different name. These stale pbo's stick like glue in the mod folder (along with their bisign's) and mostly cause un-explained grief when running the game because you forgot about them.
This is an all-bets-are-off approach, for you to start again. No harm will come to your pc. But, caveat emptor.
Excluded files
To future proof pboproject (and indeed makepbo and the dll) a default list of file exclusions is provided in setup.
In brief this option came about because of the increasing use by Bis of hpp files to be included in a config.cpp, and, the need to account for new file types (such as roadlibs.cfg and any more newly introduced files as bis improve the product)
Normally hpp files have no meaning outside of a config.bin. An unfortunate exception to this has occurred with community use of hpp to contain sqX statements. (In hindsight the file(s) should have been called sqH).
At time of writing, the default exclude is
"thumbs.db,*.txt,*.h,*.dep,*.cpp,*.bak,*.png,*.log,*.pew, *.hpp"
and, ~source\ is never inspected
All other files will be passed thru and packed.
For community users that insist on using hpp for sqX, simply remove hpp in the setup panel.
Note that the exclude list applies to ALL pbo's packed during that session. Not just a single pbo (but see wildcard exclusion below)
Some file types that are included in a pbo irrespective of a default list:
roadlibs.cfg
config.cpp->config.bin
Note that you can exclude FOLDERS so that pboProject will ignore them entirely, but you cannot exclude files like png eg, from being processed.
-B Excluded files
A separate list is provided for when you need to retain a config.cpp. Which, would normally involve 'allowing' .h and/or .hpp files too. This list is provided separately so that you do not have to constantly edit the main filter too.
Excluded Compression
Similar to exclude files in a pbo, excluded compression provides the opportunity to over-ride the defaults that the dll will use when compressing files in a pbo.
Ordinarily you should let the dll determine what is appropriate (it has far greater knowledge than you of the various engine and pbo types)
The default list is more a case of not bothering to try and compress, already compressed, file types such as paa, jpg and sounds. This speeds the process of building a pbo.
sqX files might encounter issues if compressed in missions. The dll will never compress init.sqs and init.sqf, no matter what. But see obfuscation above for other sqf files that cannot be compressed.
This facility is provided solely for your experimentation.
wildcard exclusion
All common wildcard expressions are available including folder exclusion.
In addition, the two lists mentioned above can have exclusion files AND wildcards.
Typically one would apply for mission packing, and the other for addons.
These exclusion files can be placed directly in the folder to be packed. they will NOT be added to the pbo. In this way, you can tailor exlcusions to individual pbos.
Text Editor
By default, notepad. It is highly recommend to use Notepad++.
WrpOptions
See map making below.
Signing pbos
Private Key: AnyDrive:\any\where\YourTag.biprivatekey
-W warnings are errors:
self explanatory
-S Stop processing on any error
Normally, pboproject will move on and crunch the next pbo to be made.
-G Convert all sounds to ogg
Subscriber only. wss and wav are converted to ogg. The wss and wav are retained as source.
-H Do not convert png (Dayz only)
Dayz sometimes uses non power of 2 png directly. pboProject will normally error out when this happens. This prevents a conversion attempt. Note also, this automatically over-rides png in the exlusin list (if present) from being excluded from the pbo. This saves you from altering that list each time.
Cutscenes
Cutscenes are a bad idea inside a wrp pbo. They condemn that pbo, and that wrp, to only be usable if the units are present. This means migrating islands to another engine, or simply using it as a stand alone for all to enjoy cannot be achieved.
pboProject will halt if warnings are errors, otherwise, well, you have been warned.
Wrp Options
Delete png
This option will remove png files that pboProject has successfully converted to paa. This is especially useful, indeed almost mandatory for the layers\ folder of wrp, but can be used for any purpose or pbo make.
Automake other pbos
This is the default setting of pboProject. A pbo containing a wrp will NOT be built until pboProject is satisfied that ALL objects used in that wrp are up-to-date and exist in p:/temp
Normally pboProject will (re)make as many pbos as required to satisfy above. You can disable this automation and do them manually if you so wish, but, bottom line is, the wrp will not be packed until it's done.
Location of cfgWorlds config
When creating maps, binarise must read the config.cpp that contains MinForestSquares for this wrp.
When that config is adjacent to the wrp, there's no issues. And this step is not necessary.
When, as is often the case, you provide a separate pbos for the config, the layers, and the wrp, you must tell binarise where it is.
Whis is achieved in one of two ways:
The pbo containing the config for this wrp can contain a $pboPrefix.txt.
That file can contain cfgworlds=\some\config\some\where pboProject will use it, in preference to the setup option.
This is a convenience when you have multiple maps to build and each one uses a different\config\somehere.
Whether stated by prefix, or by setup, the folder (and its children) are scanned until a suitable config cpp is found.
A 'suitable config' is one that has:
class cfgWorlds
{
class NameOfWrp
pboProject does some basic checks that the folder you specify is correct.
Further checks are made that the worldname and cfgWorldsList is also correct
pboProject only uses this path if it discovers the config it needs is not adjacent to the wrp.
If the config it needs is adjacent to the wrp, this setting is ignored and cleared automatically.
A 'correct' $pboprefix$ file over-riders anythng stated in setup.
land class generation
For further reading: read this
All p3d's which have a geolod class=
Must must have a corresponding land class in a config some\where.
The reason being, that these objects are animated in some way and the only way they work IN a map is to have a land class associated with them.
Binarise bakes the name of the land class in the wrp if it can find it.
pboProject temporarily adds these classes as externs in the config adjacent to the wrp. This prevents binarise wandering all over your pdrive. These externs do not exist in the packed pbo, they are created to fool bis binarise.
You can see which p3ds are considered land classes while scanning with the symbols, 'T', 'H', and 'S'.
A separate file is produced in temp along with the binlog for your viewing pleasure, of which land classes have been added.
If they genuinely don't exist then animations won't work in game, and it's up to you to create them. The criteria here is to unconditionally create a 'good' pbo, AND prevent binarise wandering.
Binarised p3ds
To build Arma3 island builds successfully, and to get round the infamous no-icon error, bis binarise.exe requires that ALL p3d's used on your island are:
This has nothing to do with the base requirement that ALL p3d's are in their correct locations in workspace. Duplicates of those files must also, be in the temp folder. Do not blame me!
pboProject scans the temp folder to ensure that this is the case and tries to avoid having severe bloat in the temp folder of duplicated and un-necessary copies of the same p3d if you aren't using them.
Use the View Output button.
Simply select the noisy option and reprocess. The exact cause of the problem and it is location in a file is pretty verbose.
The dll always temporarily rapifes description.ext in order to check for errors.
Special checks are made that EXEC/EVAL statements, if present, are valid. Only a small handful of sqX commands are legal in description.ext (they must all produce constants at run time)
the packer is hard-wired to use workspace\temp to store files for bis binarise
The 'temp' folder behaves in identical manner to binPbo. It is a place to store intermediate files for packing.
Please note the distinction between a source<<< folder and a 'source' folder of files containing p3ds and config.
The temp folder is only used if bis binarize.exe is invoked and pboProject tries to avoid doing so.
pboProject will force bis binarise to ignore a source\ folder(s) in the current pbo being built. It does so by temporarily moving that folder to p:/temp/nameOfPbo/source/
When building multiple pbo's or even 'addons in addons' in a single pbo, any/all source\ folders are accounted for and moved properly
As a protection mechanism, if any source/ folder already exists in p:/temp pboProject will not continue until you do something about it. This 'protection' is there in the unlikely event that pboProject was unable to move the folder back to it's original location.
Bis have made increasing use of var=something in the header of pbo's to expand the meaning of that pbo. These strings are called token pairs. (bis binarize calls them -properties)
Such examples are:
prefix=my\folder\some\where
product=ifa // a pbo intended only for ifa engines
product=a3 // ditto
svn= 1567 // a vbs2lite encryption key
version=21;
author=somebody
These token pairs are as numerous (and as long) as a piece of string. There is no limit to their quantity. Anything not understood / not looked for, in the header is ignored by the various engines. Most token pairs even if understood are optional (even prefix=)
$PBOPREFIX$.txt if present in the same folder as the root config.cpp (eg the root folder of the intended pbo) is examined for token pairs.
Such pairs are inserted into the header of the pbo.
This mechanism works via the dll and is unconditional. It is not dependent on bis binarize or any other tool.
If you place (or leave after extraction) a prefix.txt in the folder, it is contents will be reflected into the new pbo.
Thus, if you were making a pbo intended solely for arma3, you would state:
You could just as easily state:
It is quite legal to have multiple $prefixes$ in child subfolders (with attendant configs). They are ignored.
They are used at the time you choose to issue only a pbo of that subfolder. It is the subject of pbo patching and outside the scope of this document.
$PBOPREFIX$.txt is an alias for any of the following file names
The reasons for the different names are a progression from the early dayz of xbox elite to the present time. The dll recognises any of them as being valid.
Creating binarised rtms is a challenge. Blame bis for their usual incompetence. It was too hard for them to look at their own source code to figure out what bis binarise required.
There are two distinct modes of operation that cannot be swapped for the other:
Example:
//MyBridge.cfg adjacent to MyBridge.rtm
class CfgSkeletons
{
class Default;
// ...
class MyBridge: Default
{
skeletonInherit = "Default";
skeletonBones[] =
{
"1","", //components that will animate on destruction
"2","",
"3","",
"4",""
};
};
};
Enjoy
Mike Andrew, Norfolk Island, Oct 2013