cocolabs / pz-zmod

ZomboidMod is compact mod development environment for Project Zomboid.

ZomboidMod

ZomboidMod is a compact mod development environment for Project Zomboid.

It is essentially a wrapper for you mod that enables powerful IDE features and improves your modding workflow. With a collection of Gradle scripts it helps automate the process of setting up, assembling and deploying your project.

Introduction

Whether you are a creating textures, models, maps or writing code you are working with often large and complex collections of files. These files need to be interpreted, and (in case of mod files) version controlled. Since we are human beings, we are not nearly as good at interpreting and storing raw data as machines are. This is why we need their help through advanced tools such as Git and IDE's. Git helps manage our mod versions, while an IDE provides powerful features to increase efficiency, offer code assistance, and make development more enjoyable.

• Increased efficiency means an overall higher mod quality.
• Code analysis helps spot bugs and avoid lengthy debugging sessions.
• Code navigation helps quickly find what we are looking for saving us time and energy.
• More enjoyable workflow brings more motivation used to create amazing mods.

ZomboidMod serves as an umbrella for these tools, connecting everything you need in one system.

Features

• Decompiles and packages game classes to expose game engine code.
• Uses ZomboidDoc to compile a readable and always up-to-date modding Lua library.
• Compact workspace that can be used straight out of the box.
• Fully automated project changelog generation.
• Create mod distributions with a click of a button.
• Easy installation steps for enabling advanced features.
• Comes pre-configured for use with Git.
• Fully integrates with IntelliJ IDEA.

Where do I get it?

Download the latest release from the repository.

Note that you should not clone the repository and use it as a template. Instead, obtain the latest release and follow the installation instructions.

Installation

Notes

• Little question marks are hyperlinks that reveal more information when you hover over them.
• Lines that start with an arrow icon can be expanded to reveal more information.

Requirements

• Project Zomboid^?
• JDK 8^?
• IntelliJ IDEA
• EmmyLua

Setup

• Download the latest release from the repository.

• Extract the release archive in your local mod root directory (overwrite if updating).

• Make sure the root directory follows project naming standards:

  • Project name has to be all lower-case.
  • Project name has to start with pz- prefix.
  • Use dashes instead of whitespace and underscore characters.
• Open the project as a Gradle project with Intellij IDEA^?.

  
  
  

• Ensure project SDK is set to JDK 8^?.

• Initialize mod by running initializeMod run configuration^?.

  
  

• Prepare workspace by running setupWorkspace run configuration^?.

• Reload Gradle project^?.

• Attach decompiled sources to classes.

  • Open project structure - File -> Project Structure...
  • Open modules -> main -> Dependencies panel.
  • Find and select zomboid-<version>.jar dependency.
  • Click the little pencil icon to edit depdendency properties.

  

  You should now be in the window called Configure Module Library.

  • Click the little plus icon (Alt + Insert) to attach files.
  • In the new explorer window that just popped up find and select compiled sources which should be in ./lib/zomboid-<version>-sources.jar in project root directory.
  • Click OK in all open windows to save and apply settings.

  

License

It is important to license your project with an appropriate open source license to ensure others have the right to copy, distribute or modify your work without being at risk of take-downs, shake-downs, or litigation.

Learn what happens when you choose not to license your project.

ZomboidMod distributions contain a template MIT license for your project to use. Keep in mind that you can choose to license your project under a different license at any point in time. To apply the template license provided in the distribution to your project follow these steps:

• Update copyright in LICENSE.txt to include the current year and your name:

    Copyright (c) [year] [fullname]
  

• Update copyright in README.md under 'License' section to include your name and (optionally) a link to your Github profile, personal website, or another place online you can be reached:

    MIT © [Yourname](https://github.com/username)
  

Note that you can choose to include your full name or your Github username. It is a matter of preference and legally speaking both should be valid as long as you can prove the identity provided represents you.

Discord integration

If you are a Discord user and want to let the world know that you are working hard on your Project Zomboid mods you can do so with IntelliJ IDEA Discord integration.

Installation

• Install Discord Integration IDEA plugin from the marketplace.
• Run createDiscordIntegration task.^?

Note that you need to write mod metadata (mod.info) before creating Discord integration so that the integration displays correct project name and description. However the integration is automatically setup after running setupWorkspace so you don't have to worry about that.

You can rerun the task at any time if you accidentally delete the configuration file.^?

How to use

Search scopes

IDEA scopes are sets of files you can search in various contexts. ZomboidMod generates custom search scopes to help you find code usages or references helpful in modding the game:

• mod-lua - All Lua files in media directory.
• mod-media - All files in media directory.
• pz-java - Project Zomboid Java classes.
• pz-lua - Project Zomboid Lua classes.

Learn more about searching everywhere in IntelliJ IDEA.

Changelog

If you are not familiar with what a changelog is I recommend reading keep a changelog.

ZomboidMod uses github-changelog-generator to generate standardized changelogs. Your should generate a changelog after each release, when all issues on project Github repository have been closed with a merge commit.

Before generating a changelog you need to do the following:

• Make sure you have designated repository url in mod.info file.

• Generate a Github token and store it in local.properties:

   cg.token=<your-40-digit-token>

Then simply run generateChangelog task to generate project changelog.

Distribution

Before others can download your mod you need to assemble and upload the mod distribution.

Assembling distributions is a process of packaging everything your mod needs to run in production environment in compressed archives. Anything not needed in production environment (such as gradle files) needs to be excluded from distributions.

ZomboidMod handles this for you. Just run assembleModDist and a distribution archive matching the current project version will be created in build/distributions directory.

List of tasks

Setup tasks

• createDiscordIntegration - Show IDEA project in Discord via rich presence.
• createLaunchRunConfigs - Create game launch run configurations.
• createModSearchScopes - Create IDEA search scopes for mod files.
• initLocalProperties - Initialize local project properties.

Documentation tasks

• generateChangelog - Generate a project changelog.

Distribution tasks

• assembleModDist - Assembles the mod distributions.
• modDistZip - Bundles the project as a distribution.

Mod tasks

• applyModTemplate - Apply Project Zomboid mod template.
• createModStructure - Create default mod directory structure.
• initModInfo - Initialize mod metadata information.
• loadModInfo - Load mod metadata information.
• saveModInfo - Save mod metadata to file.
• showModInfo - Print mod metadata information.

Zomboid tasks

• annotateZomboidLua - Annotate vanilla Lua with EmmyLua.
• compileZomboidLua - Compile Lua library from modding API.
• updateZomboidLua - Run ZomboidDoc to update compiled Lua library.
• decompileZomboid - Decompile Project Zomboid classes.
• zomboidClasses - Assembles Project Zomboid classes.
• zomboidJar - Assembles a jar archive containing game classes.
• zomboidLuaJar - Assembles a jar containing compiled Lua classes.
• zomboidSourcesJar - Assembles a jar containing decompiled game sources.
• zomboidVersion - Read Project Zomboid game version.

Discussion

• Feel free to open a ticket if you have any problems, questions or suggestions regarding the project.
• You are also welcome to join us on Discord to talk about modding and follow community projects.

License

MIT © Matthew Cain