Hi there, not a good start for a guide on how to mod items to game? Well this is how it began or at least some of it.

I wanted to start with mods, looked at blackbeard's YT guides. Followed through until i realised a lot of stuff has changed since then. Looked through so many resources on pz_wiki, discord pinned server pinned links, earlier chats, and after requesting help from other community members i can say it's not an easy process. I'll do my best to at least make you comfortable enough to add stuff to game without breaking anything hopefully.

Note: I'm very new to this stuff literally started a couple of days ago, i do not pretend to be an expert and i hope you don't expect me to be one.

Yes, it's very important you stick to structure if you want your mod to work.
Root/top folder-> ModName

ModName folder contains two files and one folder called "media"
1. poster.png
2. mod.info

poster.png is a file responsible for what you see as a photo while checking out mod.

mod.info contains information about your mod in text format

contents of mod.info file
name=Mod's name
id=uniqueID
poster=poster.png
icon=icon.png(can include it, not a must)
description=Description about mod

media folder basically contains all other stuff that goes in,
1. scripts folder: contains all scripts
2. model_X folder: contains any 3-D models you have
3. sound folder: contains all the sound files that you wish to add
4. textures folder: contains all the icons, textures for any item you might have.

I'll not mention what other folders can go here but you can refer vanilla game files to get an idea how they structured.


Let's talk about two important locations in your file system:
1. Where you put your mod folder to test in-game
2. Where the vanilla game files are for you to refer

C:/Users/username/Zomboid/mods/ ----> Copy paste your mod folder here to test it in-game. Whole folder where top folder is your modName

To access game local files, open steam> select game>click on the settings(gear icon there)>local files>open -----> This is where you can visit your vanilla files to refer, make a shortcut it's gonna be a lot of visits

With that out of the way, if you copy your mod folder with just the above two files mod.info and poster.png to the location i mentioned for testing mods you can fire up pz and see it under mods section, right where you select your mods. It's not functional but we planted a seed.

In terms of what we actually want for each item:

• Item script to define your item and everything related to it.
  
• Icon(thing you see when item is in inventory or equipped)
  
• Texture(in simpler words a clothing for each item or skin if that makes sense)
  
