craft-engine/readme/README_zh-CN.md

CraftEngine

English | 简体中文 | 繁體中文

📌 关于 CraftEngine

CraftEngine 重新定义了 Minecraft 插件架构，作为下一代自定义内容实现的解决方案。通过 JVM 级别的注入，它提供了前所未有的性能、稳定性和可扩展性。该框架提供了一个代码优先的 API，用于注册原生集成的方块行为和物品交互逻辑。

构建

🐚 命令行

1. 安装 JDK 21。
2. 打开终端并切换到项目文件夹。
3. 执行 ./gradlew build，构建产物将生成在 /target 文件夹中。

💻 IDE

1. 导入项目并执行 Gradle 构建操作。
2. 构建产物将生成在 /target 文件夹中。

安装

💻 环境要求

1. 确保您正在运行 Paper（或其分支）1.20.1+ 服务器。CraftEngine 不支持 Spigot，且未来也不太可能支持。
2. 使用 JDK 21 来运行服务器。

🔍 安装方式

CraftEngine 提供了两种安装模式：标准安装和 Mod 模式。标准安装与传统插件安装方式相同，即将插件放入插件文件夹中。下面我们将详细介绍 Mod 模式的安装步骤。

🔧 安装服务器 Mod

1. 下载最新的 ignite.jar 到您的服务器根目录。
2. 选择以下任一操作：
   • 将您的服务器 JAR 文件重命名为 paper.jar
   • 添加启动参数：-Dignite.locator=paper -Dignite.paper.jar=./paper-xxx.jar
   • 示例：java -Dignite.locator=paper -Dignite.paper.jar=./paper-1.21.4-164.jar -jar ignite.jar
3. 启动服务器以生成 /mods 目录。
4. 将最新的 mod.jar 放入 /mods 文件夹。
5. 将插件的 JAR 文件放入 /plugins 文件夹进行安装。
6. 执行两次重启：
   1. 第一次重启用于文件初始化。
   2. 第二次重启以激活所有组件。

技术概述

⚙️ 方块

CraftEngine 使用运行时字节码生成技术，在服务器原生级别注册自定义方块，并结合客户端数据包修改以实现视觉同步。此架构提供了以下功能：

🧱 自定义原生方块

• 动态注册方块，完全可控。
• 物理属性：硬度、引燃几率、亮度等所有标准属性。
• 自定义行为：通过 API 实现树苗、作物、下落的方块等。
• 原版兼容性：完全保留原版方块机制（例如音符盒、绊线）。

📦 数据包集成

• 定义自定义矿脉。
• 生成自定义树木。
• 配置自定义地形生成。

⚡ 性能优势

• 比传统的 Bukkit 事件监听器更快、更稳定。
• 策略性代码注入以最小化开销。

🥘 配方

CraftEngine 通过底层注入实现完全可定制的合成系统。与传统插件不同，它在处理 NBT 修改时不会失效，确保配方结果仅与唯一的物品标识符绑定。

🪑 家具

该插件使用核心实体来存储家具元数据，同时将碰撞实体和模块组件作为客户端数据包传输。此架构实现了显著的服务器端性能优化，同时支持通过多部分物品集成实现复合家具组装。

📝 模板

鉴于插件配置的广泛性和复杂性，CraftEngine 实现了模块化模板系统以分隔关键设置。这使得用户可以自定义配置格式，同时显著减少冗余的 YAML 定义。

🛠️ 模型

该插件通过配置实现模型继承和纹理覆盖，同时支持从 1.21.4 版本开始的所有物品模型。它包含一个版本迁移系统，可以自动将 1.21.4+ 的物品模型降级为旧格式，以实现最大向后兼容性。

灵感来源

CraftEngine 从以下开源项目中汲取了灵感：

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

核心依赖

CraftEngine 的实现依赖于以下基础库：

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

如何贡献

🔌 新功能与 Bug 修复

如果您提交的 PR 是关于 Bug 修复的，它很可能会被合并。如果您想提交新功能，请提前在 Discord 上联系我。

🌍 翻译

1. 克隆此仓库。
2. 在 /bukkit/loader/src/main/resources/translations 中创建一个新的语言文件。
3. 完成后，提交 pull request 以供审核。我们感谢您的贡献！

💖 支持开发者

如果您喜欢使用 CraftEngine，请考虑支持开发者！

• Polymart: [无]
• BuiltByBit: [无]
• 爱发电: 通过爱发电支持

CraftEngine API

repositories {
    maven("https://repo.momirealms.net/releases/")
    // 如果你的网络环境受限可以尝试下面的存储库地址
    // maven("https://repo-momi.gtemc.cn/releases/")
}

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