PBOs: build, pack, inspect, unpack, extract, cat
A PBO is the archive format of DayZ: a header with the prefix and other header
extensions, a list of entries and a checksum. build makes the PBO of a mod folder the way
the game needs it, pack only archives, and inspect, unpack and cat read PBOs. PBO contents are treated as
untrusted: entry names with .., drive letters or absolute paths are never written outside the target folder.
The examples use the folder mymod/ from A first mod.
dayzmake build
Build a PBO from a folder: rapify configs, binarize models, check model textures, pack.
dayzmake build [-v] [-f] [--proton-binarize] [-w <wname>]... [-i <includefolder>]... [-x <excludepattern>]... [-e <headerext>]... [-k <privatekey>] [-s <signature>] <sourcefolder> [<target>]
| Argument | Meaning |
|---|---|
<sourcefolder> | The folder to pack. Its $PBOPREFIX$ (or its name) is the prefix. |
<target> | The PBO to write. Standard output when omitted (not allowed together with -k). |
| Option | Default | Meaning |
|---|---|---|
-v, --verbose | off | Show every warning. |
-f, --force | off | Overwrite <target> and an existing signature file. |
--proton-binarize | off | Linux: binarize .p3d and .rtm files with DayZ Tools’ binarize.exe under Proton. Without it models are copied as they are. See Binarizing models on Linux. On Windows binarize.exe is always used. |
-w <wname>, --warning <wname> | none | Mute a warning by name. |
-i <includefolder>, --include <includefolder> | none | Folder searched for absolute includes in configs and for textures of other mods when checking models. The current directory is only checked directly. |
-x <excludepattern>, --exclude <excludepattern> | none | Glob pattern of files to leave out. Repeatable. See below. |
-e <headerext>, --headerext <headerext> | none | Header extension key=value. Repeatable. See Header extensions and prefixes. |
-k <privatekey>, --key <privatekey> | none | Sign the PBO with this .biprivatekey after writing it. |
-s <signature>, --signature <signature> | <target>.<keyname>.bisign | Where -k writes the signature. |
Behaviour:
- Files are visited in sorted order, so the same folder always gives the same bytes. No timestamps are stored.
config.cppis rapified and stored asconfig.bin. Every other.cppand every.rvmatis rapified and keeps its name. A config that is already rapified is copied with theprerapified-filewarning..p3dand.rtmfiles are binarized (with--proton-binarizeon Linux). A model that is already binarized (ODOL, BMTR) is copied withprebinarized-file. A.p3dofile is packed as.p3d. Without--proton-binarizeon Linux, models are copied and each one raisesnon-windows-binarization.- Every editable (MLOD) model is checked for textures and materials that are not in the addon
(
missing-texture,missing-material). See Textures and model checks. - A file named
$NOBIN$or$NOBIN-NOTEST$in the source folder switches rapification and binarization off for the whole folder; the files are packed as they are. $PBOPREFIX$(or$PREFIX$) is read and not stored as an entry; its first bare line is the prefix and itskey=valuelines become header extensions.- Files that are not regular files (FIFOs, devices, sockets) are skipped with
unsupported-file. Names that are not valid as PBO entry names are skipped withunsafe-path. Names that collide ignoring case giveduplicate-entryand the first in sorted order wins, except that a generated entry (the rapifiedconfig.bin) wins over a plain file of the same name. - Exclude patterns use
*as the only wildcard; it also matches\. A pattern is matched against the whole path inside the PBO written with\, before theconfig.cpptoconfig.binrename and case-sensitively:-x '*.psd'leaves out every.psd,-x 'data\*.png'every PNG belowdata. Excluded files are skipped silently. - The target and the temporary files next to it are never packed into themselves.
- With
-kthe PBO is signed with a version 3 signature after it was written (see sign).
Examples:
$ dayzmake build -x '*.psd' -x 'data\*.png' m2 m2.pbo
$ dayzmake inspect m2.pbo
Header extensions:
- prefix=m2
- product=dayz
# Files: 4
Path Method Original Packed
Size Size
================================================================================
config.bin 0 291 291
data\note.cpp 0 31 31
data\x.rvmat 0 88 88
scripts\s.c 0 2 2
-e overrides what $PBOPREFIX$ says:
$ dayzmake build -e author=bzed -e product=dz m2 -f m2.pbo
$ dayzmake inspect m2.pbo | head -4
Header extensions:
- prefix=m2
- product=dz
- author=bzed
Signing needs a target:
$ dayzmake build -k mykey.biprivatekey t21
error: Cannot sign a pbo that is piped to stdout.
Warnings of a model that references files outside the addon (here t21 contains the test model small.p3d):
$ dayzmake build t21 t21.pbo
In file small.p3d: warning: Model references texture "t21\data\gone_co.paa", which is not in the addon. [missing-texture]
In file small.p3d: warning: Model references material "t21\data\m.rvmat", which is not in the addon. [missing-material]
In file small.p3d: warning: On non-Windows systems binarize.exe is only used with --proton-binarize; file will be copied as-is. [non-windows-binarization]
See also: pack, Header extensions and prefixes, Warnings.
dayzmake pack
Pack a folder into a PBO without rapifying or binarizing anything.
dayzmake pack [-v] [-f] [-x <excludepattern>]... [-e <headerext>]... [-k <privatekey>] [-s <signature>] <sourcefolder> [<target>]
| Argument | Meaning |
|---|---|
<sourcefolder> | The folder to pack. |
<target> | The PBO to write. Standard output when omitted (not allowed together with -k). |
| Option | Default | Meaning |
|---|---|---|
-v, --verbose | off | Show every warning. |
-f, --force | off | Overwrite <target> and an existing signature. |
-x <excludepattern>, --exclude <excludepattern> | none | Glob pattern of files to leave out, as for build. |
-e <headerext>, --headerext <headerext> | none | Header extension key=value. |
-k <privatekey>, --key <privatekey> | none | Sign the PBO afterwards. |
-s <signature>, --signature <signature> | <target>.<keyname>.bisign | Signature path for -k. |
Behaviour: the same rules as build for prefixes, exclusion, ordering and unsafe names, but file contents are
copied unchanged: config.cpp stays config.cpp, models stay as they are, and there are no model checks and no
include handling. Use it to repack a folder that was already built, or for PBOs that hold plain data.
Example (the folder w contains a name that is not allowed, a name that differs only in case, a FIFO and a
prefix with slashes):
$ dayzmake pack . ../w.pbo -f
warning: Removed leading/trailing slashes from prefix "/leading/". [prefix-slash]
warning: Skipping "data/a.txt": an entry named "data\A.txt" was already packed. [duplicate-entry]
warning: Skipping "data/bad:name.txt": unsafe entry name. [unsafe-path]
In file data/pipe: warning: Skipping a file that is not a regular file (FIFO, device or socket). [unsupported-file]
A missing folder is named in the error:
$ dayzmake pack nonexist x.pbo
error: Failed to read source folder "nonexist":
No such file or directory (os error 2)
dayzmake inspect
List what a PBO contains, or describe a model.
dayzmake inspect [-v] [--json] [<source>]
| Argument | Meaning |
|---|---|
<source> | A PBO or a .p3d model. Standard input when omitted. |
| Option | Default | Meaning |
|---|---|---|
-v, --verbose | off | Verbose output. |
--json | off | PBOs only: print the header as one JSON object (see below). |
Behaviour:
-
A file that starts with a model header is described as a model; anything else is read as a PBO.
-
For a PBO: the header extensions, the number of files, and a table with name, packing method (0 stored, compressed entries are listed with their packed size), original size and stored size.
-
For an editable MLOD model: format and version, the LODs with point, face, normal and UV-set counts, textures and materials with the number of faces that use them, properties and named selections.
-
For a binarized ODOL v56 model: format and version, the skeleton and bone count, the property class and damage, mass, bounding box, the LODs with vertex and face counts, textures and materials with the number of LODs that use them (a built-in material without a name is listed as
(none)), proxies, properties, named selections and the animation classes. A v56 model that cannot be read is an error. For another ODOL version, or a BMTR file, only the format and version are shown (ODOL adds a note that only v56 is decoded). -
Nothing is written; the command only reads.
-
--jsonprints one JSON object on one line, with the fields in this order:header_extensions: an ordered array of{key, value, key_hex, value_hex};prefixandprefix_hex: the prefix, or bothnullwhen the PBO has none;entries: an array of{name, name_hex, packing, original_size, data_size, timestamp}in header order.
key,value,prefixandnameare the bytes decoded lossily as UTF-8 and only JSON-escaped (no control-character escaping of the text output); the*_hexfields are the lowercase hex of the raw bytes. A parser reads the hex, because the text of a name with a byte that is not UTF-8 has lost it. For a model,--jsonis an error:--json is only supported for PBOs.
Examples:
$ dayzmake inspect --json mymod.pbo
{"header_extensions":[{"key":"prefix","value":"mymod","key_hex":"707265666978","value_hex":"6d796d6f64"}],"prefix":"mymod","prefix_hex":"6d796d6f64","entries":[{"name":"config.bin","name_hex":"636f6e6669672e62696e","packing":0,"original_size":291,"data_size":291,"timestamp":0}]}
$ dayzmake inspect mymod.pbo
Header extensions:
- prefix=mymod
# Files: 2
Path Method Original Packed
Size Size
================================================================================
config.bin 0 291 291
scripts\4_world\player.c 0 27 27
$ dayzmake inspect t21/small.p3d
Format: MLOD (editable model)
Version: 257
LODs: 2
# LOD Points Faces Normals UV sets
0 Resolution 1 4 3 2 2
1 Memory 4 0 2 0
Textures:
- #(argb,8,8,3)color(0.5,0.5,0.5,1,CO) (1 faces)
- t21\data\a_co.paa (1 faces)
- t21\data\gone_co.paa (1 faces)
Materials:
- t21\data\m.rvmat (2 faces)
Properties:
- LOD 0: class = house
- LOD 0: autocenter = 0
- LOD 1: x = y
Selections:
- LOD 0 (Resolution 1): body, old
- LOD 1 (Memory): start
Something that is not a PBO:
$ dayzmake inspect notpbo
error: Failed to read PBO:
failed to fill whole buffer
See also: Textures and model checks.
dayzmake unpack
Extract a PBO into a folder.
dayzmake unpack [-v] [-f] [--use-prefix] [-x <excludepattern>]... [--only <pattern>]... <source> <targetfolder>
| Argument | Meaning |
|---|---|
<source> | The PBO. |
<targetfolder> | The folder to extract into; it is created when missing. |
| Option | Default | Meaning |
|---|---|---|
-v, --verbose | off | Show every warning. |
-f, --force | off | Overwrite files that already exist in the target folder. |
--use-prefix | off | Extract into <targetfolder>/<prefix>/ instead of directly into <targetfolder>. |
-x, --exclude <excludepattern> | none | Glob pattern of entries to leave out. Repeatable. |
--only <pattern> | none | Glob pattern: write only the entries that match one. Repeatable. |
Behaviour:
- The header extensions are written to
$PBOPREFIX$in the extracted folder, so thatbuildorpackof the folder gives the same prefix again. Control characters in extensions are replaced with spaces (unsafe-header). - Entry names are validated before use. Absolute paths, drive letters,
.., empty names and names that are not valid file names are skipped with a warning (unsafe-path); names with a leading\are extracted without it (leading-separator). A name that is not UTF-8 is extracted as Windows-1252 (non-utf8-filename), and a second entry with the same path ignoring case is skipped (duplicate-entry). Nothing is ever written outside the target folder, and a symbolic link in the way is never followed. - Without
-f, extraction stops with an error when the target folder already contains a file of the PBO, and names the first one. Nothing is overwritten. --onlyand-xselect the entries to write: an entry is written when it matches at least one--onlypattern (or none is given) and no-xpattern, so-xwins.*stands for any run of characters, as in the-xofpack. Patterns are matched against the entry path with/separators, without the prefix, ignoring case.$PBOPREFIX$is always written, and the conflict check without-fcovers only the selected entries.dayzmake unpack --only '*.c' --only '*config.bin' scripts.pbo outextracts scripts and configs, not models and textures.- Compressed entries are decompressed. A rapified
config.binstays rapified; use derapify to read it. - With
--use-prefixan unsafe prefix is an error. An empty prefix means no prefix directory.
Examples:
$ dayzmake unpack mymod.pbo out
$ find out
out
out/scripts
out/config.bin
out/$PBOPREFIX$
out/scripts/4_world
out/scripts/4_world/player.c
$ dayzmake unpack mymod.pbo out2 --use-prefix
$ find out2 -type f
out2/mymod/config.bin
out2/mymod/$PBOPREFIX$
out2/mymod/scripts/4_world/player.c
$ dayzmake unpack mymod.pbo out
error: Target folder "out" already contains files of this PBO (first: "$PBOPREFIX$"). Use --force to overwrite.
A PBO with an entry name that starts with a separator and a header extension that contains a line break:
$ dayzmake unpack odd.pbo odd-out
warning: Header extension "note" contains control characters; replaced them with spaces. [unsafe-header]
warning: Entry "\scripts\hello.c" starts with a path separator; extracting it as "scripts/hello.c". [leading-separator]
See also: cat, Header extensions and prefixes.
dayzmake extract
Unpack a whole DayZ install, a mod or a single PBO into one tree organised by prefix, optionally derapified, with a map from prefix to PBO.
dayzmake extract [-v] [-f] [--derapify] [--only <pattern>]... [-x <excludepattern>]... <source> <targetfolder>
| Argument | Meaning |
|---|---|
<source> | A DayZ client or server folder, a mod folder (@Foo or a workshop folder) or a single .pbo. |
<targetfolder> | The folder for the tree; the parent is created when missing. |
| Option | Default | Meaning |
|---|---|---|
-v, --verbose | off | Print a summary (files, PBOs). |
-f, --force | off | Replace an existing target folder. |
--derapify | off | Write every rapified *.bin as text, with the extension .cpp. |
-x, --exclude <excludepattern> | none | Glob pattern of entries to leave out. Repeatable. |
--only <pattern> | none | Glob pattern: write only the entries that match one. Repeatable. |
Behaviour:
- For a folder, every
*.pbodirectly in itsdtaandaddonssubfolders is read; the folder names match in any case (DayZ usesAddons), other folders and deeper levels are not searched, and a folder without PBOs is an error. PBOs are processed in sorted order of their path relative to<source>, so the result is deterministic. - The entries of a PBO go to
<targetfolder>/<prefix>/<entry>. An empty prefix means the file name of the PBO without.pbo. Entry names are validated like those of unpack: unsafe names are skipped with a warning (unsafe-path), and so is a PBO whose prefix is not a safe folder name or ispbo-map.tsv;$PBOPREFIX$is not written, the map holds the prefixes. - When two PBOs write the same path, ignoring case, the later one in sorted order wins and the warning
duplicate-pathnames both PBOs. Two entries of one PBO with the same path giveduplicate-entry. When one PBO has a file where another (or the same one) has a folder, the first in that order is written and the later entry is skipped with the warningextract-path-clash; the extract does not fail. --derapify: a*.binthat starts with the rapified signature (config.binor any other) is written as.cppof the same name, in the text that derapify prints. One that cannot be read stays a.bin, with the warningderapify-failed.--onlyand-xmatch the entry name in the PBO (config.bin), as forunpack.- The tree is written to a staging folder next to
<targetfolder>(same parent, named.<name>.extract-<pid>-<n>) and replaces<targetfolder>with a rename when everything succeeded, then the old tree is removed. A re-run therefore drops files that no longer exist, and a failure (a PBO that cannot be read) leaves the old tree untouched and removes the staging folder. - Without
-f, an existing<targetfolder>is an error. With-fit is replaced and deleted after the swap, but only when it is an empty folder or holds apbo-map.tsvat its top level, that is, looks like the result of an earlierextract; any other folder is refused with an error that names it, so a wrong target cannot wipe a home folder. It must also be a real folder (not a file or a symbolic link), must not contain the source and must not lie inside it:extract -f m m/addonsis refused, so the PBOs are never deleted. A new<targetfolder>inside the source (extract m m/out) is refused as well, without-f, before anything is created; the paths are compared with symbolic links resolved. A new<targetfolder>with a..after a folder that does not exist (elsewhere/missing/../x) cannot be resolved and is refused with the errorInvalid target folder "<path>": cannot resolve ".." after a folder that does not exist. - Everything that goes wrong with a PBO is an error that leaves the old tree alone: a PBO or entry that cannot be
read (truncated, a compressed entry that does not decompress) and a file that cannot be written. Only unsafe names,
a path clash across entries and a
.binthat cannot be derapified are skipped, with a warning. <targetfolder>/pbo-map.tsvhas one line per PBO that was read,prefix<TAB>path of the PBO relative to <source>with/separators, sorted by prefix (then by path). A PBO without prefix is listed with its file name without.pbo. The prefix is written with/instead of\(like the folders of the tree), and then\, TAB, CR and LF in either column are written as\\,\t,\rand\n, so every\in the file starts an escape and a line reads back unambiguously (a prefixdz\gear\navigationisdz/gear/navigation). The prefix as stored is ininspect --json. The PBOs whose files were skipped because of their prefix are listed too.- Memory: an entry that is stored uncompressed is copied from the PBO to its file in pieces. Only compressed entries
and, with
--derapify,*.binfiles that start with the rapified signature are read into memory, up to 512 MiB each (a compressed entry over that is an error), so the largest PBOs extract in a small amount of memory.
Example:
$ dayzmake extract --derapify --only '*.c' --only '*.bin' --only '*.cpp' ~/dayz-server game
$ cat game/pbo-map.tsv
dz/gear/camping addons/gear_camping.pbo
dz/scripts dta/scripts.pbo
$ ls game/dz/scripts
3_game 4_world 5_mission config.cpp
$ dayzmake extract install out
error: Target folder "out" already exists. Use --force to replace it.
See also: unpack, derapify, Looking up the script API.
dayzmake cat
Write one entry of a PBO to standard output or to a file.
dayzmake cat [-v] [-f] <source> <filename> [<target>]
| Argument | Meaning |
|---|---|
<source> | The PBO. |
<filename> | The entry name exactly as inspect prints it, with \ as separator (quote it in a shell: 'scripts\4_world\player.c'). |
<target> | The file to write. Standard output when omitted. |
| Option | Default | Meaning |
|---|---|---|
-v, --verbose | off | Verbose output. |
-f, --force | off | Overwrite an existing <target>. Without a <target> (standard output) it has no effect. |
Behaviour: the entry is decompressed when it is stored compressed. The name must match exactly (including the
case the PBO uses); a name that is not in the PBO is an error. An existing <target> is not overwritten unless
you pass -f.
Examples:
$ dayzmake cat mymod.pbo 'scripts\4_world\player.c'
modded class PlayerBase {}
$ dayzmake cat mymod.pbo scripts/4_world/player.c
error: File "scripts/4_world/player.c" not found in PBO.