The Full Binning & PIGG Packaging Process

What is binning?

The City of Heroes engine uses binary .bin files for faster loading. Binning converts human-readable text and config files into these optimized binaries. Both server data and client data must be binned.

What are PIGG files?

PIGG files are the production distribution format for client data. The client builds a virtual filesystem from loaded PIGG archives, especially from the configured patch directory (for example, <ClientRoot>\ouro\). Loose client bins can sometimes be loaded by the v2 client, but they are not the intended production release format.

What are .texture files?

.texture files are DDS textures wrapped with a custom header. The header contains the relative path to the texture (for example, texture_library/GUI/Icons/powers/IconName.dds). This embedded path is critical — the game uses it to locate the texture.

Data vs localdata

• bin/data/ — base game data (original CoH content).
• bin/localdata/ — server custom content (new powers, textures, maps).
• The server merges localdata over base data.
• Most custom content (powersets, textures, maps) lives in localdata.

Bin server location

<BinServerRoot>\

Key batch files (in bin server root)

1-delete-old-bins.bat       Clears old binary files
2-rebuild-server-bins.bat   Rebuilds server-side .bin files (mapserver_debug)
3-rebuild-client-bins.bat   Rebuilds client-side .bin files (ouroboros_debug)
6-update-server-bins.bat    Updates server bins without full rebuild
7-update-client-bins.bat    Updates client bins without full rebuild
8-copy-product-catalog.bat  Copies product_catalog.bin to server\bin\
9-copy-binned-files.bat     Copies binned files from bin\data\ to binned\
10-build-patch-piggs.bat    Optional manual fallback for packing patch PIGGs

PIGG packing tools

Command-line packer:

• Location: <BinServerRoot>\bin\tools\pig.exe
• Existing Jenkins usage:

.\bin\tools\pig.exe cfvvz piggs\v2_serverbin.pigg binned\
.\bin\tools\pig.exe cfvvz piggs\v2_bin.pigg binned\

Piglet GUI / source:

• Source/tool folder: <PigletRoot>\
• Built GUI executable also exists in bin\tools\Piglet.exe

Texture conversion tools

City Icon (recommended)

• Location: <CityIconRoot>\publish\CityIcon.exe
• Supports PNG, JPG, TGA, DDS.
• Command line: CityIcon.exe --convert --mode [login|icons|folder] --source "input" --output "output"
• The output folder must be named texture_library for the correct embedded path.
• Creates .texture files with proper headers automatically.

GetTex (alternative)

• Location: <BinServerRoot>\GetTex\GetTex.exe
• Only processes TGA files.
• Has bugs requiring source code fixes (fopen modes, lock file paths).
• Embeds the output directory name into the texture header.
• Not recommended unless specifically required.

Manifest generation

