pzstorm/capsid

Project Zomboid mod development framework for Gradle.

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.

capsid's Issues

Launch run configurations not working on Linux

Launch run configurations are missing Java and LWJGL library path properties.

Zomboid search scopes

Java and Lua zomboid search scopes should be generated by generateLaunchRunConfigs task.

Configurable launch config log files

Log file tabs for launch configurations should be user-configurable.

Optional mod initialization input

Mark som mod initialization inputs (such as URL) as optional.

Zomboid Lua is not compiled properly

Task compileZomboidLua does not always compile a complete list of all exposed classes.

Configurable VM param options for library paths

The following VM parameters are required to launch the game on Linux:

java.library.path=<path>
org.lwjgl.librarypath=<path>

Capsid should offer builder methods for setting these paths.

Class libraries not loaded as dependencies

LUA_LIBRARY and ZOMBOID_CLASSES dependency entries are not loaded on classpath.

Setup workspace run configuration

Run configuration that sets up working environment.

<component name="ProjectRunConfigurationManager">
  <configuration default="false" name="setupWorkspace" type="GradleRunConfiguration" factoryName="Gradle">
    <ExternalSystemSettings>
      <option name="executionName" />
      <option name="externalProjectPath" value="$PROJECT_DIR$" />
      <option name="externalSystemIdString" value="GRADLE" />
      <option name="scriptParameters" value="" />
    </ExternalSystemSettings>
    <ExternalSystemDebugServerProcess>true</ExternalSystemDebugServerProcess>
    <ExternalSystemReattachDebugProcess>true</ExternalSystemReattachDebugProcess>
    <DebugAllEnabled>false</DebugAllEnabled>
    <method v="2">
      <option name="Gradle.BeforeRunTask" enabled="true" tasks="createLaunchRunConfigs" externalProjectPath="$PROJECT_DIR$" vmOptions="" scriptParameters="" />
      <option name="Gradle.BeforeRunTask" enabled="true" tasks="createModSearchScopes" externalProjectPath="$PROJECT_DIR$" vmOptions="" scriptParameters="" />
      <option name="Gradle.BeforeRunTask" enabled="true" tasks="createDiscordIntegration" externalProjectPath="$PROJECT_DIR$" vmOptions="" scriptParameters="" />
      <option name="RunConfigurationTask" enabled="true" run_configuration_name="decompileZomboid" run_configuration_type="GradleRunConfiguration" />
      <option name="RunConfigurationTask" enabled="true" run_configuration_name="runZomboidDoc" run_configuration_type="GradleRunConfiguration" />
    </method>
  </configuration>
</component>

Capsid gradle plugin runs endlessly when decompiling Class files

I've tried to follow this guide https://github.com/Konijima/PZ-Libraries to decompile PZ 41.76.
I've thought, that the decompiling just takes longer, but in the log I've seen that an error occured and stopped all other decomiling steps.

INFO:  ... done
INFO:  Decompiling class zombie/network/GameClient
ERROR:       Unable to simplify switch on enum: 1 not found, available: {}
INFO:  ... done
INFO:  Decompiling class zombie/network/FakeClientManager
Unable to simplify switch on enum: 1 not found, available: {}

Actually I've found Unable to simplify switch on enum: 1 not found, available: {} this line 9 times in the logs.

ZomboidJar task using project version in jar name

Tasks extending ZomboidJar task are creating jar files that use project version when Project Zomboid version property is not found. The intended behavior is that the version is omitted from jar name if said property is not found.

Changelogs available only to mod projects

GenerateChangelogTask is not available to non-mod projects.

Mod initialization run configuration

Run configuration that initializes mod environment.

<component name="ProjectRunConfigurationManager">
  <configuration default="false" name="initializeMod" type="GradleRunConfiguration" factoryName="Gradle">
    <ExternalSystemSettings>
      <option name="executionName" />
      <option name="externalProjectPath" value="$PROJECT_DIR$" />
      <option name="externalSystemIdString" value="GRADLE" />
      <option name="scriptParameters" value="" />
    </ExternalSystemSettings>
    <ExternalSystemDebugServerProcess>true</ExternalSystemDebugServerProcess>
    <ExternalSystemReattachDebugProcess>true</ExternalSystemReattachDebugProcess>
    <DebugAllEnabled>false</DebugAllEnabled>
    <method v="2">
      <option name="Gradle.BeforeRunTask" enabled="true" tasks="initLocalProperties" externalProjectPath="$PROJECT_DIR$" vmOptions="" scriptParameters="" />
      <option name="Gradle.BeforeRunTask" enabled="true" tasks="initModInfo" externalProjectPath="$PROJECT_DIR$" vmOptions="" scriptParameters="" />
      <option name="Gradle.BeforeRunTask" enabled="true" tasks="createModStructure" externalProjectPath="$PROJECT_DIR$" vmOptions="" scriptParameters="" />
      <option name="Gradle.BeforeRunTask" enabled="true" tasks="applyModTemplate" externalProjectPath="$PROJECT_DIR$" vmOptions="" scriptParameters="" />
    </method>
  </configuration>
</component>

Integrate decompiler code

Fernflower decompiler code should be integrated/bundled with Capsid so that we do not need the user to configure IDEA path and we have greater control over the decompilation process.

Task for decompiling Zomboid libraries

Create a new task that would decompile Project Zomboid libraries.

Zomboid classes not available without game dir

ZOMBOID_CLASSES dependency is not registered if gameDir property is not found in project.

This becomes an issue for example if we want to compile the project on CI where we don't have the game directory and we have to use a pre-assembled containing Zomboid classes.

Setup issue on Windows

After setting my game directory with .\gradlew setGameDirectory

where my local.properties file looks like:

gameDir=/Program Files (x86)/Steam/steamapps/common/ProjectZomboid

I'm getting this error when trying to do anything with gradle:

Could not create task ':updateZomboidLua'.
Could not create task ':zomboidVersion'.
> 'org.gradle.api.tasks.JavaExec io.pzstorm.capsid.zomboid.task.ZomboidVersionTask.setMain(java.lang.String)'

Not sure where to go from here. Any help would be appreciated

Decompiling class zombie/characters/action/ActionTransition

Hello, this decompilation (Decompiling class zombie/characters/action/ActionTransition) lasts for 30 minutes, I had never had the previous case. Is it a file integrity issue?

Incorrect decompile task destination

Destination directory for decompileZomboid task is set to same directory as input directory.

Option for configuring non-mod projects

Projects that are not mods should also be able to take advantage of non-mod related tasks.
This should be configurable via Capsid extension.

Launch configs always launch in debug mode

All launch configurations are always launching Project Zomboid in debug mode.

Configurable run config main class

Run configuration MAIN_CLASS_NAME attribute should be user-configurable.

Run zomboidClasses on game version change

zomboidClasses task should run only when game version changes. This behavior should be configurable through Capsid extension so that it can be disabled with a simple boolean option.