Aeonis
一款适用于 Minecraft 的游戏玩法与世界内容模组,支持 Fabric 和 NeoForge。
Aeonis 添加了玩家与生物的变身功能、AI 辅助的命令控制系统、自定义维度与进度挂钩、独特的动画生物,以及配套的渲染和实用工具。
- 版本:5.0.0
- Minecraft:26.3
- 加载器:Fabric 和 NeoForge
- 许可证:GPL-3.0-or-later(见 LICENSE)
依赖项
已针对 26.3 版本的官方 Fabric、NeoForged 和 Mojang 元数据进行了验证。
| 组件 |
版本 |
| Minecraft |
26.3 |
| Java |
25(构建和运行时的最低要求) |
| Gradle |
9.5.1(通过随附的包装器) |
| Fabric Loader |
0.19.5 或更高版本 |
| Fabric API |
0.161.0+26.3 |
| Fabric Language Kotlin |
1.14.1+kotlin.2.4.20 |
| Fabric Loom |
1.17-SNAPSHOT |
| NeoForge |
26.3.0.6-beta |
| NeoGradle (userdev) |
7.1.39 |
| KotlinForForge |
6.3.0 或更高版本 |
| Mod Menu(可选,仅限 Fabric) |
21.0.0-beta.1 |
映射文件使用的是未混淆工作流中的官方 Mojang 映射。Yarn 和中立映射(intermediary)在本项目中已不再使用。
在报告启动问题之前,有两点关于依赖项的注意事项值得阅读:
- NeoForge 尚未发布 26.3 的非 beta 版本。26.3.0.6-beta 是 26.3 分支上的最新版本;没有正式版或候选版(RC)。
- KotlinForForge 尚不支持 Minecraft 26.3。详见 TODO.md 中的 已知限制。
安装
安装与你的加载器匹配的 jar 包。两个 jar 包均源自同一源代码树,不可互换。
- 为 Minecraft 26.3 安装 Fabric Loader 0.19.5+ 或 NeoForge 26.3.0.6-beta。
- 在 Fabric 上,还需安装 Fabric API。
- 将
AeonisCM-5.0.0.jar(Fabric)或 aeonis-5.0.0.jar(NeoForge)放入你的 mods 目录。
- Mod Menu 在 Fabric 上是可选的,仅提供配置入口。
从源码构建
全新克隆后,只需一条命令即可构建两个 jar 包:
./gradlew build
构建产物写入以下位置:
fabric/build/libs/AeonisCM-5.0.0.jar
neoforge/build/libs/aeonis-5.0.0.jar
若仅需构建其中一个加载器:
./gradlew :fabric:build
./gradlew :neoforge:build
首次构建会下载 Minecraft、加载器工具链和映射文件,可能需要几分钟时间。必须提供 Java 25;构建过程请求 Java 25 工具链,不依赖硬编码的 JDK 路径。
测试构建
scripts/ 下的两个辅助脚本可在无需启动器或账户的情况下检查构建结果。
在真实的 PolyMC 实例中启动模组,并确认客户端能正常进入主菜单:
python3 scripts/mc-smoke-test.py
它会构建 Fabric jar 包,将其复制到该实例的 mods/ 文件夹中,使用该实例自身的库和资源启动 Minecraft,并在发生崩溃、Mixin 应用错误或入口点失败时以非零状态退出。使用 --instance、--polymc-home 或 POLYMC_HOME 环境变量可指定其他实例,使用 --no-build 可重用现有的 jar 包,使用 --dry-run 可查看启动命令。
检查所有 Mixin 是否仍指向当前 Minecraft jar 包中存在的代码:
python3 scripts/check-mixin-targets.py
此脚本使用 javap 针对未混淆的 jar 包解析 @Inject、@Redirect、@Accessor 和 @Shadow 选择器,从而捕获那些编译通过但运行时失败的类重命名和签名更改。请先至少运行一次 ./gradlew :fabric:build,以确保它检查的 jar 包已经生成。
项目结构
Aeonis 是一个包含三个模块的 Gradle 构建项目。这种拆分是有意的:模组庞大且涉及大量状态管理,且两种加载器共享同一套游戏玩法系统的实现,以防止两者之间的行为出现无声的分歧。
| 模块 |
用途 |
common |
与加载器无关的游戏逻辑:命令、实体、物品、维度、变形/附身系统以及 AI 助手。在与 Fabric Loom 配合的未混淆工作流下,针对 Minecraft 进行编译。 |
fabric |
Fabric 入口点、Mixin、客户端渲染、网络通信及 fabric.mod.json。 |
neoforge |
NeoForge 入口点、Mixin、客户端渲染、网络通信及 neoforge.mods.toml。 |
两个加载器模块均依赖于 common,并将其输出打包进各自的 jar 包中。
为何采用手动多项目布局
曾考虑过 Architectury API 但最终否决。Aeonis 严重依赖针对原版类的 Mixin,以及需要为每种加载器单独连接事件的特殊变形/附身系统;Architectury 的抽象层不仅无法移除对特定加载器 Mixin 代码的需求,反而会使这些细节变得模糊不清。简单的多项目 Gradle 构建使每种加载器的入口点和 Mixin 保持明确,并让 common 直接拥有共享逻辑。配置界面使用小型的每加载器垫片(shim),而非第三方配置库,因为现有的界面均为手写。
命令
除非另有说明,所有命令均需操作员权限。
变身
| 命令 |
描述 |
/transform <entity> [variant...] |
变身为生物。接受实体 ID 和可选的变体参数。 |
/untransform |
恢复为正常玩家形态。 |
/exitbody s |
退出至生存模式。 |
/exitbody c |
退出至创造模式。 |
示例:
/transform minecraft:zombie
/transform minecraft:wither
/transform minecraft:ender_dragon
/transform minecraft:breeze
/transform minecraft:phantom
/transform minecraft:ghast
/transform minecraft:bee
/transform minecraft:dolphin
/transform minecraft:creeper
/transform minecraft:skeleton
/transform minecraft:blaze
/transform minecraft:enderman
恶作剧
| 命令 |
描述 |
/prank smite <players> |
召唤闪电打击。 |
/prank yeet <players> |
将玩家发射到空中。 |
/prank disco <players> |
派对特效。 |
/prank supersize <players> |
放大玩家。 |
/prank smol <players> |
缩小玩家。 |
/prank chaos <players> |
三种随机效果。 |
/prank rocket <players> |
火箭发射。 |
/prank spin <players> <times> |
旋转玩家。 |
/prank freeze <players> |
原地冻结。 |
/prank burn <players> |
点燃玩家。 |
/prank drunk <players> |
恶心与失明。 |
/prank boing <players> |
超级弹跳。 |
/prank confetti <players> |
烟花纸屑爆发。 |
/prank swap <player_a> <player_b> |
交换两名玩家的位置。 |
/prank morph <players> <type> |
临时变形两分钟。 |
事件工具
| 命令 |
描述 |
/event ambush |
突袭生物埋伏。 |
/event scan |
扫描附近的敌对生物。 |
/event thunder |
开始雷霆竞技场事件。 |
/event copper |
向玩家掉落铜锭。 |
/event time <ticks> |
加速时间流逝。 |
/event cleanse <players> |
移除所有状态效果。 |
/event crit_save |
关键救援(复活)。 |
/event pro_gamer |
职业玩家模式。 |
/event exitbody <s|c> |
退出附身状态(生存或创造模式)。 |
能力
| 命令 |
描述 |
/ability mimic zombie |
播放僵尸环境音效。 |
/ability mimic wither |
播放凋灵环境音效。 |
/ability mimic ghast |
播放恶魂尖叫。 |
/ability mimic dragon |
播放龙咆哮。 |
/ability dash |
快速向前冲刺。 |
/ability blink <range> |
短距离瞬移。 |
/ability jump |
月球跳跃。 |
/ability roar |
监守者咆哮。 |
/ability darkness |
黑暗脉冲。 |
/ability summon vex |
召唤宠物恼鬼。 |
/ability summon wolves <count> |
召唤灵体狼。 |
AI 工具
| 命令 |
描述 |
/ai chaotic <entities> |
启用混乱 AI(实验性)。 |
/ai chaotic stop |
禁用混乱 AI。 |
/ai director <entities> walk_to <x y z> [speed] |
引导实体移动到指定位置。 |
/ai director <entities> look_at <target> |
使实体注视目标。 |
/ai director <entities> attack <target> |
使实体攻击目标。 |
/ai director <entities> stop |
停止实体的所有指令。 |
系统与功能
| 命令 |
描述 |
/aeonis soul |
进入灵魂模式(旁观者,按 P 键附身)。 |
/aeonis unsoul |
退出灵魂模式。 |
/aeonis sys ping |
显示服务器和模组统计信息。 |
/aeonis sys story |
显示 Aeonis 故事背景文本。 |
/aeonis help |
显示游戏内帮助列表。 |
/aeonis reload |
重新加载所有模组功能并重置状态。 |
/aeonis features extra_mobs |
查询是否启用了 Aeonis 自定义生物。 |
/aeonis features extra_mobs <true|false> |
启用或禁用 Aeonis 自定义生物生成。 |
伙伴机器人
| 命令 |
描述 |
/comp spawn |
生成一个伙伴机器人。 |
/comp mode <mode> |
设置伙伴行为模式(攻击、跟随、撤退)。 |
AI 助手
/ai 命令树由可配置的 LLM(大型语言模型)集成支持,兼容 OpenAI、OpenRouter 和 Gemini。API 密钥和服务商选择通过游戏内配置界面或 Aeonis/llm 配置文件进行设置。该助手既可以发出命令也可以运行已保存的脚本,并且受操作员配置的允许执行命令白名单限制。请将 API 密钥视为机密:它们存储在配置文件中,而非世界存档中。
维护者须知
更新到新 Minecraft 版本
从 26.1 到 26.3 的更新遵循了以下检查清单。此处保留它是因为对于下一个版本升级,这仍然是正确的顺序。
- 更新 Gradle wrapper 并确认新版本所需的 Java 基线。
- 在
gradle.properties 中更新新的 Minecraft、加载器、Fabric API、NeoForge、Loom 和 Kotlin 版本。请针对其官方来源验证每一项,而不是复制博客文章;Beta 标签会很快转正。
- 重新检查映射假设。本项目在未混淆的工作流中使用 Mojang 官方映射;不要重新引入 Yarn 或 intermediary。
- 排查被移除或重命名的原版 API。26.3 更新要求,例如将实体常量从
EntityType 移至 EntityTypes,将 Entity.hurtMarked 重命名为 syncVelocity,将 Entity.setInvulnerable 替换为 setPermanentlyInvulnerable,将当前屏幕从 Minecraft 移至 Gui,用 GuiGraphicsExtractor 替换用于 HUD 元素的 GuiGraphics,以及将 InputConstants.Type.KEYSYM 重命名为 KEYBOARD。
- 根据新映射审计每个 mixin。当 mixin 的目标消失时,它们会在运行时而非编译时报错,因此需要手动逐一检查。
- 重新验证世界生成和数据包注册表。旧版数据包内容目前在加载器模块的
processResources 中被排除;详见 TODO.md。
- 在两种加载器上回归测试经过转换的游戏玩法路径,特别是转换和取消转换的清理过程。
- 更新此 README、
CHANGELOG.md 和模组元数据文件。
发布
- 在
gradle.properties 中设置 mod_version。
- 运行
./gradlew clean build 并确认生成了两个 jar 文件。
- 验证每个 jar 内部
fabric.mod.json 和 neoforge.mods.toml 中嵌入的版本号。
- 添加
CHANGELOG.md 条目。
Changelog 条目位于 CHANGELOG.md。
许可证
Aeonis 采用 GNU General Public License v3.0 或更高版本授权。
版权所有 (C) 2025-2026 Aevora Labs。请参阅 LICENSE。
Aeonis
A gameplay and world-content mod for Minecraft, available for both Fabric and NeoForge.
Aeonis adds player and mob transformation, AI-assisted command and control systems,
custom dimensions and progression hooks, unique animated mobs, and supporting
rendering and utility tooling.
- Version: 5.0.0
- Minecraft: 26.3
- Loaders: Fabric and NeoForge
- License: GPL-3.0-or-later (see LICENSE)
Requirements
Verified against the official Fabric, NeoForged, and Mojang metadata for the 26.3 line.
| Component |
Version |
| Minecraft |
26.3 |
| Java |
25 (minimum for both build and runtime) |
| Gradle |
9.5.1 (via the included wrapper) |
| Fabric Loader |
0.19.5 or newer |
| Fabric API |
0.161.0+26.3 |
| Fabric Language Kotlin |
1.14.1+kotlin.2.4.20 |
| Fabric Loom |
1.17-SNAPSHOT |
| NeoForge |
26.3.0.6-beta |
| NeoGradle (userdev) |
7.1.39 |
| KotlinForForge |
6.3.0 or newer |
| Mod Menu (optional, Fabric only) |
21.0.0-beta.1 |
Mappings are the official Mojang mappings in the unobfuscated workflow. Yarn and
intermediary are no longer used anywhere in this project.
Two dependency notes worth reading before reporting a launch problem:
- NeoForge has not published a non-beta build for 26.3 yet. 26.3.0.6-beta is the
newest build on the 26.3 line; there is no release or RC.
- KotlinForForge does not yet support Minecraft 26.3. See
Known limitations in TODO.md.
Installation
Install the jar that matches your loader. Both jars are built from the same source
tree and are not interchangeable.
- Install Fabric Loader 0.19.5+ or NeoForge 26.3.0.6-beta for Minecraft 26.3.
- On Fabric, also install Fabric API.
- Place
AeonisCM-5.0.0.jar (Fabric) or aeonis-5.0.0.jar (NeoForge) in your
mods directory.
- Mod Menu is optional on Fabric and only provides the config entry point.
Building from source
A fresh clone builds both jars with a single command:
./gradlew build
Artifacts are written to:
fabric/build/libs/AeonisCM-5.0.0.jar
neoforge/build/libs/aeonis-5.0.0.jar
To build one loader only:
./gradlew :fabric:build
./gradlew :neoforge:build
The first build downloads Minecraft, the loader toolchains, and mappings, and can
take several minutes. Java 25 must be available; the build requests a Java 25
toolchain and does not rely on a hardcoded JDK path.
Testing a build
Two helpers under scripts/ check a build without needing a launcher or an account.
Boot the mod in a real PolyMC instance and confirm the client reaches the main menu:
python3 scripts/mc-smoke-test.py
It builds the Fabric jar, copies it into the instance's mods/ folder, launches
Minecraft with that instance's own libraries and assets, and exits non-zero on a
crash, a mixin apply error or an entrypoint failure. Use --instance,
--polymc-home or the POLYMC_HOME environment variable to target another instance,
--no-build to reuse the existing jar, and --dry-run to inspect the launch command.
Check that every mixin still targets code that exists in the current Minecraft jar:
python3 scripts/check-mixin-targets.py
This resolves @Inject, @Redirect, @Accessor and @Shadow selectors against the
deobfuscated jar with javap, catching renames and signature changes that compile
cleanly and then fail at runtime. Run ./gradlew :fabric:build at least once first, so
that the jar it inspects has been produced.
Project layout
Aeonis is a three-module Gradle build. The split is deliberate: the mod is large
and stateful, and both loaders share a single implementation of the gameplay
systems so that behaviour cannot silently diverge between them.
| Module |
Purpose |
common |
Loader-agnostic game logic: commands, entities, items, dimensions, the transform/possession system, and the AI assistant. Compiled against Minecraft with Fabric Loom in the unobfuscated workflow. |
fabric |
Fabric entrypoints, mixins, client rendering, networking, and fabric.mod.json. |
neoforge |
NeoForge entrypoints, mixins, client rendering, networking, and neoforge.mods.toml. |
Both loader modules depend on common and shade its output into their own jar.
Why a manual multi-project layout
Architectury API was considered and rejected. Aeonis depends heavily on mixins
targeting vanilla classes and on a custom transform/possession system that needs
per-loader event wiring; Architectury's abstraction layer would have obscured those
without removing the need for loader-specific mixin code. A plain multi-project
Gradle build keeps each loader's entrypoints and mixins explicit and lets common
own the shared logic directly. Config screens use a small per-loader shim rather
than a third-party config library, since the existing screens are hand-written.
Commands
All commands require operator permissions unless noted.
Transformation
| Command |
Description |
/transform <entity> [variant...] |
Transform into a mob. Accepts an entity ID and optional variant arguments. |
/untransform |
Return to your normal player form. |
/exitbody s |
Exit to Survival mode. |
/exitbody c |
Exit to Creative mode. |
Examples:
/transform minecraft:zombie
/transform minecraft:wither
/transform minecraft:ender_dragon
/transform minecraft:breeze
/transform minecraft:phantom
/transform minecraft:ghast
/transform minecraft:bee
/transform minecraft:dolphin
/transform minecraft:creeper
/transform minecraft:skeleton
/transform minecraft:blaze
/transform minecraft:enderman
Prank
| Command |
Description |
/prank smite <players> |
Strike with lightning. |
/prank yeet <players> |
Launch into the sky. |
/prank disco <players> |
Party effects. |
/prank supersize <players> |
Scale players up. |
/prank smol <players> |
Scale players down. |
/prank chaos <players> |
Three random effects. |
/prank rocket <players> |
Rocket launch. |
/prank spin <players> <times> |
Spin players. |
/prank freeze <players> |
Freeze in place. |
/prank burn <players> |
Set on fire. |
/prank drunk <players> |
Nausea and blindness. |
/prank boing <players> |
Super bounce. |
/prank confetti <players> |
Firework confetti burst. |
/prank swap <player_a> <player_b> |
Swap two players. |
/prank morph <players> <type> |
Temporary transform for two minutes. |
Event tools
| Command |
Description |
/event ambush |
Surprise mob ambush. |
/event scan |
Scan for hostiles nearby. |
/event thunder |
Start the thunder dome event. |
/event copper |
Drop copper on players. |
/event time <ticks> |
Warp time forward. |
/event cleanse <players> |
Remove all effects. |
/event crit_save |
Critical save (revive). |
/event pro_gamer |
Pro gamer mode. |
/event exitbody <s|c> |
Exit body (Survival or Creative). |
Abilities
| Command |
Description |
/ability mimic zombie |
Play the zombie ambient sound. |
/ability mimic wither |
Play the wither ambient sound. |
/ability mimic ghast |
Play the ghast cry. |
/ability mimic dragon |
Play the dragon growl. |
/ability dash |
Quick dash forward. |
/ability blink <range> |
Teleport a short distance. |
/ability jump |
Moon jump. |
/ability roar |
Warden roar. |
/ability darkness |
Darkness pulse. |
/ability summon vex |
Summon a pet vex. |
/ability summon wolves <count> |
Summon spirit wolves. |
AI tools
| Command |
Description |
/ai chaotic <entities> |
Enable chaotic AI (experimental). |
/ai chaotic stop |
Disable chaotic AI. |
/ai director <entities> walk_to <x y z> [speed] |
Walk entities to a position. |
/ai director <entities> look_at <target> |
Make entities look at a target. |
/ai director <entities> attack <target> |
Make entities attack a target. |
/ai director <entities> stop |
Stop all orders for entities. |
System and features
| Command |
Description |
/aeonis soul |
Enter soul mode (spectator, possess with the P key). |
/aeonis unsoul |
Exit soul mode. |
/aeonis sys ping |
Show server and mod stats. |
/aeonis sys story |
Show Aeonis story flavour text. |
/aeonis help |
Show the in-game help listing. |
/aeonis reload |
Reload all mod features and reset state. |
/aeonis features extra_mobs |
Query whether Aeonis custom mobs are enabled. |
/aeonis features extra_mobs <true|false> |
Enable or disable Aeonis custom mob spawning. |
Companion bots
| Command |
Description |
/comp spawn |
Spawn a companion bot. |
/comp mode <mode> |
Set the companion behaviour mode (attack, follow, retreat). |
AI assistant
The /ai command tree is backed by a configurable LLM integration supporting
OpenAI, OpenRouter, and Gemini. API keys and provider selection are configured
through the in-game config screen or the Aeonis/llm config file. The assistant can
both issue commands and run saved scripts, and it is subject to an operator-configurable
allowlist of executable commands. Treat API keys as secrets: they are stored in the
config file, not in the world save.
Maintainer notes
Updating to a new Minecraft version
The 26.1 to 26.3 update followed this checklist. It is kept here because it remains
the right sequence for the next version bump.
- Update the Gradle wrapper and confirm the Java baseline the new version requires.
- Update
gradle.properties with the new Minecraft, loader, Fabric API, NeoForge,
Loom, and Kotlin versions. Verify each against its official source rather than
copying a blog post; beta tags are promoted quickly.
- Re-check mapping assumptions. This project uses official Mojang mappings in the
unobfuscated workflow; do not reintroduce Yarn or intermediary.
- Sweep for removed or renamed vanilla API. The 26.3 update required, among others,
moving entity constants from
EntityType to EntityTypes, renaming
Entity.hurtMarked to syncVelocity, replacing Entity.setInvulnerable with
setPermanentlyInvulnerable, moving the current screen from Minecraft to
Gui, replacing GuiGraphics with GuiGraphicsExtractor for HUD elements,
and renaming InputConstants.Type.KEYSYM to KEYBOARD.
- Audit every mixin against the new mappings. Mixins fail at runtime rather than
compile time when their target disappears, so check each one by hand.
- Re-validate worldgen and data pack registries. Legacy datapack content is
currently excluded from
processResources in the loader modules; see
TODO.md.
- Regression-test the transformed-gameplay paths on both loaders, especially
transform and untransform cleanup.
- Update this README,
CHANGELOG.md, and the mod metadata files.
Releasing
- Set
mod_version in gradle.properties.
- Run
./gradlew clean build and confirm both jars are produced.
- Verify the version stamped into
fabric.mod.json and neoforge.mods.toml
inside each jar.
- Add a
CHANGELOG.md entry.
Changelog entries live in CHANGELOG.md.
License
Aeonis is licensed under the GNU General Public License v3.0 or later.
Copyright (C) 2025-2026 Aevora Labs. See LICENSE.
评论 0
登录后参与评分
还没有评论,来抢沙发吧