• Model/Mesh(3D model of item, don't need it if you are using vanilla models)
  
• Sound(if there's any)

• GIMP: for creating Icons and textures
  
• Blender: For 3-D models
  
• Audacity: For Sound

Let's talk about item script, this one defines everything about your item:

A sample script from vanilla files

Most of stuff here is self explanatory, ill talk about few key details to lookout for to avoid any problems

• Icon: Here you write name of your icon file excluding the "item_" prefix and make sure first letter is uppercase
  
  
• Static model: Look at model script and write name of model you want this item to have, static means while the item is in hand.
  
  
• WorldStatic model: Again from the model script, choose a model you wanna display here. World static model refers to when item's on ground or placed.

NOTE: In the screenshot of script, you can't see it here but the text is wrapped inside "module Base{}" because it's file from vanilla, you can write your module name and if you are using anything from vanilla make sure to squeeze "import {Base}" in there.


Edit: Group of variables used during object creation, figured it would fit perfectly here.
https://github.com/MrBounty/PZ-Mod---Doc/blob/main/Items%20variables.md

Checklist for Icons

1. Keep the size of about 32px x 32px, if not sure refer vanilla icons.
2. Export in PNG format.
3. Name icon files with prefix "item_"
4. Icons go into "textures" folder
5. While calling Icons inside script, don't use "item_" prefix, just rest of name. Also rest of name should start with capital letter.

Ex: IconfileName: item_ItemName , while using inside script only do "ItemName".

6. "textures" folder goes into "media" folder

Checklist for textures:

• Textures should be of same size or scale like in vanilla game files, refer those files if you find
  something similar to yours.
  
  
• Export to PNG format
  
  
• textures go to "textures" folder

if you made the model, models goes into "models_X" (vanilla structure). Name whatever you want, avoid name clash with vanilla models.

I think it's time to introduce scripts, think of it as definitions for everything you have. Where to get icons from, where to find sound, model or what texture to use, what should call what sound etc etc.

Your script folder contains all the scripts that you gonna write, "script" folder goes into "media" folder.

To define textures and model/mesh for our items, we make a model script:





Think of it as your file name, if anyone needs stuff from your file this will be helpful. It's unique and prolly best to use MOD ID as your module name

This is how it sounds a base file of game, we import it only if we use stuff that's already defined in base module.

it means 3-d model that's all, this is how you define what model will your item use? Careful when you give file names here address should match. If file is inside your model_X folder then you just write file name but if it's inside one of the sub folder then you write complete name i.e. using /subfolderA/fileName

skin/clothing of your item, again all textures go inside texture folder.

With this you control the size of your models, so you don't end up doing what i did. To get almost as same scale as vanilla, go for value of "0.01xx" here can be variable and you can tweak it a bit slightly increment the size to avoid this




Note: In all your scripts, you just write name of stuff and system knows where to find them if you used correct folder. But if say a file called fileA is a texture file and it's inside texture/subfolder then you would need to call it's complete address i.e. subfolder/fileA in all your scripts. It goes for all the scripts and all the files.

a few words from TIS, pinned in discord server


Please try to avoid using model textures that are larger than the ones used in Vanilla PZ for equivalent items.
Generally speaking vehicles are 512x512.
Body and clothing textures are 256x256.
Weapons are generally 128x128 - but vary due to the variation in sizes.
Hats are 128x128.--Blair Algol(TIS)

I won't be teaching how to make models, if you want you're gonna have to learn that.
I'll give one important detail about models, when you export from your software it should be either in .x extention or .fbx extention only

Note: Static models and WorldStatic models are different things, first one is what model looks like in your hand. WorldStaticModel means how it looks on ground in-game. I don't know too much in detail apart from this. You might wanna reconsider while dealing with static models, if you use ground ones then during animation the item might get flipped.




Edit: Sometimes despite having the right configurations, you won't be able to see your model in-game. I recently ran into something like that, scale was the culprit. You see the model i was using from vanilla files, it was scaled to 0.4 but i was using a value of 0.19.. So the model was there but it was too small to notice. Anyway if not sure, refer to vanilla files for scale/texture sizes etc.

Firstly sound is looped in-game, can't say it's true for everything in-game but for what i tried atleast so if you hear your sound again and again while action is performed, then i'm not much of help here.


Shoutout to @PhilJHerman, been very helpful with questions through this whole process (say Hi to them on discord) suggested to change time duration of action or spread audio file in order to match with action duration. I tried the latter and it wasn't a success. They also suggested to tweak action time interval long enough to match with sound duration that way you can save yourself from that loop. I tried it for something else and it works at least for that part.

Convert sound file to OGG format(believe .wav also works) , if stereo doesn't work switch to mono Audio. Remember i mentioned "Audacity"? Should help you with this.

All sounds goes into "sound" folder just as vanilla structure.

As for writing sound script file, here's a resource: https://pzwiki.net/wiki/Scripts_guide/Sound_Script_Guide

Just as we talked about all scripts go into scripts folder.

Now this falls into some technical sides of radar, There's a concept called Procedural Distribution.
Earlier in pz codewise items were added separately to all the rooms in the world. So let's say there's about 100 items then you'd add 100 items to each room with a chance to spawn in. This often resulted into items of different categories spawning in same room, cabinets etc.

To deal with this problem devs worked on Procedural Distribution, Instead of adding say 100 items to each room. Now we make lists of item of same type of categories, anyway if we can relate items to we name that category and add items in it along with spawn chance.

There's several lists like this in commons/ProjectZomboid/media/lua/server/items/ProceduralDistributions


these are just two of those lists, anyway hopefully this explains.

So now to actually spawn these items in server, commons/ProjectZomboid/media/lua/server/items/Distributions file is used

Here's an example,

So you don't mess with Distributions file, All you need to do is add your item to those lists in procedural distributions we talked about.

Note: To understand procedural distribution i'd recommend checking out the link in references section about procedural stuff. Really great explanation.

Say your item is cold drink, try to find a category itll fit with in-game. Basically open up that ProceduralDistributions file and search for item that relates closesly with your item.

Note down names of each of those lists which contain item similiar to yours

Once you're done, All you need to do is now add your item to each of those lists.


For each list you'd insert your item in first row and in second line you insert the odds for it to spawn, as you can see from example code how each list from procedural distribution has two entries here.
This repeats for each list you wanna add your item to.

All these files in this section is lua code btw, i won't jump too much into details and i expect you to put in some efforts while exploring and learning along the way.

Let's talk about some technical stuff here, watch out every spelling check, missing comma or just the structure. Can't stress enough how important that is.

It's not going to be easy, there's not much resources and the ones that are already there are somewhat outdated. But here's what I know this whole process is what teaches you stuff in the end. Just as I'm creating this guide after scratching my head since two days one roadblock at a time, it's gonna be same way when I tap into new territory of modding.

You're not learning how to make mods for pz, you're learning the process of how to make something with limited amount of information and a bit of experimentation on your part.


When in doubt try to look at vanilla files, explore and experiment with stuff. To connect with other folks from community, join PZ discord server. They have dedicated channel for mod-development, comes handy for many doubts you might have.


Enough TED talk, I'll add all the resources to refer down below, I'll try to update this guide if I can. Maybe I'll add different stuff related to modding if I learn something new. STAY TUNED.

Please upvote if you found this helpful :)

My other guides:
https://psteamcommunity.yuanyoumao.com/sharedfiles/filedetails/?id=3002618095
https://psteamcommunity.yuanyoumao.com/sharedfiles/filedetails/?id=2916478006
https://psteamcommunity.yuanyoumao.com/sharedfiles/filedetails/?id=2997471577

My mod:
https://psteamcommunity.yuanyoumao.com/sharedfiles/filedetails/?id=3030571779

• Mostly centralised stuff here
  https://pzwiki.net/wiki/Modding
  
  
• Really Good tutorial i found in the wild
  https://youtu.be/ikRcbRHc45k
  
  
• It's outdated but if anyone wants to take a look at
  https://youtu.be/N6tZujOPnDw
  
  
• File Structure
  https://youtu.be/ArPOmuFEdGo
  
  
• Explains Procedural Distribution, makes stuff so much easier.
  https://theindiestone.com/forums/index.php?/topic/38165-quick-guide-how-to-mod-the-loot-distribution-system-distributionslua-proceduraldistributionslua/
  
  
  
  
• 3-D models and tools
  https://theindiestone.com/forums/index.php?/topic/37647-the-one-stop-shop-for-3d-modeling-from-blender-to-zomboid/
  
  
  
  
• some random stuff i found on forums
  https://theindiestone.com/forums/index.php?/topic/23364-all-lua-functions-list/
  
  
• Events
  https://pzwiki.net/wiki/Lua_Events
  
  
• wanna add sandbox options for mod?
  https://github.com/demiurgeQuantified/PZModdingGuides/blob/main/guides/SandboxOptions.md