fwolfe/zomboid-modding-guide

Guide to modding various aspects of Project Zomboid

Project Zomboid Modding Guide

This document is very much a Work-In-Progress.

The goal of this guide is to have a one-stop-spot for how to mod TheIndieStone's Project Zomboid, covering all aspects of modding, tools required, tips and tricks, as well as tutorials, examples and useful code snippets.

Much of the current modding information is in outdated tutorials, scattered in forum posts, etc. Ideally by hosting a universal guide on Github, it can be collected all in one spot and anyone can contribute new information, corrections or updates as PZ's API changes over time.

This guide is not meant to be a tutorial (although will contain tutorials), but a reference for both new and experienced modders.

Contributions to this guide are more then welcome.

Contents

• Introduction
  • Overview
  • Required Tools
• Mod Structure
• The Scripts
• The Code
• Translations
• The Maps
• The Models

---

---

Introduction

---

Overview

"Modding" is a vague term covering multiple areas. Many of these areas sometimes overlap but should be considered separate as they require different skill sets and knowledge.

Adding basic items and recipes

This can be done with little (or none) coding knowledge and minimal tools. Item and recipe definitions are inside standard .txt documents, although these txt files must conform to a specific syntax and style.

Code changes, advanced items and recipes

Being able to add on to or edit Zomboid's code is a major bonus, and where the real power of mods comes in. PZ is coded in a mixture of Java (the main engine) and Lua (the moddable components).
Knowledge of the Lua programming language is HIGHLY advised. You'll save yourself a lot of grief and effort learning Lua before diving into this area. Fortunately Lua is a simple language by design, and relatively easy to learn.
The internet is scattered with tutorials.

3d Models

For build 40 and below, 3d art for Project Zomboid primarily consists of weapon models and vehicles. At this time all 3d mods fall into one of these 2 types. Models are in a custom .txt format. The processes of exporting from your modelling app and importing in PZ is fairly simple, though initial positioning, scaling and rotation can take a bit of tweaking. Minor coding is required to tell Zomboid to load the custom models.

Build 41 uses the .X and .fbx formats.

Textures

Map Making

---

Required Tools (software)

This section should describe the various software tools required for various areas, and provide url links for the more common software used

For the most part, you are free to use what ever tools you want. The exception is custom map creation, where you are currently limited to the tools released by TIS.

Text Editors:

Used in all areas of modding. Notepad++ is often the preferred editor for windows OS's (it also runs amazingly well on linux with wine)

3d Modelling:

Used for the creation of custom items, vehicles and weapons. Blender is the common choice as its free and import/export scripts for PZ's older (build 40) model format exist.

Image Editor:

If your doing custom icons, textures, maps or 3d models you'll need one of these. Paint.NET, Photoshop and GIMP are the most used, but whatever supports the .png format will work.

Custom Mapping:

TODO: list tools used in mapping.

---

Topics

• Mod Structure
• The Scripts
• The Code
• Translations
• The Maps
• The Models

zomboid-modding-guide's Issues

Map modding section needs completion

Map creation techniques and tools need detailing, as well as tips, tricks, and gotchas by someone with a fair amount of expertise in this field. A actual tutorial for this would be nice as well. I suspect this will be very image heavy (screenshots).

Ideally the main body of the section should be in github style markdown. For separate tutorials markdown should be preferred however some flexibility should be considered for easier viewing offline.

good references to read to know the API

Discussed in #14

^{Originally posted by SamiSul April 11, 2023}
In the guide I noticed the line:
Official documentation is outdated and sparse. The most effective way to find what's available to you is by reading the code.
Where can I find code to read? Thanks :)

3d modelling section needs completion

The guide is currently completely lacking in 3d modelling aspects such as importing for different object types (vehicles, weapons, clothes). Raw 3d modelling tutorials aren't really required, however application specific tutorials on exporting would be useful.
Problems like the blender version vs .x format issues should be listed and detailed.

Both build 40 and 41 methods could be outlined, its highly likely build 40 will continue to be in use for some time due to system requirement difference.

Since build 41 is still in beta at this point, any 41 info may end up becoming obsolete so this area could be considered low priority, but would be extremely useful for new modders.

Document the hook system

Write information about how the hook system works:
https://github.com/FWolfe/Zomboid-Modding-Guide/blob/master/api/README.md#the-hook-system

Recommend IntelliJ IDEA

Under Required Tools (software) we are currently recommending Notepad++ as the preferred text editor, however as mentioned here in PR #4 we should be promoting the use of IDE over text editors such as Notepad++.

The best (or the smartest) Java IDE on the market is IntelliJ IDEA.

Translation section needs completion

The section covering translations is non-existent. This needs to cover the file structure, how to build proper translation support into mods, how to translate 3rd party mods, and use of the API's getText() function including string formatting positional
arguments.

API/README.md has a broken link

Line 211

./JavaClasses.md does not exist it would seem.

I'm looking through commits to see why it was removed.

Commit 8b73a72 shows that it's created but, somewhere along the line it's been dropped.

I'm guessing this was force pushed from a local clone and the JavaClasses.md got dropped then.

Recommend modding communities

Since modding is generally a community effort (including this guide) it would be a good idea to provide links to existing modding communities. At the very least we should mention the IndieStone Discord server and its #modding channel.