Contributing

Contributing explains how to help DragonMineZ: reporting bugs, testing releases, suggesting features, improving documentation or working on the code. Whatever you want to do, the team is happy to collaborate with you. Please follow these guidelines so the process stays smooth for every contributor. If you want to donate to the project, see Supporting the project on Patreon.

Getting started

Read the Code of Conduct. By contributing, you agree to uphold the Code of Conduct.
Check the existing issues. Look through the issues to see if someone has already reported your concern or proposed your idea.
Fork the repository and clone your fork to your local environment for testing and development (see below).
Set up your environment with the tools listed below.

To clone your fork:

git clone https://github.com/your-username/DragonMineZ.git

Make sure you have these tools installed:

Java Development Kit (JDK) 17 (the build uses a Java 17 toolchain)
Git
An IDE with Gradle support (IntelliJ IDEA or Eclipse)

You don't need to install Gradle or Forge yourself: the repository ships the Gradle wrapper (gradlew / gradlew.bat), which downloads Gradle, Minecraft Forge (1.20.1-47.4.10) and every dependency on the first build.

If you are not forking the repository or creating an add-on, you can skip step 3. For add-on development, see Add-on Getting Started instead.

Building and running

Run these commands from the repository root (./gradlew on Linux and macOS, .\gradlew.bat on Windows):

Command	What it does
`./gradlew build`	Full build. The shippable jar is `build/libs/dragonminez-<version>.jar` (it bundles the database libraries); the `-slim` jar is not meant to be shipped.
`./gradlew runClient`	Starts a development client (working directory `run/`).
`./gradlew runServer`	Starts a development dedicated server (working directory `run/`).
`./gradlew runData`	Runs data generation (working directory `run-data/`) and writes to `src/generated/resources/`. Run it after changing datagen providers, and review the generated diff.

There is no automated test suite. Validate your change with build and, when it affects gameplay, by testing it in runClient and/or runServer.
Client-only development mods (JEI runtime, shaders and so on) are only added to runClient. Keep it that way, so they can't leak into generated data or the dedicated server.
Resource optimization (PackSquash) runs on CI and is off for local builds by default. Force it with -PoptimizeResources=true or -PoptimizeResources=false.

Translations

src/main/resources/assets/dragonminez/lang/en_us.json is the source language file. Add an entry there for every new piece of text players can see, and keep existing keys stable.
Other languages are translated by the community on Crowdin. The English file is uploaded to Crowdin automatically when it changes on main.
Before opening a pull request, check that every language file is valid JSON with scripts/check_lang.sh (it needs jq).

How to contribute

Reporting bugs

If you have found a bug, open a bug report and include as much detail as possible:

A clear description of the issue
Steps to reproduce it
Expected and actual results
Screenshots, logs or crash reports, if any

Game testing

Anyone is free to test the public releases and share what they find with the team: bugs, exploits, balance issues, crashes or anything else that seems off. You don't need to be a developer or open a pull request to help this way.

Test against public releases only. Do not test against unreleased or internal builds unless you have been given explicit access.
Share your findings in a bug report or on Discord.
If what you find is a security vulnerability (for example, something that could be exploited to harm other players or servers), follow the Security Policy instead of opening a public issue.

Suggesting features

Have a great idea? Open a feature request and provide:

A clear and concise explanation of the feature
Its potential benefits and impact
Any alternatives or related concepts

You can also suggest features on the Discord server.

Submitting pull requests

Step 1: Create a branch. main holds the current stable release line; the next version is developed on its own version branch (for example v2.2). Base your branch on the one your change is meant for; if you are unsure, ask on Discord. Use a descriptive branch name:

git checkout -b fix/short-description

Step 2: Make your changes.

Write clean and concise code.
Test your changes locally to make sure they work as intended.
Follow the project's coding conventions and standards.

Step 3: Commit your changes with a meaningful commit message:

git commit -m "Fix: Resolved issue with XYZ feature"

Step 4: Push your changes.

git push origin fix/short-description

Step 5: Open a pull request. Go to your fork on GitHub and submit a pull request.

Describe the changes and link the related issues.
Be prepared to discuss and revise your code based on feedback.
Every pull request is compiled automatically by the Compile Check workflow (./gradlew build). If it fails, your pull request will not be merged. Workflow runs for first-time contributors may need a maintainer's approval before they start.

Automated checks

Workflow	When it runs	What it does
Compile Check	Every pull request, and pushes to any branch except `main` that touch code, resources or Gradle files	Runs `./gradlew build`
Java CI	Pull requests and pushes to `main` that touch Java or `build.gradle.kts`	Runs `./gradlew build` and submits the dependency graph
Crowdin Check & Upload	Pushes to `main` that touch the lang folder, every 2 days, or manually	Validates the language files with `scripts/check_lang.sh` and uploads `en_us.json` to Crowdin
CodeQL	Daily	Security analysis of the Java code and the workflows

Releases are published to Modrinth and CurseForge from main by the maintainers' release workflows.

Contributor guidelines

Coding standards
- Use descriptive variable and method names.
- Format code consistently (indentation, spacing and so on).
- Write comments for complex logic.
Documentation
- Update or add documentation for new or changed features.
- Make sure this wiki reflects major changes.
Testing
- Test thoroughly across the relevant scenarios, including a dedicated server (runServer) when your change touches client classes, networking or server logic.
- Fix any linting or compilation issues before submitting your pull request.
Compatibility
- Many systems read JSON that players, server owners and add-on authors edit (configs, quests, wishes, Dragon Ball packs). Don't rename or remove config keys, JSON fields, NBT save keys or registry names without discussing it first: older worlds and configs must still load.
- Network packets are identified by registration order: add new packets at the end of NetworkHandler.register(), never in the middle.
- Validate everything a client sends on the server; never trust the client for stats, unlocks, quests, wishes or progression.
Project docs
- CLAUDE.md and the AI/ folder (Agents.md, Context.md, Memory.md, QuestAddonAPI.md) describe the architecture, data systems, build and release automation in detail. They are written for AI coding assistants but are just as useful for human contributors: read AI/Context.md before larger changes.

Community

Join the Discord server for real-time discussions.

Supporting the project on Patreon

DragonMineZ is a community-driven project, and your support helps the team keep improving it and delivering new features. Consider becoming a patron on Patreon to support the development and maintenance of the mod. Patrons receive exclusive benefits, such as:

Early access to new features
Behind-the-scenes updates
Recognition in the community

Every contribution, no matter how small, helps DragonMineZ keep improving.

Licensing

By contributing, you agree that your contributions will be licensed under the same license that governs the project.

Thank you

The team is excited to see your contributions and ideas. If you have any questions or need help, reach out to the team.