Project Zomboid Studio

April 24, 2026 · View on GitHub

Original project repository: Konijima/project-zomboid-studio

This is a CLI tool for creating and maintaining Lua mods for Project Zomboid with ease. Visit the link above for:

Project Zomboid Legacy support (Build 41)

Key Changes in This Branch

Compatibility in this branch: Project Zomboid b42.17.0 MP
Added AGENTS.md with build commands, architecture overview, and code style guidelines
Updated mod ID formatting to be Unix-compatible (Windows and Linux):
- Spaces converted to underscores: "Teleportal Prototype" → teleportal_prototype
- Special characters removed: "My-Cool Mod!" → my_cool_mod
- Maintains camelCase without conversion: "TeleportalPrototype" → teleportalprototype
Reworked scaffolding to rely on cached templates with explicit refresh via --force-update or pzstudio update
Removed the legacy installLibraries() fallback from intended scaffolding behavior in favor of template-driven project creation
Added .pzstudioignore filtering for scaffold and build flows, with built-in maintenance exclusions such as **/.gitkeep
Build 42 Layout Support (NEW):
- Added pzstudio modinfo generate command to author mod.info files directly in your source tree.
- Supports Build 42 nested layouts: generates into common, 42, or version-specific branch folders containing lua.
- Automatically ignores root-level mod.info for projects using the new nested layout.
- Respects build.modInfo project configuration to skip or automate metadata generation.
Updated mod.info output path to respect branch-based layouts in both source and workshop builds.
Enhanced build command to create dual workshop outputs:
- Main workshop: {projectTitle} with standard mod IDs and configured visibility.
- Dev branch workshop: {projectTitle} - dev_branch with _dev suffix on mod IDs.
- Each mod in dev branch has its ID field prefixed in the generated metadata.
- Dev branch workshop always sets visibility to unlisted regardless of project.json settings.
- Dev branch workshop title appends - dev_branch suffix: title={projectTitle} - dev_branch.
- Dev branch workshop.txt has no id= field (excluded automatically).
Robust I/O Validation & Migration:
- Implemented runtime validation for project.json and config.json with descriptive Where-What-Why error reporting.
- Added pzstudio migrate command to safely upgrade legacy configuration files while preserving unknown fields.
- Expanded IModConfig with support for pack, tiledef, url, versionMin, and versionMax.
- Added --verbose mode for detailed diagnostic logging across all commands.
- Stubbed experimental watch command as "Not implemented yet!" to avoid instability.
Updated documentation to reference original project repository

4. Quality Workflows

Maintain code quality using the following commands:

# Run linting
pnpm run lint

# Run linting and fix auto-fixable issues
pnpm run lint:fix

# Run unit tests
pnpm run test

# Run tests in watch mode
pnpm run test:watch

# Run tests with coverage
pnpm run test:coverage

The automated test suite currently covers deterministic library logic including argument parsing, expectation validation, and shared helper utilities. Manual verification remains required for terminal UI, file watching, and integration-heavy command flows.