CraftEngine

English | 简体中文 | 繁體中文

📌 About CraftEngine

CraftEngine redefines plugin architecture as a next-generation solution for custom content implementation. Its JVM-level injection delivers unprecedented performance, stability, and extensibility. The framework provides a code-first API for registering natively integrated block behaviors and item interaction logic.

Build

Getting the full jar is completely free, as long as you have a device with jdk21 installed. Follow the guide below to build it.

🐚 Command Line

• Start terminal and change directory to the project folder.
• Execute "./gradlew build" and get the artifact under /target folder.

💻 IDE

• Import the project and execute gradle build action.
• Get the artifact under /target folder.

Installation

💻 Enviroment Requirements

• First, ensure that you are running a Paper/Folia (or its fork) 1.20.1+ server. The plugin does not support Spigot and is unlikely to do so in the future.
• Secondly, please use JDK 21 to run the server. I believe this is quite straightforward for you.

🔍 How to Install

CraftEngine offers two installation modes: Standard Installation and Mod Mode. As the name suggests, Standard Installation involves placing the plugin into your plugins folder just like any conventional plugin. Below, we will provide a detailed explanation on how to install using mod mode.

🔧 Install Server Mod

• Download the latest ignite.jar into your server's root directory
• Either:
  • Rename your server JAR to paper.jar and modify startup command to: -jar ignite.jar
• Or:
  • Use advanced launch arguments
    • For paper/folia: -Dignite.locator=paper -Dignite.paper.jar=./server-xxx.jar -jar ignite.jar
    • For some special paper forks -Dignite.locator=paper -Dignite.paper.target=cn.dreeam.leaper.QuantumLeaper -Dignite.paper.jar=./leaf-xxx.jar -jar ignite.jar
• Start the server to generate the /mods directory
• Place the latest mod.jar in /mods
• Install the plugin by placing its JAR in /plugins
• Perform two restarts:
  1. Initial restart for file initialization
  2. Final restart to activate all components

Technical Overview

⚙️ Blocks

The plugin employs runtime bytecode generation to register custom blocks at the server-native level, combined with client-side data packet modification for visual synchronization. This architecture provides:

🧱 Native Block Customization

• Dynamically register blocks with complete control over
• Physics: hardness, flammability, light emission, etc.
• Custom Behaviors: Tree saplings, crops, falling blocks, and more via API
• Vanilla Compatibility: Full preservation of vanilla block mechanism (e.g., note blocks, tripwires)

📦 Data Pack Integration

• Define custom ore veins
• Generate custom trees
• Configure custom terrain generation

⚡ Performance Advantages

• Significantly faster and stabler than traditional Bukkit event listeners
• Strategic code injection for minimal overhead

🥘 Recipes

CraftEngine implements a fully customizable crafting system via low-level injection. Unlike conventional plugins that fail with NBT modifications, it ensures resilient handling of item metadata - recipe outcomes remain exclusively tied to unique item identifiers.

🪑 Furniture

The plugin utilizes a core entity to store furniture metadata, while transmitting collision entities and modular components as client-bound packets. This architecture achieves significant server-side performance optimization, while supporting composite furniture assembly through multi-part item integration.

📝 Templates

Given the extensive and intricate nature of plugin configurations, a modular template system is implemented to compartmentalize critical settings. This enables user-customizable configuration formats while significantly minimizing redundant YAML definitions.

🛠️ Models

The plugin enables model inheritance and texture overrides through configuration, while supporting all item models from version 1.21.4 onward. It incorporates a version migration system that automatically downgrades 1.21.4+ item models to legacy formats with maximum backward compatibility.

Inspired Projects

This project draws inspiration from the following open-source works:

• Paper
• LuckPerms
• Fabric
• packetevents
• NBT
• DataFixerUpper
• ViaVersion

Core Dependencies

The implementation relies on these fundamental libraries:

• ignite
• cloud-minecraft
• rtag
• adventure
• byte-buddy

How to Contribute

🔌 New Features & Bug Fixes

If your PR is about a bug fix, it will most likely get merged. If you want to submit a new feature, please make sure to contact me in advance on Discord. The code you contribute will be open-sourced under the GPLv3 license. If you prefer a more permissive license(MIT), you can specifically indicate it at the top of the file.

🌍 Translations

1. Clone this repository.
2. Create a new language file in: /bukkit/loader/src/main/resources/translations
3. Once done, submit a pull request for review. We appreciate your contributions!

💖 Support the Developer

If you enjoy using CraftEngine, consider supporting the developer! By supporting developers, you can get support from the development team.

• Polymart: [None]
• BuiltByBit: [None]
• Afdian: Support via Afdian

CraftEngine API

repositories {
    maven("https://repo.momirealms.net/releases/")
}

dependencies {
    compileOnly("net.momirealms:craft-engine-core:0.0.38")
    compileOnly("net.momirealms:craft-engine-bukkit:0.0.38")
}