Modding: Difference between revisions

From PZwiki
m (→‎Mapping resources: Add link to my WIP modding tool)
 
(89 intermediate revisions by 21 users not shown)
Line 1: Line 1:
{{languages|Modding}}
{{Header|Modding}}
{{header|Community|Modding|version=Version 41|incver=68}}
{{Page version|41.78.16}}
[[File:SpiffosWorkshop.png|link=https://steamcommunity.com/app/108600/workshop/|frame|right|Spiffo's Workshop is the home of [[Project Zomboid]] mods on [[Steam]].]]
[[File:SpiffosWorkshop.png|link=https://steamcommunity.com/app/108600/workshop/|frame|right|Spiffo's Workshop is the home of [[Project Zomboid]] mods on [[Steam]].]]
== '''Terms & Conditions''' ==
'''By purchasing Project Zomboid, you are permitted to:'''
*Change or distribute the base files or contents in any way you like, provided that those changes do not result in you making Project Zomboid available to play or download (this includes making it available open source), or are for the purposes of cheating, unauthorised hacking, exploits or griefing other people or are malicious or illegal in intent or practice.
*Use art, music, video footage or other assets of Project Zomboid for creative purposes in any way you like providing the end result is related in some way to promoting Project Zomboid, is for non-commercial use only (unless we agreed otherwise with you) and states Project Zomboid as its influence and origin by supplying the following wording prominently with the assets: “Thanks to The Indie Stone for creating Project Zomboid http://projectzomboid.com/), which made this possible. This is an unofficial fan production for non-commercial purposes made under the Indie Stone Terms [link to these terms]“


'''You are not permitted to:'''
=='''Terms & Conditions'''==
*Modify the base files of Project Zomboid to include malicious code or other naughtiness.
By playing Project Zomboid, you agree to the '''[https://projectzomboid.com/blog/support/terms-conditions/ Terms & Conditions]'''.
*Distribute Project Zomboid yourself, or host its download. In order to ensure the game’s integrity we recommend it should only ever be downloaded from established portals on which we’ve placed it (e.g. Steam).


'''In terms of the modding of PZ, you also agree that:'''
By modding Project Zomboid, you also agree with the '''[https://projectzomboid.com/blog/modding-policy/ Modding Policy]'''.
*The Indie Stone reserve the right to implement any features in the game irrespective of whether mods exist that accomplish the same goal.
*PZ modders are solely responsible for their mod, including (but not limited to compliance with any hosting platforms (such as Steam Workshop). They are also responsible for obtaining third party consents for any third party materials in the mod. Legally, we have to ask that modders to ‘represent and warrant’ (i.e. promise legally) that their mod is their own original work and any third party contents are fully and properly licensed by the modder.
*Creation of mods is subject to our [https://theindiestone.com/forums/index.php?/topic/54-modding-rules-guidelines/&do=findComment&comment=530 modding guidelines], which may be updated from time to time with any technical requirements regarding how PZ mods must work.
*Project Zomboid modders are free to receive monetary/gift donations from the players who use their releases, and appreciate the time and effort put into them. However having mods created exclusively for those who choose to donate (or separate ‘in-mod’ content and bonuses) is not allowed. Mod creators cannot sell modifications to Project Zomboid.


==How to install/play mods==
===Key restrictions===
[[File:Mod unchecked.jpg|thumb|right|350px|Mod menu]]
*The Indie Stone reserves the right to implement any features in the game irrespective of whether mods exist that accomplish the same goal.
To get a full tutorial on how to install mods, see [RoboMat's tutorial on the forums].
*Modders are solely responsible for their mod, including (but not limited to compliance with any hosting platforms (such as Steam Workshop). They are also responsible for obtaining third party consents for any third party materials in the mod. Legally, we have to ask that modders to ‘represent and warrant’ (i.e. promise legally) that their mod is their own original work and any third party contents are fully and properly licensed by the modder.
*Creation of mods is subject to our [https://projectzomboid.com/blog/modding-policy/ modding policy], which may be updated from time to time with any technical requirements regarding how PZ mods must work.
*Project Zomboid modders are free to receive monetary/gift donations from the players who use their releases, and appreciate the time and effort put into them. However, having mods created exclusively for those who choose to donate (or separate ‘in-mod’ content and bonuses) is not allowed. Mod creators cannot sell modifications to Project Zomboid.


To start a mod up, first make sure the mod is installed in the correct directory. Once you have done this, start up Project Zomboid. Once you get to the main menu, down at the bottom of the screen when you see "Survival" and "Sandbox" you will also find a menu option called Mods. Click on it, which will then lead you to the mod menu.
==Installing and using mods==
*[[Installing mods]] - how to install mods for [[Steam]] or [[GOG]] version of the game.
*[[Using mods]] - how to enable and configure mods.
*[[Mod problems solution]] - what to do if mods do not work well or break the game.
*[[Testing mods in multiplayer]] - guide about setting up the mod to work on the server.
<span style="font-size: 120%; font-weight: bold; color: green;">Tip: </span> join [https://discord.gg/theindiestone The Indie Stone Discord server] for get access to '''#mod_support''' channel, where you can ask question about using mods.
 
To start a mod up, first make sure the mod is installed in the correct directory. Once you have done this, start up Project Zomboid. Once you get to the main menu, down at the bottom of the screen when you see menu options you will also find a menu option called MODS. Click on it, which will then lead you to the mod menu.


In there you should see the list of mods that you have installed. Double click on the mod you wish to start and a green tick should appear next to the mod.
In there you should see the list of mods that you have installed. Double click on the mod you wish to start and a green tick should appear next to the mod.
Next thing to do is shut down Project Zomboid and start it up again. Once started your mod should now be ready to go. Instructions on using the mod are usually contained in README's or information in the thread.
Next thing to do is shut down Project Zomboid and start it up again. Once started your mod should now be ready to go. Instructions on using the mod are usually contained in README's or information in the thread.


==Current mods==
==Current mods==
{{Main|Mods}}
*[https://steamcommunity.com/app/108600/workshop/ Spiffo's Workshop]
*[https://steamcommunity.com/app/108600/workshop/ Spiffo's Workshop]
*[https://theindiestone.com/forums/index.php?/forum/58-mods/ Completed Mods]
*[https://theindiestone.com/forums/index.php?/forum/58-mods/ Completed mods]
*[https://theindiestone.com/forums/index.php?/forum/59-wip/ Work-in-Progress Mods]
*[https://theindiestone.com/forums/index.php?/forum/59-wip/ Work-in-Progress mods]


==Modding tutorials==
==Creating mods==
{| class="pztable-com sortable" style="width:50%;"
In modding for PZ, there are several main directions:
! style="width:60%;" | Tutorial
*'''Changing scripts''' - scripts in the game describe the parameters of items, recipes, and vehicles. Making a mod that changes the values ​​of items, vehicles, a recipe, or adds a new item is not a difficult task. This does not require programming knowledge; any text editor may be used. Scripts are in .txt files and have a specific structure.
! style="width:20%;" | Author
*'''Writing Lua code''' - the main direction in PZ modding. Most mods contain Lua code. PZ is developed mainly in Java and Lua, so using Lua code in mods is closely related to the exploration of Java and Lua game code. When creating more complex mods, you will have to dive into the decompiled Java code of the game. We will cover the basics of the Lua language, but you should be familiar with the basics of programming. A general understanding of the syntax of the Java language is also desirable, as it may be necessary to explore the game code to figure out how some functions work.
! style="width:20%;" | Last updated
*'''Creating 3D models''' - at the moment, with the help of mods, you can add new models of vehicles, weapons, ordinary items, and clothes to the game. The game uses 2 model formats - .X and .FBX. For us to create mods with models, the .FBX format will be enough.
|-
*'''Creating animations''' - creating animations for the character. Includes creating an animation file and integrating it into the game.
| [https://github.com/FWolfe/Zomboid-Modding-Guide Project Zomboid Modding Guide] <small>(WIP)</small>
*'''Creating textures, pictures and icons''' - this direction complements the others. Models will need textures, items will need icons, the interface will need certain images, and maps will need textures for new tiles (new objects to be placed on the map).
| Fenris Wolf
*'''Map creation''' - creating locations, buildings, and general environments for the game. See [[#Mapping]].
| July 27, 2019
*'''Translations''' - translating the game to various languages, see [[Translations]].
|-
| [[Modding:Lua_Events|Lua Events (v41.65)]]
| co`
| {{#switch:{{REVISIONMONTH1:Modding:Lua Events}}|1=January|2=February|3=March|4=April|5=May|6=June|7=July|8=August|9=September|10=October|11=November|12=December}} {{REVISIONDAY:Modding:Lua Events}}, {{REVISIONYEAR:Modding:Lua Events}}
|-
| [https://theindiestone.com/forums/index.php?/topic/61-robomats-modding-tutorials-updated-12112013/ RoboMat's Tutorials]
| RoboMat
| July 24, 2013
|-
| [http://www.projectzomboid.com/modtools/ModdingGuide2.rtf Java Scripting Guide (very out of date, only the item and recipe sections seems to be applicable to current builds)]
| Lemmy101
| July 24, 2013
|}


====A Note Regarding Updating and/or Changing Mods====
<span style="font-size: 120%; font-weight: bold; color: green;">Tip: </span> Join [https://discord.gg/theindiestone The Indie Stone Discord server] to access the '''#mod_development''' channel, where you can ask any question about creating Project Zomboid mods.
Removing .txt and .lua files from a mod before updating them to the steam workshop may result in file mismatch errors etc. on account of steam not automatically removing said files from clients and/or servers.
One solution is manually deleting these files from the installation directories of the server and/or clients.
As well modders can avoid this issue by keeping those files, instead of removing them, but editing those files so they are empty instead of having any functional content. Including commented text explaining the reason for this in the files is also a good practice.


====A Note Regarding Linux and Case Sensitivity====
===Working tools===
Note that, unlike Windows and Mac, Linux OS is case-sensitive regarding file and directory names.
*'''Text editor''' - used to edit scripts and write code. Preferably, use editors with Lua syntax highlighting - like [https://notepad-plus-plus.org Notepad++] or [https://code.visualstudio.com/ VS Code].
Although people playing PZ on Linux is uncommon, it's far more common with server hosting services.
*'''Image editor''' - used to create icons, textures for items and tiles. For example: [https://www.gimp.org/ GIMP].
To avoid issues, make sure and follow the vanilla PZ capitalization conventions for file and directory names.
*'''3D modeling''' - used to work on 3D models. For example: [https://store.steampowered.com/app/365670/Blender Blender].
*Latest [https://theindiestone.com/forums/index.php?/topic/59675-latest-tilezed-worlded-and-tilesets-september-8-2022/ TileZed, WorldEd, and tilesets] – TileZed can also be downloaded and compiled from [https://github.com/timbaker/tiled the source code on GitHub], or they can be installed (currently only for Windows), as [https://steamdb.info/app/380880/ Project Zomboid Modding Tools] if the game is owned on Steam.


For example: with clothing mods fileguidtable.xml works for Windows and Mac, but will cause serious issue for Linux as it will be looking for "fileGuidTable.xml", as that is how the vanilla PZ file is capitalized. Although Client, Server, and Shared will work for the lua directories for non-Linux systems. it won't work for Linux; consequently use the vanilla capitalization, "client", "server" and "shared" for those.
====Modding tools====
*[https://github.com/Konijima/PZ-Libraries Decompiling & setting up auto-complete/intellisense in IDEA IntelliJ]
*[https://www.guidgenerator.com/ Free Online GUID Generator: for making GUIDs for modded clothing and outfits.]


====Javadoc reference to Project Zomboid codebase====
===Resources===
* [https://projectzomboid.com/modding/ Project Zomboid Java documentation]<!--Previous/Outdated: "https://theindiestone.com/zomboidjavadocs/"-->
*[[Lua]] - introduction and guide to using Lua language.
* [https://zomboid-javadoc.com/41.65/ Project Zomboid Java documentation v41.65 (Unofficial)]
**[[Lua Functions]]
* [https://zomboid-javadoc.com/40.43/ Project Zomboid Java documentation v40.43 (Unofficial)]
**[[Lua Events]]
* [https://zomboid-javadoc.com/39.67/ Project Zomboid Java documentation v39.67 (Unofficial)]
**[[Lua Objects]]
* [https://zomboid-javadoc.com/38.30/ Project Zomboid Java documentation v38.30 (Unofficial)]
*[[Debug mode]] - explanation how to run the game in the debug (developer) mode and how to use it.
*[[Startup parameters]] - startup parameters to launch the game with.
*[[Mod structure]] - explanation how the mod works and how to create a template for it.
*[[Folders structure]] - description of files and folders that will be useful when developing mods.
*[[File formats]] - documentation of file formats.
*[[Tile properties]] - explanation of [[tile]] properties.
*[[Room definitions and item spawns]] - explanation of room definitions, used mainly for loot distribution.
*[[Vehicle zones]] - explanation of vehicle zones.
*[[Procedural distributions]] – list of procedural distributions.
*[[Game time]] - explanation about how time in game works and GameTime class.
*[[Decompiling game code]] - guide how to study the Java source code of the game.
*[[Adding new tiles]] - guide to making new tiles.
*[[Scripts guide]] - guide for scripts (.txt files) for items, recipes, and translations.
*[[How to make a clothing mod]] - guide on how to add clothing mods.
*[[List of Tiledefs in use by mods]]


====Basic Lua language====
==Mapping==
*[[Lua_Intro|An Introduction to Lua]]
{{Main|Mapping}}
*[[Variables_Assignments_Datatypes|Variables, Assignments and Datatypes]]
{| class="wikitable theme-blue sortable" style="width: 50%;"
**[[Variables Assignments Datatypes/Task one solutions|''Test yourself solutions'']]
! style="width: 60%;" | Tutorial
*[[Arithmetic_Operators|Arithmetic Operators]]
! style="width: 20%;" | Author
*[[Relational_and_Boolean_Operators|Relational and Boolean Operators]]
! style="width: 20%;" | Last updated
*[[Concatenation_and_Length_Operators|Concatentation and Length Operators]]
*[[If_Statements_and_Functions|If Statements and Functions]]
*[[Loops|Loops]]
*[[Local_and_Global_Variables|Local and Global Variables]]
*[[Tables|Tables]]
*[[Looping_Through_Tables|Looping Through Tables]]
 
====Typescript Modding====
You can now use Typescript language to write your mods which are then compiled into lua.
* [https://github.com/asledgehammer/PipeWrench/wiki PipeWrench - Wiki]
* [https://github.com/asledgehammer/PipeWrench PipeWrench - Typing]
* [https://github.com/Konijima/pzpw PZPW - NodeJS Command-line Tool]
 
====Modding Tools====
* [https://github.com/Konijima/PZ-Libraries Decompiling & setting up auto-complete/intellisense in IDEA IntelliJ]
* [https://notepad-plus-plus.org/downloads/ Notepad++, a simple editor.]
* [https://code.visualstudio.com/ VS code, a simple editor.]
* [https://www.guidgenerator.com/ Free Online GUID Generator: for making GUIDs for modded clothing and outfits.]
 
====Important Additional Modding Resources====
* [https://discord.com/channels/136501320340209664/232196827577974784/901629291274575883 Setting up the mod.info file: a link to a post on TIS Discord explaining how.]
* [https://theindiestone.com/forums/index.php?/topic/9799-key-code-reference/ PZ Keycode references.]
* [https://github.com/MrBounty/PZ-Mod---Doc/blob/main/Items%20variables.md Variables to use when creating an item.]
* [https://github.com/MrBounty/PZ-Mod---Doc/blob/main/How%20to%20make%20a%20custom%20skill%20or%20perk.md Guide for adding a new Skill/Perk, add XP and find all perks names.]
* [https://github.com/MrBounty/PZ-Mod---Doc/blob/main/How%20to%20make%20a%20custom%20trait.md Guide for adding a custom trait.]
 
====General Additional Modding Resources====
* [https://steamcommunity.com/sharedfiles/filedetails/?id=2721464487 Guide to make a hair mod.]
* [https://www.youtube.com/playlist?list=PLwV27NP3RkJl27tveCa9EMMvAdjmGXZsf A YouTube playlist with Blackbeard's modding tutorials.]
* [https://discord.com/channels/136501320340209664/279303619277488128/864229655867031572 Photoshop Masks used for making and editing tile sprites, a link to a post on TIS Discord with the file.]
* [https://github.com/MrBounty/PZ-Mod---Doc/blob/main/How%20to%20use%20global%20modData.md Global Mod Data: How to use this powerful tool for tracking global mod data.]
* [https://github.com/MrBounty/PZ-Mod---Doc/blob/main/How%20to%20make%20a%20custom%20timed%20actions.md Guide to make a custom Timed Action.]
* [https://github.com/MrBounty/PZ-Mod---Doc/blob/main/Animation%20list.md A list of all the animation variables used in timed actions.]
* [https://github.com/Konijima/PZ-Community-API/tree/master/Contents/mods/CommunityAPI/media/lua/client/SpawnerAPI  SpawnerAPI: Allows for pending the spawns of vehicles, items, zombies in order to spawn things anywhere in the world. Upon loading the cell in question the item becomes spawned in.]
* [https://discord.com/channels/136501320340209664/232196827577974784/864843709900128278 Guide to how PZ loot distribution works on TIS Discord.]
* [https://discord.com/channels/136501320340209664/232196827577974784/899479292088569906 Spawning a tile from it's name: a link to a post on TIS Discord explaining how.]
* [https://discord.com/channels/136501320340209664/232196827577974784/891769429543759883 How to spawn loot on specific zombie outfit corpses: a link to a post on TIS Discord explaining how.]
* [https://discord.com/channels/136501320340209664/232196827577974784/890921284379246613 Item spawning examples that work: a link to a post on TIS Discord explaining how.]
* [https://discord.com/channels/136501320340209664/232196827577974784/867969619749666866 An archive with files demonstrating how to add modded sandbox options: a link to a post on TIS Discord.]
* [https://discord.com/channels/136501320340209664/232196827577974784/887879308473933884 A tool for dumping distro table contents to console.txt: a lint to a post on TIS Discord with the code.]
* [https://discord.com/channels/136501320340209664/232196827577974784/931744932656451645 How to use read/write with files in mods, useful for server ini files: a link to a post on TIS Discord explaining how.]
* [https://discord.com/channels/136501320340209664/232196827577974784/940523841027964948 A post on TIS discord with code to serialize lua table into json and vice versa.]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=2474838710 A guide on how to change Zomboid's in-game music and sound effects.]
* [https://discord.com/channels/136501320340209664/232196827577974784/869049443117314128 Looking for Error messages in the console log, a short guide on TIS Discord.]
* [https://github.com/pzstorm/capsid pzstorm/capsid - Project Zomboid mod development framework for Gradle. Apparently abandoned?]
* [https://www.youtube.com/watch?v=iv7N7gmowWU WordZed tutorial on YouTube.]
* [https://theindiestone.com/forums/index.php?/topic/28633-complete-vehicle-modding-tutorial/  Complete Vehicle Modding Tutorial on TIS forum.]
* [https://github.com/MrBounty/PZ-Mod---Doc/blob/main/Useful%20links.md Useful links.]
* [https://pzwiki.net/wiki/New_Tiles Making New Tiles for PZ.]
* [https://theindiestone.com/forums/index.php?/topic/38165-quick-guide-how-to-mod-the-loot-distribution-system-distributionslua-proceduraldistributionslua/ How To Mod The Loot Distribution System.]
 
====Clothing Modding Resources====
* [https://steamcommunity.com/sharedfiles/filedetails/?id=2648115890/ Guide for adding new clothing items with modding for build 41.]
* [https://discord.com/channels/136501320340209664/232196827577974784/945412454521913385 A list of Blood Locations used for Clothing Modding; a post on TIS Discord.]
* [https://discord.com/channels/136501320340209664/869327724504842330/931152156805955625 A list of Mask IDs used for Clothing Modding; a post on TIS Discord.]
* [https://discord.com/channels/136501320340209664/869327724504842330/954782177067937832 A Graphic to explain the masking system for clothing in PZ; a post on TIS Discord.]
 
====Old and more specific Additional Modding Resources====
* [https://github.com/Konijima/PZ-Community-API/blob/master/Contents/mods/CommunityAPI/media/lua/shared/CommunityAPI/IsoUtils.lua  isoRangeScan: This is an utility function meant for large scale scans of isoGridSquares around a given IsoObject. The scans are done fractally - that is to say from a center (or centers) outward to fill a larger area.]
* [https://theindiestone.com/forums/index.php?/topic/21923-itemzed-updated-11b/ ItemZed: for editing Item scripts and distribution files (out of date, needs to be updated to work properly with build 41)]
 
==Mapping tutorials==
{{main|Mapping}}
{| class="pztable-com sortable" style="width:50%;"
! style="width:60%;" | Tutorial
! style="width:20%;" | Author
! style="width:20%;" | Last updated
|-
|-
| [https://theindiestone.com/forums/index.php?/topic/21951-the-one-stop-tilezed-mapping-shop/&tab=comments#comment-251715 The One Stop TileZed Mapping Shop]
| [https://theindiestone.com/forums/index.php?/topic/21951-the-one-stop-tilezed-mapping-shop/&tab=comments#comment-251715 The One Stop TileZed Mapping Shop]
Line 202: Line 138:
| Atoxwarrior
| Atoxwarrior
| June 26, 2016
| June 26, 2016
|-
|}
|}


====Mapping tools====
====Mapping resources====
* [https://theindiestone.com/forums/index.php?/topic/50425-latest-tilezed-worlded-and-tilesets-march-14-2022/ TileZed, WorldEd, and Tilesets] <small>(March 14, 2022)</small>
*[https://www.pztiles.com/home PZ Tiles and a comprehensive selection of other mapping and tile making resources.]
* [https://theindiestone.com/forums/index.php?/topic/23816-latest-tilezed-worlded-and-tilesets-may-17-2018/&do=findComment&comment=270743 TileZed, WorldEd, and Tilesets] <small>(May 17, 2018)</small>
*[https://drive.google.com/drive/folders/12jQxlDlyC-fACV45oCWshZb60QHoQ6kf The build 41 base and vegetation maps for PZ.]
*[https://theindiestone.com/forums/index.php?/topic/25742-project-zomboid-basemap/ The build 40 base and vegetation maps for PZ.]
*[https://drive.google.com/file/d/1zvjxsjLi2KGwU7SVbLoH2m32UuSgCxcw/view?usp=sharing An app for replacing the zombie layers on cells.]
*[https://drive.google.com/file/d/1PRsZfmE3Ov7U9Nc_mSBv62fMFROpIIct/view?usp=sharing An app for moving the cells in maps.]
*[https://discord.com/channels/136501320340209664/279303619277488128/946017802647658586 A more recent base map for PZ.]
*[https://github.com/geromet/PZTools Distribution Explorer. Super "early access"]
 
==Notes==
===A note regarding optimization and timestamps===
This numerical information in the console.txt output log is a timestamp, such as in "LOG  : General    , 1669904231941"
If you need to evaluate the runtime impact of code it is a good metric.
 
===A note regarding updating and/or changing mods===
Removing .txt and .lua files from a mod before updating them to the steam workshop may result in file mismatch errors etc. on account of steam not automatically removing said files from clients and/or servers.
One solution is manually deleting these files from the installation directories of the server and/or clients.
As well modders can avoid this issue by keeping those files, instead of removing them, but editing those files so they are empty instead of having any functional content. Including commented text explaining the reason for this in the files is also a good practice.
 
===A note regarding Mac, Linux and case sensitivity===
Note that, unlike Windows, Mac and Linux OS are case-sensitive regarding file and directory names.
Although people playing PZ on Linux is uncommon, it's far more common with server hosting services.
To avoid issues, make sure and follow the vanilla PZ capitalization conventions for file and directory names.
 
For example: with clothing mods fileguidtable.xml works for Windows and Mac, but will cause serious issue for Linux as it will be looking for "fileGuidTable.xml", as that is how the vanilla PZ file is capitalized. Although Client, Server, and Shared will work for the lua directories for non-Linux systems. it won't work for Linux; consequently use the vanilla capitalization, "client", "server" and "shared" for those.
 
==See also==
*[[Mods]]
*[[Talk:Modding]] – for some raw guides to extracting images. The text needs to be cleaned up.
 
==External resources==
{| class="wikitable theme-blue sortable" style="width: 50%;"
! style="width: 60%;" | Tutorial
! style="width: 20%;" | Author
! style="width: 20%;" | Last updated
|-
| [https://github.com/FWolfe/Zomboid-Modding-Guide Project Zomboid Modding Guide] (WIP)
| Fenris Wolf
| January 22, 2023
|-
| [https://theindiestone.com/forums/index.php?/topic/61-robomats-modding-tutorials-updated-12112013/ RoboMat's Tutorials]
| RoboMat
| July 24, 2013
|-
| [https://www.projectzomboid.com/modtools/ModdingGuide2.rtf Java Scripting Guide (very out of date, only the item and recipe sections seems to be applicable to current builds)]
| Lemmy101
| July 24, 2013
|}
 
===Javadoc reference to Project Zomboid codebase===
*[https://zomboid-javadoc.com/41.78/ Project Zomboid Java documentation v41.78 (Unofficial)]
*[https://projectzomboid.com/modding/ Project Zomboid Java documentation v41.77]<!--Previous/Outdated: "https://theindiestone.com/zomboidjavadocs/"-->
*[https://zomboid-javadoc.com/41.65/ Project Zomboid Java documentation v41.65 (Unofficial)]
*[https://zomboid-javadoc.com/40.43/ Project Zomboid Java documentation v40.43 (Unofficial)]
*[https://zomboid-javadoc.com/39.67/ Project Zomboid Java documentation v39.67 (Unofficial)]
*[https://zomboid-javadoc.com/38.30/ Project Zomboid Java documentation v38.30 (Unofficial)]
 
===Typescript modding===
You can now use Typescript language to write your mods which are then compiled into lua. However it is not necessary to use Typescript to write mods.
*[https://github.com/asledgehammer/PipeWrench/wiki PipeWrench - Wiki]
*[https://github.com/asledgehammer/PipeWrench PipeWrench - Typing]
*[https://github.com/Konijima/pzpw PZPW - NodeJS Command-line Tool]
 
===Important additional modding resources===
*[https://discord.com/channels/136501320340209664/232196827577974784/901629291274575883 Setting up the mod.info file: a link to a post on TIS Discord explaining how.]
*[https://theindiestone.com/forums/index.php?/topic/9799-key-code-reference/ PZ Keycode references.]
*[https://github.com/MrBounty/PZ-Mod---Doc/blob/main/Items%20variables.md Variables to use when creating an item.]
*[https://github.com/MrBounty/PZ-Mod---Doc/blob/main/Make%20a%20custom%20skill%20or%20perk.md Guide for adding a new Skill/Perk, add XP and find all perks names.]
*[https://github.com/MrBounty/PZ-Mod---Doc/blob/main/How%20to%20make%20a%20custom%20trait.md Guide for adding a custom trait.]
 
===General additional modding resources===
*[https://steamcommunity.com/sharedfiles/filedetails/?id=3035712003 How To Create an Animation.]
*[https://steamcommunity.com/sharedfiles/filedetails/?id=2721464487 Guide to make a hair mod.]
*[https://www.youtube.com/playlist?list=PLwV27NP3RkJl27tveCa9EMMvAdjmGXZsf A YouTube playlist with Blackbeard's modding tutorials.]
*[https://discord.com/channels/136501320340209664/279303619277488128/864229655867031572 Photoshop Masks used for making and editing tile sprites, a link to a post on TIS Discord with the file.]
*[https://github.com/MrBounty/PZ-Mod---Doc/blob/main/How%20to%20use%20global%20modData.md Global Mod Data: How to use this powerful tool for tracking global mod data.]
*[https://github.com/MrBounty/PZ-Mod---Doc/blob/main/How%20to%20make%20a%20custom%20timed%20actions.md Guide to make a custom Timed Action.]
*[https://github.com/MrBounty/PZ-Mod---Doc/blob/main/Animation%20list.md A list of all the animation variables used in timed actions.]
*[https://github.com/Poltergeistzx/Project-Zomboid/blob/main/docs/TimedActions%20Flow%20Chart.pdf A flow chart for the Timed Actions]
*[https://github.com/Konijima/PZ-Community-API/tree/master/Contents/mods/CommunityAPI/media/lua/client/SpawnerAPI  SpawnerAPI: Allows for pending the spawns of vehicles, items, zombies in order to spawn things anywhere in the world. Upon loading the cell in question the item becomes spawned in.]
*[https://discord.com/channels/136501320340209664/232196827577974784/864843709900128278 Guide to how PZ loot distribution works on TIS Discord.]
*[https://discord.com/channels/136501320340209664/232196827577974784/899479292088569906 Spawning a tile from it's name: a link to a post on TIS Discord explaining how.]
*[https://discord.com/channels/136501320340209664/232196827577974784/891769429543759883 How to spawn loot on specific zombie outfit corpses: a link to a post on TIS Discord explaining how.]
*[https://discord.com/channels/136501320340209664/232196827577974784/890921284379246613 Item spawning examples that work: a link to a post on TIS Discord explaining how.]
*[https://discord.com/channels/136501320340209664/232196827577974784/867969619749666866 An archive with files demonstrating how to add modded sandbox options: a link to a post on TIS Discord.]
*[https://discord.com/channels/136501320340209664/232196827577974784/887879308473933884 A tool for dumping distro table contents to console.txt: a lint to a post on TIS Discord with the code.]
*[https://discord.com/channels/136501320340209664/232196827577974784/931744932656451645 How to use read/write with files in mods, useful for server ini files: a link to a post on TIS Discord explaining how.]
*[https://discord.com/channels/136501320340209664/232196827577974784/940523841027964948 A post on TIS discord with code to serialize lua table into json and vice versa.]
*[https://steamcommunity.com/sharedfiles/filedetails/?id=2474838710 A guide on how to change Zomboid's in-game music and sound effects.]
*[https://discord.com/channels/136501320340209664/232196827577974784/869049443117314128 Looking for Error messages in the console log, a short guide on TIS Discord.]
*[https://github.com/asledgehammer/Candle Candle - EmmyLua Support for PZ's Java API.]
*[https://github.com/pzstorm/capsid pzstorm/capsid - Project Zomboid mod development framework for Gradle. Apparently abandoned?]
*[https://www.youtube.com/watch?v=iv7N7gmowWU WordZed tutorial on YouTube.]
*[https://theindiestone.com/forums/index.php?/topic/28633-complete-vehicle-modding-tutorial/  Complete Vehicle Modding Tutorial on TIS forum.]
*[https://github.com/MrBounty/PZ-Mod---Doc/blob/main/Useful%20links.md Useful links.]
*[https://theindiestone.com/forums/index.php?/topic/38165-quick-guide-how-to-mod-the-loot-distribution-system-distributionslua-proceduraldistributionslua/ How To Mod The Loot Distribution System.]
*[https://github.com/demiurgeQuantified/PZEventDoc/blob/develop/docs/Events.md An up-to-date (41.78) reference to events and hooks.]
*[https://github.com/demiurgeQuantified/PZEventStubs PZEventStubs: Lua stubs for events and hooks.]
*[https://github.com/demiurgeQuantified/PZModdingGuides/blob/main/guides/SandboxOptions.md A reference for adding custom sandbox options.]
*[https://github.com/demiurgeQuantified/PZModdingGuides/blob/main/guides/GameTime.md GameTime and deltas: An explanation of time deltas and their applications in modding.]
*[https://github.com/demiurgeQuantified/PZModdingGuides/blob/main/guides/ScriptFunctions.md Documentation on functions linked to item/recipe/vehicle scripts.]
 
===Clothing modding resources===
*[https://steamcommunity.com/sharedfiles/filedetails/?id=3025955520/ Guide for adding new clothing items with modding for build 41.]
*[https://discord.com/channels/136501320340209664/232196827577974784/945412454521913385 A list of Blood Locations used for Clothing Modding; a post on TIS Discord.]
*[https://discord.com/channels/136501320340209664/869327724504842330/931152156805955625 A list of Mask IDs used for Clothing Modding; a post on TIS Discord.]
*[https://discord.com/channels/136501320340209664/869327724504842330/954782177067937832 A Graphic to explain the masking system for clothing in PZ; a post on TIS Discord.]


====File format====
===Old and more specific additional modding resources===
* [[Modding/File Formats|File format documentation]]
*[https://github.com/Konijima/PZ-Community-API/blob/master/Contents/mods/CommunityAPI/media/lua/shared/CommunityAPI/IsoUtils.lua  isoRangeScan: This is an utility function meant for large scale scans of isoGridSquares around a given IsoObject. The scans are done fractally - that is to say from a center (or centers) outward to fill a larger area.]
*[https://theindiestone.com/forums/index.php?/topic/21923-itemzed-updated-11b/ ItemZed: for editing Item scripts and distribution files (out of date, needs to be updated to work properly with build 41)]


====Mapping Resources====
{{Navbox modding}}
* [https://www.pztiles.com/home PZ Tiles and a comprehensive selection of other mapping and tile making resources.]
* [https://drive.google.com/drive/folders/12jQxlDlyC-fACV45oCWshZb60QHoQ6kf The build 41 base and vegetation maps for PZ.]
* [https://theindiestone.com/forums/index.php?/topic/25742-project-zomboid-basemap/ The build 40 base and vegetation maps for PZ.]
* [https://drive.google.com/file/d/1zvjxsjLi2KGwU7SVbLoH2m32UuSgCxcw/view?usp=sharing An app for replacing the zombie layers on cells.]
* [https://drive.google.com/file/d/1PRsZfmE3Ov7U9Nc_mSBv62fMFROpIIct/view?usp=sharing An app for moving the cells in maps.]
* [https://discord.com/channels/136501320340209664/279303619277488128/946017802647658586 A more recent base map for PZ.]
* [https://pzwiki.net/wiki/New_Tiles Making New Tiles for PZ.]

Latest revision as of 12:33, 15 March 2024

ModdingModding
UI Tick.png
This page has been revised for the current stable version (41.78.16).
Help by adding any missing content. [edit]
Spiffo's Workshop is the home of Project Zomboid mods on Steam.

Terms & Conditions

By playing Project Zomboid, you agree to the Terms & Conditions.

By modding Project Zomboid, you also agree with the Modding Policy.

Key restrictions

  • The Indie Stone reserves the right to implement any features in the game irrespective of whether mods exist that accomplish the same goal.
  • Modders are solely responsible for their mod, including (but not limited to compliance with any hosting platforms (such as Steam Workshop). They are also responsible for obtaining third party consents for any third party materials in the mod. Legally, we have to ask that modders to ‘represent and warrant’ (i.e. promise legally) that their mod is their own original work and any third party contents are fully and properly licensed by the modder.
  • Creation of mods is subject to our modding policy, which may be updated from time to time with any technical requirements regarding how PZ mods must work.
  • Project Zomboid modders are free to receive monetary/gift donations from the players who use their releases, and appreciate the time and effort put into them. However, having mods created exclusively for those who choose to donate (or separate ‘in-mod’ content and bonuses) is not allowed. Mod creators cannot sell modifications to Project Zomboid.

Installing and using mods

Tip: join The Indie Stone Discord server for get access to #mod_support channel, where you can ask question about using mods.

To start a mod up, first make sure the mod is installed in the correct directory. Once you have done this, start up Project Zomboid. Once you get to the main menu, down at the bottom of the screen when you see menu options you will also find a menu option called MODS. Click on it, which will then lead you to the mod menu.

In there you should see the list of mods that you have installed. Double click on the mod you wish to start and a green tick should appear next to the mod.

Next thing to do is shut down Project Zomboid and start it up again. Once started your mod should now be ready to go. Instructions on using the mod are usually contained in README's or information in the thread.

Current mods

Main article: Mods

Creating mods

In modding for PZ, there are several main directions:

  • Changing scripts - scripts in the game describe the parameters of items, recipes, and vehicles. Making a mod that changes the values ​​of items, vehicles, a recipe, or adds a new item is not a difficult task. This does not require programming knowledge; any text editor may be used. Scripts are in .txt files and have a specific structure.
  • Writing Lua code - the main direction in PZ modding. Most mods contain Lua code. PZ is developed mainly in Java and Lua, so using Lua code in mods is closely related to the exploration of Java and Lua game code. When creating more complex mods, you will have to dive into the decompiled Java code of the game. We will cover the basics of the Lua language, but you should be familiar with the basics of programming. A general understanding of the syntax of the Java language is also desirable, as it may be necessary to explore the game code to figure out how some functions work.
  • Creating 3D models - at the moment, with the help of mods, you can add new models of vehicles, weapons, ordinary items, and clothes to the game. The game uses 2 model formats - .X and .FBX. For us to create mods with models, the .FBX format will be enough.
  • Creating animations - creating animations for the character. Includes creating an animation file and integrating it into the game.
  • Creating textures, pictures and icons - this direction complements the others. Models will need textures, items will need icons, the interface will need certain images, and maps will need textures for new tiles (new objects to be placed on the map).
  • Map creation - creating locations, buildings, and general environments for the game. See #Mapping.
  • Translations - translating the game to various languages, see Translations.

Tip: Join The Indie Stone Discord server to access the #mod_development channel, where you can ask any question about creating Project Zomboid mods.

Working tools

Modding tools

Resources

Mapping

Main article: Mapping
Tutorial Author Last updated
The One Stop TileZed Mapping Shop RingoD123 January 30, 2017
How to Combine Map Mods RingoD123 June 11, 2017
Full list of current Room Definitions RingoD123 February 7, 2014
Making new room definitions RingoD123 June 10, 2017
Mapping Tutorial's and Videos Thuztor April 20, 2015
Mapping Tutorial's and Videos (Outdated) Thuztor September 12, 2017
VegMap to Testing Custom Map Cpt_Paradox January 28, 2017
Making rooms with the place wall tool, item spawns, ortho and more! Cpt_Paradox November 30, 2017
Sliding Glass Doors, New Textures, Here's How! Cpt_Paradox November 30, 2017
How to make a map Start to Finish Full Video Tutorial BlackBeard January 30, 2017
All player made Building Archives BlackBeard May 31, 2019
Custom texture packs and tile definitions EasyPickins June 5, 2014
Card's Tutorial for Terrain Generation Cardenaglo February 22, 2017
Video Tutorials mapping Atoxwarrior June 26, 2016

Mapping resources

Notes

A note regarding optimization and timestamps

This numerical information in the console.txt output log is a timestamp, such as in "LOG  : General , 1669904231941" If you need to evaluate the runtime impact of code it is a good metric.

A note regarding updating and/or changing mods

Removing .txt and .lua files from a mod before updating them to the steam workshop may result in file mismatch errors etc. on account of steam not automatically removing said files from clients and/or servers. One solution is manually deleting these files from the installation directories of the server and/or clients. As well modders can avoid this issue by keeping those files, instead of removing them, but editing those files so they are empty instead of having any functional content. Including commented text explaining the reason for this in the files is also a good practice.

A note regarding Mac, Linux and case sensitivity

Note that, unlike Windows, Mac and Linux OS are case-sensitive regarding file and directory names. Although people playing PZ on Linux is uncommon, it's far more common with server hosting services. To avoid issues, make sure and follow the vanilla PZ capitalization conventions for file and directory names.

For example: with clothing mods fileguidtable.xml works for Windows and Mac, but will cause serious issue for Linux as it will be looking for "fileGuidTable.xml", as that is how the vanilla PZ file is capitalized. Although Client, Server, and Shared will work for the lua directories for non-Linux systems. it won't work for Linux; consequently use the vanilla capitalization, "client", "server" and "shared" for those.

See also

  • Mods
  • Talk:Modding – for some raw guides to extracting images. The text needs to be cleaned up.

External resources

Tutorial Author Last updated
Project Zomboid Modding Guide (WIP) Fenris Wolf January 22, 2023
RoboMat's Tutorials RoboMat July 24, 2013
Java Scripting Guide (very out of date, only the item and recipe sections seems to be applicable to current builds) Lemmy101 July 24, 2013

Javadoc reference to Project Zomboid codebase

Typescript modding

You can now use Typescript language to write your mods which are then compiled into lua. However it is not necessary to use Typescript to write mods.

Important additional modding resources

General additional modding resources

Clothing modding resources

Old and more specific additional modding resources