mcgen

中文文档

mcgen is a Zig command-line generator for Minecraft plugin and mod starter projects. It provides an interactive wizard for selecting a platform, build system, Minecraft version, and project metadata, then writes a ready-to-edit project scaffold.

The project is inspired by the project creation workflow in the MinecraftDev IntelliJ IDEA plugin, but this repository is a standalone CLI generator.

Features

• Interactive project creation wizard
• Supported dedicated generation pipelines:
  • Bukkit
  • Spigot
  • Paper
  • Forge
  • NeoForge
  • Fabric
• Generated Gradle starter layout with:
  • build.gradle
  • gradle.properties
  • settings.gradle
  • gradlew
  • gradlew.bat
  • gradle/wrapper/gradle-wrapper.properties
  • platform-specific metadata files
  • starter main class
  • .gitignore
• Minecraft version selection with live, cached, and embedded fallback sources

Current behavior

The generator currently has three real template families:

• Bukkit / Spigot / Paper
• Forge / NeoForge
• Fabric

The following platforms are accepted by the wizard but currently fall back to the Bukkit-style generator:

• BungeeCord
• Velocity
• Sponge
• Architectury

Build system behavior

The wizard lets you choose Gradle or Maven, but the current implementation still generates Gradle project files for every path.

Choosing Maven only changes the final printed next-step command. It does not generate pom.xml or a Maven wrapper.

Requirements

• Zig 0.15.x
• Make (optional)

Build

make

Equivalent direct build:

zig build -Doptimize=ReleaseSafe
cp zig-out/bin/mcgen ./mcgen

Run

./mcgen

The wizard will guide you through:

1. Platform selection
2. Build system selection
3. Minecraft version selection
4. Optional framework version overrides for Forge, NeoForge, and Fabric
5. Project metadata input
6. Final confirmation and generation

Generated project layout

Bukkit / Spigot / Paper

<artifact-id>/
├── build.gradle
├── gradle.properties
├── settings.gradle
├── .gitignore
├── gradlew
├── gradlew.bat
├── gradle/
│   └── wrapper/
│       └── gradle-wrapper.properties
└── src/
    └── main/
        ├── java/
        │   └── <package>/
        │       └── <MainClass>.java
        └── resources/
            └── plugin.yml

Forge / NeoForge

<artifact-id>/
├── build.gradle
├── gradle.properties
├── settings.gradle
├── .gitignore
├── gradlew
├── gradlew.bat
├── gradle/
│   └── wrapper/
│       └── gradle-wrapper.properties
└── src/
    └── main/
        ├── java/
        │   └── <package>/
        │       └── <MainClass>.java
        └── resources/
            ├── META-INF/
            │   └── mods.toml
            ├── pack.mcmeta
            └── <mod-id>.mixins.json

Mixin configuration is only generated when you enable mixins in the wizard.

Fabric

<artifact-id>/
├── build.gradle
├── gradle.properties
├── settings.gradle
├── .gitignore
├── gradlew
├── gradlew.bat
├── gradle/
│   └── wrapper/
│       └── gradle-wrapper.properties
└── src/
    └── main/
        ├── java/
        │   └── <package>/
        │       └── <MainClass>.java
        └── resources/
            ├── fabric.mod.json
            └── <mod-id>.mixins.json

Version selection

mcgen can resolve Minecraft and framework versions from multiple sources:

• live network fetch
• local cache
• embedded fallback data

The current source is shown in the wizard.

Useful environment variables:

• MCGEN_TEST_SELECTED_VERSION=1.21.1
  • skips the interactive Minecraft version prompt when the value is selectable
• MCGEN_BYPASS_CACHE=1
  • ignores the local version cache for the current run

Next steps after generation

For generated Gradle projects:

cd <artifact-id>
./gradlew build

For mod projects:

./gradlew runClient

For plugin projects, build the jar and install it into your server as needed.

Notes and limitations

• Main class defaults to CamelCase(project name) + Plugin
• Group ID suggestion defaults to com.<lowercased author>
• Artifact ID suggestion defaults to the lowercase project name with spaces replaced by -
• NeoForge live version normalization is still an evolving area; when live lookup is unavailable, the generator falls back to embedded data
• There is currently no automated test suite wired into the repository; validation is done by rebuilding and running the CLI manually

License

This repository is licensed under the MIT License.

Credits

Inspired by the MinecraftDev IntelliJ IDEA plugin.