Search the Community
Showing results for tags 'Tutorials'.
-
RoboMat's Modding Tutorials - An introduction to modding for Project Zomboid - I - Introduction I1 - Where to start I2 - What is needed I3 - Lua Tutorials I4 - Other Resources II - The first steps II1 - Getting the connection II2 - The entry point: Events III - The first mod III1 - Preparations III1a - Folders III1b - Our mod's identification card III1c - The actual lua script III2 - Adding items to the inventory III3 - Handling keys III4 - Detecting the correct key IV - Custom professions IV1 - Creating a custom profession IV1a - The foundation IV1b - Creating the profession IV1c - Creating a new trait IV1d - Custom Spawnpoints IV1e - Custom Profession Clothing IV1f - Putting it all together IV2 - Linking Professions / Traits to game mechanics I. Introduction Hello there, this is my attempt to write a few modding tutorials for the community. I will try to update this whenever I have some spare time. 1. Where to start First things first. When I started looking into the code of Project Zomboid and the different mods I was a bit confused. There was the source code in Java, the additional code in Lua and the scripting language and I didn't really know which one to look into. To spare you this confusion I'll explain their purpose shortly: Java: Most of the source code of Project Zomboid is written in Java. While you can modify the java files it is not recommended. According to the developers changing the java source code won’t be necessary in future versions of Project Zomboid, so we won’t look into that. Eggplanticus has made a nice post about how to spelunk in the Java source if you want to try it nonetheless. Lua: There already are parts of the source of PZ that have been ported to lua. If you really want to get into modding, you won't get around learning its syntax. Scripting: At the moment it is only used for easily adding items to the game. While we will cover some of the basics of the scripting language we will mostly work with lua coding. 2. What is needed Basically to edit a lua file you can use any standard text editor that is capable of saving simple (unformatted) text files. So Wordpad (Windows) or TextEdit (Mac OS) will do. While it is possible to create a script with those programs they miss many features a specific IDE will give you (syntax-highlighting, auto-formatting, etc...). I prefered working with Eclipse IDE with an extra lua plugin installed for quite some time, but recently switched to IntelliJIdea - haven't been looking back ever since. There are other free alternatives like gedit, Notepad++, ZeroBraneStudio or XCode for example. Find one that works for you and stick with it. Remember: It's not the program that does the work. None of them will turn you into a RobertJohnson over night, they only make your life easier. 3. Lua Tutorials If you have some experience with programming already Lua will probably be fairly easy to pick up for you. I mainly used the official manual to learn the language, but of course there are many other great tutorials out there. From time to time I check the lua wiki and of course stack overflow. Just to be as clear about this as possible: This won't be a tutorial about lua. It will be a tutorial about modding Project Zomboid. If you don't understand parts of my code, you probably should learn some basic lua syntax first. If there is one thing I don't like then it's people who don't even take the time to read through the tutorial notes, then copy&paste the code and finally spam the thread with questions about "why it doesn't work". Don't be that person (unless you are Rathlord). 4. Other Resources For more tutorials you should visit pz-mods.net and the tutorial section on the indiestone forums. If you have further questions you can post them in the modding help section of the the indiestone forums and one of the many coders will help you for sure. TOC Last updated: 12.11.2013 II. The first steps Okay now that we got that out of the way let's move on to the actual modding part. 1. Getting the connection To mod the game we somehow have to interact it. Lua's main purpose lies on extending existing programs written in other programming languages. As mentioned in the previous chapter the main base of Project Zomboid was written in Java. That's where the connection between lua and the java source code happens. With lua we can access all the public functions written in the Java source code. -- lua function function doStuffInLua(_player) -- getSpecificPlayer() is a public method defined in the java source code -- that returns the player. We can access it through lua. getSpecificPlayer(_player); end But how do we know which methods there are!? Well, we can look at the javadoc. It's basically a complete list of all methods in the Java source code and it has even been updated to 2.9.9.15 recently. If you want to be on the save side I suggest that you open the source code and look through it yourself. I use a small programm called JD-GUI for that purpose. It has a useful search function that can search through the whole source code. In the course of this tutorial I will mark methods we call from java so you don't have to worry too much about that at the moment. Eggplanticus also released a good tutorial on how to decompile the java source over here. 2. The entry point: Events So now we know that we can call Java methods from our lua code, but we still don't know how we actually execute our lua code. We need something that runs our code, when Project Zomboid runs. This will be done with Events. You can think of events as entry points to the source code of the Project Zomboid source code. Once Project Zomboid encounters an Event from a mod it calls the associated function. -- the function we want to execute function sayStuff() -- Java: we get the first player local player = getSpecificPlayer(0); -- Java: let the player speak player:Say("I like turtles."); end -- this event will be fired every ten ingame minutes. -- In this case sayStuff() is the associated method and -- thus will be executed every ten minutes. Events.EveryTenMinutes.Add(sayStuff); This short "mod" lets the player talk about his love for testudines every ten minutes in the game. Nothing great but it gets the point across. There are already many different events added to the game which we can use for our mods and the developers are constantly adding new ones. For a somewhat complete list check out the Event Reference on pz-mods.net. Don't worry though, we will use some of them throughout this tutorial so you will slowly get the hang of it. TOC Last updated: 01.10.2013 III. The first mod Let's continue with a little more complex example. We will create a small cheat script that adds some items to the player's inventory when a certain key is pressed. 1. Preparations At first we're going to set up a proper folder structure and all the files we'll need to get the mod to work with Project Zomboid. Please note that this tutorial has Version 2.9.9.17 and later in mind and thus is going to use the structure needed to work with the modloader. If everything is done right our mod will later on appear in the game like this: The almighty RobertJohnson has released a more in-depth tutorial about the modloader and mod.info functions. Once that version is released I'm going to update this post too! a.) Folders Please note, that the folder structure might slightly variate depending on what IDE you are using. I'm going to show you the end-structure which I use when I release my mods: I named the topmost folder (we are going to call this the base folder from now on) after our mod: CheatMod. This base folder is going to contain ALL of our mod files. The "media/lua" folder is basically the location of the vanilla lua files. When we drop our mod into the modloader it is going to copy the files in our base folder to their specified location in the PZ source files. This way our mods don't overwrite any base files and the mod can be removed from the game at any time without breaking it. Yay for the nifty modloader! b.) Our mod's identification card The modloader needs some way of identifying the mods given to it. This is done by the so called mod.info file. It is a simple (unformatted!) text file which contains some important information about our mod. It must be put into the base folder: To make it work we will have to fill it with information of course. Copy this to your mod.info file: name=Cheat Mod (1.0.0) poster=poster.png description=This mod is used to explain modding for Project Zomboid. It is going to show several aspects of modding from start to finish. -by RoboMat id=CheatMod name: The name of the mod. poster: The image file that is displayed in the mod menu in PZ. description: A short description of your mod. I am not sure how many characters this supports. id: The id of our mod. This is used to identify our mod. The id must have the same name as the base folder of our mod (in this case: CheatMod). If you drop you folders into your Project Zomboid "mods" folder now it would already display it as a mod in the game: Of course this isn't really a mod yet. We still need to give it some functionality c.) The actual lua script The last file we need to create is the lua script file. We are going to call it "AddItems.lua" and put it into "media/lua/Mods/CheatMod". Make sure that you really are using the correct suffix of ".lua". Now we are set and ready to begin working on our first mod! 2. Adding items to the inventory We are going to start with a simple script that allows us to add a few items to the player inventory as soon as a certain key is pressed. Adding items is a fairly easy task as you will see. Open your AddItems.lua and enter the following code. local function addItems() local player = getSpecificPlayer(0); -- Java: get player one local inv = player:getInventory(); -- Java: access player inv -- Java: add the actual items to the inventory inv:AddItem("Base.Axe"); inv:AddItem("Base.RippedSheets"); inv:AddItem("camping.TentPeg"); end As with the previous examples our starting point is the player. We need to "get" him first with getSpecificPlayer(0). We then can access his inventory with the getInventory() call. "getInventory()" returns an ItemContainer which happens to be the player's main inventory. This means we now can use all the java functions defined for the ItemContainer.class and one of them happens to be the nifty AddItem(...) function. If you look at the javadoc of this function you will notice that it expects a String as a parameter. What it doesn't tell you is, that it actually needs the module of the item you want to add and the name of the item itself. You can read our example above as "add item Axe from module Base". The code above would give the player an axe, some bandages and a tent peg from the camping module. How do you find out the modules and names of the items? Of course by looking through the source files. All items are currently located in "/media/scripts/items.txt", "/media/scripts/newitems.txt", "/media/scripts/camping.txt" and "/media/scripts/farming.txt". Just take a look at these files - the rest should be self explanatory. 3. Handling keys As we haven't defined an event yet, the function is pretty useless right now. We want the items to be added whenever the player presses a key and luckily the devs have given us the great OnKeyPressed event for that purpose. Let's add it to our mod: local function addItems() local player = getSpecificPlayer(0); -- Java: get player one local inv = player:getInventory(); -- Java: access player inv -- Java: add the actual items to the inventory inv:AddItem("Base.Axe"); inv:AddItem("Base.RippedSheets"); inv:AddItem("camping.TentPeg"); end -- Will be fired whenever we press a key. Events.OnKeyPressed.Add(addItems); This event will be called whenever a key is pressed in the game. The only problem is, that the event doesn't care which key that is. If we would leave our mod like this, the player would get spammed with countless items. We need to fix that! 4. Detecting the correct key One of the great things about events is, that some of them pass useful parameters to the function which is called through the event. The OnKeyPressed event for example passes the number of the pressed key to the function. The called function in this case is of course "addItems()". To use the parameter we have to slightly modify our code another time: -- We added the parameter to the function which -- will be passed to the function as soon as the -- event fires. local function addItems(_keyPressed) local key = _keyPressed; -- Store the parameter in a local variable. print(key); -- Prints the pressed key to the console. -- We test if the correct key is pressed. if key == 25 then local player = getSpecificPlayer(0); -- Java: get player one local inv = player:getInventory(); -- Java: access player inv -- Java: add the actual items to the inventory inv:AddItem("Base.Axe"); inv:AddItem("Base.RippedSheets"); inv:AddItem("camping.TentPeg"); end end -- This will be fired whenever a key is pressed. Events.OnKeyPressed.Add(addItems); Notice the _keyPressed parameter that was added to our function. You might wonder about the leading undaerscore. It is just a thing of coding style that I like to do, to be able to distinguish parameters from local variables in the function's body. The same goes for storing the parameter in the local variable "key". It might seem superfluous at first, but if you want to change the content of this variable later on, you can easily do that by changing its declaration at the top of the functions instead of having to track down every single occurence. Anyway, they _keyPressed parameter will receive a number corresponding to the pressed key and pass it into our function. Unfortunately I'm not to sure which numbering method is used in Project Zomboid, but I think it might be the one from LWJGL. You can use the print(key) call in the function to easily find out all numbers you need to know anyway. Basically we just have finished our first real mod. Save the AddItems.lua and copy your base folder into the Project Zomboid-mods folder. Now you can go into the game and enable your mod (restart the game afterwards!). Once you are in the game now, you should be able to cheat items into your character's inventory by pressing the 'P' key on your keyboard. TOC Last updated: 12.11.2013 IV. Custom professions Admittedly our first mod isn't very impressive so we are going to expand it a bit. The biggest problem at the moment is, that the player can cheat weapons into his or her inventory every playthrough, which might ruin legit savegames. 1. Creating a custom profession That's why we are going to create a custom "Cheater" Profession and link the cheat code to it. a.) The foundation Of course we need to create a new lua script. I'm gonna call it "CheaterProfession.lua" and save it in its own folder (Note: Basically it doesn't matter where you save your lua files, but good structuring will make it easier for you and others to organize and understand your project). After creating the file open it and add the following lines: -- CheaterProfession.luarequire'NPCs/MainCreationMethods';require'NPCs/ProfessionClothing'; This basically makes sure that the file is loaded after those two files which enables us to use their functions. (If someone has a more technical explanation feel free to PM me or comment below!). b.) Creating the profession Now we can start with actually creating the new profession. Add these lines to your CheaterProfession.lua -- CheaterProfession.lua require'NPCs/MainCreationMethods'; require'NPCs/ProfessionClothing'; local function initProfessions() -- Java: Create a new profession. local cheater = ProfessionFactory.addProfession("cheater", "Cheater", "Prof_rm_Cheater"); -- Java: Add a custom trait called Undesireable (no one likes cheaters ). cheater:addFreeTrait("rm_undesireable"); -- Java: Add the vanilla trait Nightowl. cheater:addFreeTrait("NightOwl"); end Lets go through the code. The part of it which actually creates / registers the new profession is: local cheater = ProfessionFactory.addProfession("cheater", "Cheater", "Prof_rm_Cheater"); It calls the addProfession(String type, String name, String IconPath) function of the ProfessionFactory. The parameters are used like this: type: Used to identify the profession internally in the game's code. name: Human readable name which appears in the game's menus etc. iconPath: Name of the custom icon to be displayed in the game. If we would leave the code here it would create a fine new profession without any traits though. That's where the remaining two lines come into play: cheater:addFreeTrait("rm_undesireable"); This adds a (you probably guessed it) trait to the profession we just created. "rm_Undesireable" is the trait we are going to create in a few seconds whereas "NightOwl" is one of the vanilla traits. Of course PZ doesn't know "rm_undesireable" yet, so we still have to actually create it. Lets do it. c.) Creating a new trait We add a new function above the one we created above to initialise the traits. local function initTraits() TraitFactory.addTrait("rm_undesireable", "Undesireable", 0, "Allows you to cheat.\nShame on you!", true); end Quite similar to the ProfessionFactory we used above, the TraitFactory class allows us to add a new trait by calling addTrait(String type, String name, int cost, String desc, boolean profession). Let me explain those parameters: type: This is the internal name used in the games code. It's also the name of the custom icon to be displayed in the game. ! Has to be lower case ! name: The human readable name displayed in menus etc. cost: Determines how many trait points it will cost to select this trait. desc: The description which appears when you hover over the trait. profession: If set to true the trait won't appear as a selectable trait but instead stays a "profession-only" trait. It really is as easy as that Now you actually already have a fully functional profession which you could play with. But it still is lacking two important parts of the profession system: Spawn points and custom clothing colours. d.) Custom Spawnpoints Spawnpoints determine where in the Gameworld the player will appear when the game starts. Before we can add a new spawnpoint though we of course need to find out its coordinates in the game. For this purpose I have created the "Coordinate Viewer", which displays the player's coordinates as a small overlay in the game. So if our cheater profession should start in the large warehouse (where else!?) the game will show us a player position of X: 3110 and Y: 1809. Unfortunately we can't use those "absolute" coordinates for the spawning code. We have to calculate the "relative" coordinates instead. Don't worry though - it is pretty easy. Basically you just need to divide the absolute coordinates by 300 to get the cells, but more importantly you have to ignore the remainder. Our coordinates for the big warehouse would be X: 10 and Y: 6 then. Now we have the cell in which the player should spawn. Relative to that position we need the exact coordinates and this is where the remainder comes into play. Still using the above coordinates the remainders of the division would be for X: 110 and for Y: 9. This probably sounds more complicated than it is. I suggest that you read through this post by The_Real_AI who maybe explains it a bit better. Now that we have calculated the coordinates, we need to tell the game to use them. -- Set custom spawn points for this profession. -- Modelled after spawn code by RegularX. Thanks to -- The_Real_Ai for his explanation on how to calculate -- them. local function initSpawnPoints() local spawn; -- Create a Spawnpoint in the large Warehouse. spawn = { { worldX = 10, worldY = 6, posX = 110, posY = 8, }, } -- Add our profession to the list of spawnpoints for Muldraugh. BaseGameCharacterDetails.spawnPoint.MuldraughKY.cheater = spawn; spawn = { { worldX = 39, worldY = 23, posX = 138, posY = 100, }, } -- Add our profession to the list of spawnpoints for West Point. BaseGameCharacterDetails.spawnPoint.WestPointKY.cheater = spawn; end Basically we have created a local table which holds our calculated coordinates and added it to the global table BaseGameCharacterDetails.spawnPoint. Take a look at the last line of the function: BaseGameCharacterDetails.spawnPoint.WestPointKY.cheater = spawn; We create a new index cheater and give it the value of our spawnpoint. It is essential that this index uses the type (check the parameters above) of your profession or else it won't work. It is probably self evident but MuldraughKY holds all spawns for Muldraugh, whereas WestPointKY creates spawns in West Point. e.) Custom Profession Clothing Finally we are going to add some custom colors for the profession clothing. The System is quite similar to the spawn points above: Basically we are going to create a table which holds all values for male and female "cheaters". ----- Set custom clothing and clothing colors for this -- profession. local function initClothing() local clothes = {} ProfessionClothing.rm_Burglar = clothes; end We create a table called clothes which will hold all of the necessary values. Then we have to make two nested tables to separate the "male" and "female" clothes (this means the guy can have blue and the lady pink colors for example - yay ). local function initClothing() local clothes = { male = { }, female = { }, } end Now we will add all the values need to create the clothes. First we declare which type of clothing item the character should wear. The male character is going to wear a Shirt and Trousers and the female character gets a Blouse and Skirt. ----- Set custom clothing and clothing colors for this -- profession. local function initClothing() local clothes = { male = { topPal = "Shirt_White", top = "Shirt", bottomPal = "Trousers_White", bottom = "Trousers", }, }, female = { topPal = "Blouse_White", top = "Blouse", bottomPal = "Skirt_White", bottom = "Skirt", }, } end You probably are wondering why there are two variables (top and topPal) for each item for example. As far as I understand the system the "pal" stuff just sets the color palette for the specific item. Why we have to do that ... I don't know It is something we gotta have to ask the devs. Last but not least we are going to give some colours to those clothes. Those values will be stored in two seperat tables called topCol and bottomCol. As you probably figured the first determines the colours of the top the character wears, whereas the latter determines the clothes for pants, skirts, etc. PZ uses the three values Red, Green and Blue (RGB) to calculate the final colour. Those values have a floating point range from 0 to 1 which was a bit strange for me at first considering that most programs and games I've used use values from 0 to 255 I will leave it to you to figure out which values return which colour. In my example here all clothes will be black: ----- Set custom clothing and clothing colors for this -- profession. local function initClothing() local clothes = { male = { topPal = "Shirt_White", top = "Shirt", bottomPal = "Trousers_White", bottom = "Trousers", topCol = { r = 0.1, g = 0.1, b = 0.1, }, bottomCol = { r = 0.1, g = 0.1, b = 0.1, }, }, female = { topPal = "Shirt_White", top = "Shirt", bottomPal = "Trousers_White", bottom = "Trousers", topCol = { r = 0.1, g = 0.1, b = 0.1, }, bottomCol = { r = 0.1, g = 0.1, b = 0.1, }, }, } ProfessionClothing.cheater = clothes end Just like the spawnpoints we add the table of our cheater profession to the global table called ProfessionClothing with the last line of the function. f.) Putting it all together We still need to tell PZ to call our functions once the game boots so that our custom values are initialised. We wlll use our beloved Events for that. Add these lines to the end of your CheaterProfession.lua file: Events.OnGameBoot.Add(initTraits); Events.OnGameBoot.Add(initProfessions); Events.OnGameBoot.Add(initSpawnPoints); Events.OnGameBoot.Add(initClothing); We are done here. Congratulations you have created your first custom Profession The complete file should look like this: TOC Last updated: 12.11.2013 2. Linking Professions / Traits to game mechanics What we want to do now is link a special game mechanic to the trait of the profession we just created. Of course this isn't a must, but it doesn't make much sense to implement a trait that doesn't have any effect in the game, does it? You will see that it is actually pretty easy. Let's get to it. Coming soon™... TOC Last updated: 08.11.2013
-
*snip* - never mind lol (figured it out on my own)