PZ Character Blender

Build a real Project Zomboid character in Blender

Same body meshes, clothing, hair, beards, skin tones and animation clips as Build 42 itself — ready to customize, pose and play in the viewport.

Quick start  ·  Features  ·  How it works  ·  Details

pzcharacterblender.mp4

---

🚀 Quick start

Option A  ·  Full setup

setup.bat

One script does all of it:

1	Checks Python is on your PATH
2	Finds your ProjectZomboid folder — folder picker if it can't guess
3	Extracts the game's models, textures and clips
4	Offers to copy the add-on into Blender for you

⏱️  About ten minutes, almost all of it the extract.

Option B  ·  Drag a zip in

Already extracted assets/characters/? Skip the setup script — build the add-on zip and drag it straight into a Blender window, where it installs itself.

Make the zip:

package_addon.bat

That writes pz_character_viewer.zip next to setup.bat. It isn't committed to the repo — it's a build artifact, and a stale one silently keeps reinstalling old code, so it's always built fresh. Prebuilt zips are attached to each release.

📦  No script? Right-click src/addon/pz_character_viewer, then Send to → Compressed (zipped) folder. Same result. The script is easier, and it skips __pycache__ for you.

Then drag it in, and point the add-on at your data: open the sidebar, and next to (not set) at the top of the panel click the 📁 folder button. Pick the assets/characters folder — it sits right beside setup.bat.

Blender remembers it from then on.

---

Then, in Blender

1	Edit → Preferences → Add-ons Enable PZ Character Viewer
2	Press N in the 3D viewport Opens the sidebar
3	Open the PZ Character tab
4	Click Randomize 🎲

Prefer to install by hand?

DETAILS.md carries the manual install steps, every extractor option, how to re-run it later, the test suite, and the internals of the add-on.

---

✨ Features

👕  Full outfit builder Body, underwear, tops, bottoms, feet, accessories and more — cycled layer by layer.	🎲  Randomize Rolls a fresh outfit using the game's own weighting and exclusivity rules.
🎨  Recolour Any garment the game itself lets you recolour, with the game's own muted-random-colour logic.	🧍  Line-ups Release characters into a row, instead of overwriting your last one.
🏃  Real animation clips Browse, search, pin and play the game's own.	🔀  Clip layering Two clips at once — base + overlay — with real upper/lower body bone masks.

📖  DETAILS.md — exactly how each of these works

🗡️  weapon_attachment.md — how PZ attaches a held weapon, and the two defects that currently make one sit wrong

---

🧩 How it's built

Two halves, connected only by a folder of extracted files:

     your PZ install                                   Blender
            │                                             ▲
            ▼                                             │
   ┌──────────────────┐      ┌───────────────┐     ┌──────────────┐
   │  src/extractor/  │ ───► │    assets/    │ ──► │  src/addon/  │
   │   Python, once   │      │  characters/  │     │   the add-on │
   └──────────────────┘      └───────────────┘     └──────────────┘
     reads the game            gitignored            never touches
                                                     the install

Part	What it does
src/extractor/	Stdlib-only Python. Reads your PZ install once, writes assets/characters/.
src/addon/pz_character_viewer/	A Blender add-on. Reads assets/characters/. Never touches the game install.

⚖️  You need a legal Build 42 install. Nothing extracted is redistributable, so assets/ is gitignored — everyone who clones this runs the extractor against their own copy. See LEGAL_DISCLAIMER.md.

---

📋 Requirements

🐍	Python 3 on PATH	For the extractor. No pip packages needed.
🟠	Blender	For the add-on. Developed against 5.2.
🧟	Project Zomboid Build 42	The source of everything. Needs media/models_X.
🪟	Windows	For the .bat scripts. Not needed — see below.

Running on Linux or macOS

The add-on is plain Python and works anywhere Blender does. Only the convenience wrappers — setup.bat, extract.bat, package_addon.bat and scripts/pick_folder.ps1 — are Windows-only.

Everything they wrap is portable. Run the extractor directly:

export PZ_GAME_DIR="/path/to/ProjectZomboid"
mkdir -p assets/characters
python3 src/extractor/pz_characters.py --out assets/characters/characters.pzc
python3 src/extractor/pz_animscript.py --out assets/characters/locomotion_manifest.json

The second pass takes about five seconds and supplies the upper/lower bone masks for partial-body animation preview. The add-on runs without it.

Then build the add-on zip — package_addon.py is stdlib Python too:

python3 package_addon.py

and install it as in Option B above.

---

🌱 Where this came from

This is the character half of the pz_tile_viewer add-on in pz-testing, split out to stand alone.

Nothing in this folder needs Godot — though the same extracted data is also read by a Godot runtime (CharacterAssetRegistry.gd) elsewhere in that project.

---

⚖️ Licence

Released under the GNU General Public License v3.0 — forks and derivatives must stay open source under the same licence.

That covers this codebase only. It grants no rights to The Indie Stone's models, animations, textures or trademarks: extracted output is gitignored, and redistributing it is between you and them.

LEGAL_DISCLAIMER.md has the full position.

_{Not affiliated with, endorsed by, or sponsored by The Indie Stone.
Project Zomboid and related marks are their property.}