Preferred: launcher / admin manifest panel (for example https://www.example.com/manifest).

• Scans public\game and calculates MD5 hashes / sizes for every distributed file.
• Required after replacing PIGG files in the client mirror.

Legacy script: <ToolsRoot>\update_manifest.js — only updates selected loose-bin entries and is not sufficient for final releases.

Pre-step: Merge content to data folder (critical)

Before binning, custom content must be merged into the correct binning server source folders using the Merge Tool. Loose files placed directly under bin\serverdata\Defs\ are not binned correctly and must be treated as a mistake.

• Merge Tool location: <MergeToolRoot>\
• Purpose: merges new power definitions, textures, and other assets from 2. Deployment into the binning server data tree.

Power data destinations

.powers      ->  bin\serverdata\Defs\powers\
.powersets   ->  bin\serverdata\Defs\powers\
.categories  ->  bin\serverdata\Defs\powers\
.ms          ->  bin\serverdata\texts\English\Powers\

Merge process

1. Run the Merge Tool from the bin server root directory.
2. Select source: 2. Deployment folder.
3. Select destination: the correct binning server destination folder.
4. Click Merge to combine all custom content into the data directory.
5. Verify merged files appear in the canonical locations, especially bin\serverdata\Defs\powers\ and bin\serverdata\texts\English\Powers\.

• Always merge before running any binning steps.
• The merge tool may create backups of overwritten files.
• Check merge logs for any conflicts or errors.
• Some content may require manual merging if tool conflicts occur.

Step 1 — Delete old bins

Run 1-delete-old-bins.bat. Clears old binary files to prevent conflicts. Required before any rebuild.

Step 2 — Rebuild server bins

Run 2-rebuild-server-bins.bat

mapserver_debug.exe -createbins -verbose 2 -project ourodev

• Generates server-side binaries (powers, classes, costumes, etc.).
• Takes ~5–10 minutes.
• Output: bin\data\server\bin\

Step 3 — Rebuild client bins

Run 3-rebuild-client-bins.bat

ouroboros_debug.exe -console -createbins -verbose 2 -fullscreen 0 -project ourodev

• Generates client-side binaries (geobins, texture bins, etc.).
• May take 10+ minutes (times out at 10 min if too slow).
• Output: bin\data\bin\

Steps 4–5 — Update bins (optional)

If you only changed a few files and don't need a full rebuild:

• 6-update-server-bins.bat — update server bins.
• 7-update-client-bins.bat — update client bins.

Step 6 — Copy product catalog

Run 8-copy-product-catalog.bat. Copies product_catalog.bin to server\bin\. Required step.

Step 7 — Copy binned files

Run 9-copy-binned-files.bat

• Copies binned client files from bin\data\bin\ to binned\bin\.
• Copies binned server files from bin\data\server\bin\ to binned\server\bin\.
• Cleans old binned files first.
• Produces candidate loose-bin output only — this is not final client release.

Step 8 — Build PIGG archives

• Canonical method: City Hall native PIGG builder.
• Fallback method: local/manual patch PIGG batch file.
• Uses bin\tools\pig.exe

Purpose:

• Pack approved loose bins/assets into PIGG archives for production distribution.
• The client should receive PIGGs in the patch directory, not loose bins.
• City Hall must package narrow patch PIGGs only — do not wildcard-copy every generated .bin into a production patch PIGG.

Approved client patch PIGG bins (e.g. patch_bin.pigg):

bin\clientmessages-en.bin
bin\product_catalog.bin
bin\costume.bin

Approved serverbin patch PIGG bins (e.g. patch_serverbin.pigg):

server\bin\powers.bin
server\bin\powersets.bin
server\bin\powercats.bin
server\bin\VillainDef.bin
server\bin\product_catalog.bin
server\bin\messages-en.bin

sequencers.bin
ent_types.bin
behaviors.bin
behavioralias.bin
animlists.bin
fxinfo.bin
menuAnimations.bin
seqstatebits.bin

PIGG naming reference

Current Jenkinsfile output names:

piggs\v2_bin.pigg
piggs\v2_serverbin.pigg

Existing local output also includes piggs\v2_textures.pigg.

Example configurable stable patch names:

piggs\patch_bin.pigg
piggs\patch_serverbin.pigg
piggs\patch_textures.pigg
piggs\patch_login.pigg

Step 9 — Promote client PIGGs

Copy approved client PIGGs to <ClientRoot>\ouro\:

• patch_bin.pigg (or your configured client patch PIGG name).
• patch_serverbin.pigg (or your configured serverbin patch PIGG name).
• patch_textures.pigg (optional — when texture assets are packaged).
• patch_login.pigg (optional — when login-screen assets are packaged).

Step 10 — Promote server output

The server may run raw bins. Promote approved server bins to the live server data tree only:

<ServerRoot>\data\

The serverbin PIGG is part of the client patchdir PIGG set and should be copied to <ClientRoot>\ouro with the other patch PIGGs. This does not mean loose server bins should be copied to the client — loose server bins remain server-only.

Step 11 — Mirror client and generate manifest

1. Mirror the entire client folder to <WebRoot>\public\game\.
2. Generate a new manifest from https://www.example.com/manifest.
3. Test from launcher.

Converting power icons with City Icon

1. Prepare source images (PNG or TGA, 32×32 or 64×64).
2. Create an output directory literally named texture_library (e.g. C:\Output\texture_library\).
3. Run City Icon:

   CityIcon.exe --convert --mode icons --source "C:\InputIcons" --output "C:\Output\texture_library"

4. Output appears in C:\Output\texture_library\GUI\Icons\powers\.
5. Verify the header (first 100 bytes should show texture_library/GUI/Icons/powers/).

Converting login screen with City Icon

1. Prepare source image (PNG, recommended 1920×1080).
2. Create an output directory literally named texture_library.
3. Run City Icon:

   CityIcon.exe --convert --mode login --source "C:\Input\loginscreen.png" --output "C:\Output\texture_library"

4. Output: C:\Output\texture_library\GUI\CREATION\HybridUI\LoginScreen\COH_LogInScreen_Background.texture
5. Verify the header shows texture_library/GUI/CREATION/HybridUI/LoginScreen/...

CORRECT: --output "C:\temp\texture_library"  ->  Path: texture_library/GUI/...
WRONG:   --output "C:\temp\output"            ->  Path: output/GUI/...

Why update the manifest?

The launcher downloads game files based on manifest.xml. If file sizes or MD5 hashes don't match, the launcher will either redownload files unnecessarily or skip files that actually need updating.

Manual update steps

1. Open <WebRoot>\public\manifest.xml
2. Find the file entry to update:

   <file name="data/texture_library/GUI/Icons/Powers/Filename.texture"
         size="OLD_SIZE" md5="OLD_MD5">

3. Calculate the new MD5:

   (Get-FileHash "filepath" -Algorithm MD5).Hash

4. Get the new file size:

   (Get-Item "filepath").Length

5. Update the entry:

   <file name="data/texture_library/GUI/Icons/Powers/Filename.texture"
         size="NEW_SIZE" md5="NEW_MD5">

6. Update the version tag: <version>YYYYMMDDTHHMMSS</version>
7. Save the manifest.

Automated update (update_manifest.js)

node update_manifest.js

• Automatically updates powers.bin and VillainDef.bin hashes.
• Updates version timestamp.
• Located at <ToolsRoot>\update_manifest.js

After binning, deploy to all locations

Do not deploy

Verify deployment

This is the recommended direct path for a full release using City Hall and City Icon. It is based on the confirmed stable process:

• Source content is checked before deployment.
• Textures are converted with correct texture_library headers.
• Content is merged, not blindly overwritten.
• Official full binning batch files are used.
• Generated bins are treated as candidate output.
• Only approved narrow bins/assets are packed into patch PIGGs.
• Volatile bins are blocked from client patch PIGGs.
• Client distribution is PIGG-first.

Required tools

• City Hall — validation, controlled merges, official full binning, protected-bin comparison, PIGG packaging, and promotion.
• City Icon — converting PNG / JPG / TGA / DDS source images into .texture files with correct embedded texture_library paths.
• Merge Tool — used by City Hall (or manually when troubleshooting) to merge data into the binning server source tree.
• Binning server tools — mapserver_debug.exe, ouroboros_debug.exe, pig.exe, and the official numbered batch files.

Folder expectations

• <StagingRoot> — unfinished or newly received content. Fix issues here first.
• <DeploymentRoot> — clean content ready to merge into the binning server.
• <SourceFilesRoot> — canonical archive of content that has successfully binned and tested.
• <BinServerRoot> — i2401 binning server root containing bin\, binned\, piggs\, and the official batch files.
• <ClientRoot> — full client folder that will be mirrored to the launcher public game folder. Patch PIGGs normally live under <ClientRoot>\ouro\.
• <ServerRoot> — the live server root. Approved raw server bins are promoted to <ServerRoot>\data\.
• <WebRoot>\public\game — launcher distribution mirror. Mirrors <ClientRoot>; never receives loose server bins.

Step 1 — Prepare content in staging

1. Place new powersets, defs, message stores, textures, PFX, sequencers, or other content into <StagingRoot>.
2. Do not put loose files directly into the binning server source folders.
3. Check for obvious issues before moving forward:
   • Missing .ms display strings.
   • Raw P-number labels showing in source.
   • Missing referenced PFX files.
   • Missing referenced entity or pet definitions.
   • Incorrect icon names or paths.
   • Files placed at the wrong folder depth.
   • New files that should be merged into existing canonical files.

Step 2 — Convert textures with City Icon

Use City Icon before binning whenever content includes icons, login screens, or other custom textures.

Power icons

1. Open City Icon.
2. Choose Power Icons mode.
3. Select one or more images, or a folder of images.
4. Set output to a folder literally named texture_library.
5. Convert.
6. Expected output: texture_library\GUI\Icons\powers\*.texture

Login screen

1. Open City Icon.
2. Choose Login Screen mode.
3. Select the source login image.
4. Set output to a folder literally named texture_library.
5. Convert.
6. Expected output: texture_library\GUI\CREATION\HybridUI\LoginScreen\COH_LogInScreen_Background.texture

Folder conversion

• Use Folder mode when converting an existing texture_library tree.
• City Icon should preserve the relative folder structure under texture_library.

Step 3 — Move clean content to deployment

1. After staging content is corrected, move or merge it into <DeploymentRoot>.
2. Keep Deployment clean — it should contain only content intended for the next binning run.
3. If content belongs to an existing canonical data file, merge it into the relevant canonical file rather than keeping duplicate competing files.
4. Place converted texture_library output into Deployment so City Hall can stage it for texture PIGG packaging.

Step 4 — Open City Hall and check settings

1. <BinServerRoot> points to the binning server root.
2. <StagingRoot> points to the staging folder.
3. <DeploymentRoot> points to the deployment folder.
4. <SourceFilesRoot> points to the canonical source/archive folder.
5. <ClientRoot> points to the client folder.
6. <ServerRoot> points to the live server folder.
7. <WebRoot>\public\game is the launcher distribution target, if configured.
8. Known-good baseline output is configured.
9. Protected bins are enabled.
10. PIGG names are set to your stable patch names.

Step 5 — Run City Hall validation

1. Validate Staging.
2. Fix any reported issue before continuing.
3. Run the Staging → Deployment merge dry-run.
4. If the dry-run is clean, run the real Staging → Deployment merge.
5. Validate Deployment.
6. Fix any reported issue before continuing.

Step 6 — Merge deployment into bin server source

Important canonical destinations:

.powers      ->  <BinServerRoot>\bin\serverdata\Defs\powers\
.powersets   ->  <BinServerRoot>\bin\serverdata\Defs\powers\
.categories  ->  <BinServerRoot>\bin\serverdata\Defs\powers\
.ms          ->  <BinServerRoot>\bin\serverdata\texts\English\Powers\
texture_lib  ->  <BinServerRoot>\bin\localdata\texture_library\

Step 7 — Run the official full binning chain

1. 1-delete-old-bins.bat
2. 2-rebuild-server-bins.bat
3. 3-rebuild-client-bins.bat
4. 8-copy-product-catalog.bat
5. 9-copy-binned-files.bat

Step 8 — Compare generated bins against baseline

Expected bins may include:

powers.bin
powersets.bin
powercats.bin
VillainDef.bin
product_catalog.bin
messages-en.bin
clientmessages-en.bin
costume.bin

Protected bins must be reviewed carefully and blocked by default:

sequencers.bin
ent_types.bin
behaviors.bin
behavioralias.bin
animlists.bin
fxinfo.bin
menuAnimations.bin
seqstatebits.bin

Step 9 — Build patch PIGGs with City Hall

City Hall should call <BinServerRoot>\bin\tools\pig.exe and stage and build only approved patch contents:

• Client patch PIGG — approved narrow client bins only. Must not include volatile protected bins.
• Serverbin patch PIGG — approved power/server data bins needed by the client patchdir. Loose server bins must not be copied into client data folders.
• Texture patch PIGG — approved texture_library content, including custom icons. Build only when texture assets exist.
• Login patch PIGG — only the login background texture. Build only when login assets exist.

Step 10 — Promote approved output

Client

1. Copy approved patch PIGGs into <ClientRoot>\ouro\.
2. Do not copy loose client bins into <ClientRoot>\data\bin\.
3. Do not copy loose server bins anywhere under <ClientRoot>.

Server

1. Promote approved raw server bins to <ServerRoot>\data\.
2. Keep server-only raw bins server-side.

Launcher / public game folder

1. Mirror <ClientRoot> to <WebRoot>\public\game\.
2. Do not union old files with new files if that leaves stale content behind.
3. The public game folder should represent the current client package exactly.

Step 11 — Generate the manifest

1. Generate a fresh manifest from the launcher/admin manifest panel.
2. Confirm the manifest contains the new or replaced patch PIGGs.
3. Confirm file sizes and hashes match the actual files.
4. Do not rely on old loose-bin manifest update scripts for PIGG-first releases.

Step 12 — Smoke test before announcing release

1. Launcher downloads the expected patch files.
2. Client starts without texture misnamed errors.
3. Character creator opens.
4. Relevant archetypes/powersets appear.
5. New icons render correctly.
6. New login screen or custom textures render correctly, if changed.
7. A character can load into a map.
8. Any new powers can be selected and activated.
9. No protected-bin related crashes appear.

Final release checklist