Tutorial: Creating Project Zomboid mods using PZPW
PZPW stands for Project Zomboid PipeWrench. It is a Node command-line tool used to create and manage PZPW projects.
This tool allows modders to create mods written in Typescript and easily generate their mods and workshop directory for publishing.
- CLI: https://www.npmjs.com/package/pzpw
- Compiler: https://www.npmjs.com/package/pzpw-compiler
- Template: https://www.npmjs.com/package/pzpw-template
Before starting, make sure you have Node.js and npm (Node Package Manager) installed on your system. If you don't have them installed, you can download Node.js here which includes npm.
To install PZPW globally, run the following command in your terminal or command prompt:
npm i -g pzpw
To create a new mod, run the following command:
pzpw new "my-mod-id" "My Mod Name" "My Name"
Now, wait for PZPW to finish preparing your new mod environment. Once it's done, you can start working on your mod!
After PZPW has finished setting up your mod environment, you should have a new directory named my-mod-id. To open this directory in Visual Studio Code (VSCode), follow these steps:
- Launch Visual Studio Code.
- Click on
Filein the menu bar. - Select
Open Folder...from the dropdown menu. - Navigate to the
my-mod-iddirectory. - Click on the
Select Folderbutton.
or right-click in the directory to open it with Visual Studio Code
Now your mod directory is open in VSCode, and you can start developing your Project Zomboid mod!
There are two important directories in your mod project:
The assets directory is where you should store any asset files your mod requires, such as images, sounds, text files, and so on. Organizing these files in the assets folder will make it easier to manage and maintain your mod.
The src directory contains the Typescript files for your mod. This is where you'll write your code, create new classes, and define the logic for your mod.
To better understand the assets folder, let's dive deeper into its structure:
The assets/mods/ directory is where you should set your mod icon and poster. Organize your additional assets inside the media sub-directory. This can include textures, sounds, and other files used by your mod.
The assets/workshop/ directory is where you should place your workshop preview image and description. The preview image is what users will see when browsing the Steam Workshop, and the description will provide them with more information about your mod.
In the assets/LICENSE.txt file, define your mod's license. This file outlines the terms and conditions under which your mod can be used, modified, and distributed. Choose an appropriate license for your project to ensure proper usage.
The src directory is where you write your mod's Typescript code. It's divided into three main sub-directories:
The src/client/my-mod-id/ directory contains the Typescript files for the client-side logic of your mod. This is where you should implement any functionality that will run on the player's computer, such as UI elements, visual effects, or client-side game mechanics.
The src/server/my-mod-id/ directory contains the Typescript files for the server-side logic of your mod. This is where you should implement any functionality that will run on the server, such as managing multiplayer interactions, synchronizing game states, or enforcing game rules.
The src/shared/my-mod-id/ directory contains the Typescript files for the shared logic of your mod. This is where you should implement any functionality that will be used by both the client-side and server-side scripts, such as data structures, utility functions, or common game mechanics.
Now let's create a sample client-side script for your mod. In the src/client/my-mod-id/ directory, create a new file called my-first-script.ts. Add the following code to the file:
import { onGameStart } from "@asledgehammer/pipewrench-events";
onGameStart.addListener(() => {
print("Hello World!");
});This simple script imports the onGameStart event from the @asledgehammer/pipewrench-events package. It then adds a listener to this event, which will print "Hello World!" to the console when the game starts.
In your mod project, you'll find a file named pzpw-config.json. This file is used to set all the data that would normally be found in your mod.info file. The data in this file will be automatically generated, so you only need to focus on setting the information in the JSON file.
The pzpw-config.json file uses a schema located at https://raw.githubusercontent.com/Konijima/pzpw-config-schema/master/pzpw-config.schema.json, which provides intellisense to help you understand what data you can add and how it should be structured.
The file has two main parts: mods and workshop.
The mods object contains information about the mods that are available in this project. You can set various properties such as the mod's ID, name, author, and more.
The workshop object contains information about your workshop project. Inside this object, there is an array named mods which allows you to include the mods that you need in the published workshop entry. This helps you manage and bundle multiple mods together for publishing.
By configuring your pzpw-config.json file properly, you can streamline the process of managing your mod's data and publishing it to the Steam Workshop.
Before you can compile your mod project, you need to install and set up the pzpw-compiler. Follow these steps to prepare the compiler:
The first time, you will need to install the pzpw-compiler using the following command:
npm install -g pzpw-compiler
Once the compiler is installed, you need to set the cache directory of your Project Zomboid location. Use the following command (replace the path with the correct one for your system):
pzpw-compiler cachedir set "C:\Users\Konijima\Zomboid"
Now that the compiler is set up, you can start compiling your mod. There are two ways to compile:
- Compile mods into your Zomboid/mods directory:
pzpw-compiler mods
- Compile mods into your Zomboid/workshop directory:
pzpw-compiler workshop
Choose the appropriate method based on your needs. After compiling, your mod will be ready for testing and distribution!
If you want to add an additional mod to your existing PZPW project, you can do so by using the pzpw add command. For example, to add a mod called "Additional Mod" with the ID "additional-mod", run the following command:
pzpw add "additional-mod" "Additional Mod"
This command will create a new mod within your PZPW project and set up the necessary directories and files. You can then start developing the additional mod alongside your existing mod.
Remember to update your pzpw-config.json file to include the new mod in the mods object and, if necessary, add it to the workshop object as well.
