Storm Capsid

Capsid is a compact mod development environment for Project Zomboid.

It is a Gradle plugin that enables powerful IDE features and improves your modding workflow. 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.

Capsid 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.
Fully automated project changelog generation.
Create mod distributions with a click of a button.
Fully integrates with IntelliJ IDEA.

Where do I get it?

Check the latest version on Gradle Plugin Portal and declare the plugin like this:

plugins {
    id 'io.pzstorm.capsid' version '0.4.2' 
}

How to use it

Setup

Run createRunConfigurations Gradle task. In the lower half of the screen you can find the task execution log which will ask you to enter path to game installation directory. This is the directory where you installed Project Zomboid. Click on the line below the input line and enter the path installation directory.
Run setupWorkspace IDEA run configuration. This will setup everything from creating IDEA/Discord integration to decompiling the game for you.
Attach decompiled sources to assembled Zomboid jar. For more information see Setup in ZomboidMod documentation.
Run initializeMod IDEA run configuration. After running this configuration you will be asked to input details about your mod such as name, description and URL. Click on the line below the input and enter the details asked by the task.

Project 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.

Capsid mod template comes with 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 on Project Zomboid mods you can do so with IntelliJ IDEA Discord integration.

Do the following steps to enable Discord integration for your mod project:

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

Project name and description displayed in Rich Presence will be read from mod.info file so you should run this task after initializing mod. Note that you can rerun the task at any time if you update mod metadata or accidentally delete the configuration file.^?

Search scopes

IDEA scopes are sets of files you can search in various contexts. Capsid 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.

Capsid 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:

Set Github repository owner and name through Capsid plugin extension:
```
setProjectRepository('repo-owner', 'repo-name')
```
If the named properties are not configured by user, Capsid will try to read the repository owner and name information from url property in mod.info file assuming it is a valid Github URL.
Generate a Github token and store it as a project property in local.properties:
```
gcl.token=<your-40-digit-token>
```
You can also store the token as an IDEA terminal environment variable CHANGELOG_GITHUB_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.

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

List of tasks

Setup tasks

setGameDirectory - Set game directory via user input.
createRunConfigurations - Create useful IDEA run configurations.
createSearchScopes - Create IDEA search scopes for project files.
createDiscordIntegration - Show IDEA project in Discord via rich presence.

Zomboid tasks

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

Mod tasks

createModStructure - Create default mod directory structure.
saveModMetadata - Save mod metadata to file.
loadModMetadata - Load mod metadata information.
initModMetadata - Initialize mod metadata information.
showModMetadata - Print mod metadata information.
applyModTemplate - Apply Project Zomboid mod template.

Distribution tasks

generateChangelog - Generate a project changelog.
mediaClasses - Assembles mod Lua classes.
processMediaResources - Process mod resources.

Discussion

Feel free to open a ticket if you have any problems, questions or suggestions regarding the project.
You are also welcome to join Coco Labs on Discord to talk about modding and follow community projects.
If you are interested in learning about Java modding join The Storm Project on Discord.

License

This project is licensed under GNU General Public License v3.0.

pzstorm / capsid

readme