Accelerated Recoiling

# 加速碰撞 (Accelerated Recoiling) 加速碰撞是一个专注于优化服务端实体碰撞逻辑的模组。它利用 FFM (Foreign Function & Memory) API/JNI 接管实体 AABB 碰撞检测，将高密集计算压力转移至 C++ 原生库，从而显著提升服务器性能。 **本模组目前为实验性质，实体挤压表现与原版不完全一致。请务必在做好存档备份的前提下谨慎使用。如果在意原版特性还原程度，请切换至Java Vanilla后端** 官方交流群：1023713677 ## 特性介绍 * **实体碰撞性能提升**：通过将底层的碰撞逻辑交由 C++ 处理，打破 Java 在处理海量实体碰撞时的性能瓶颈。在测试条件下（同一区块数千实体），TPS 提升可达数十倍。 * **算法优化**：引入效率更高的碰撞算法，避免了原版 O(N^2) 复杂度的实体遍历，降低 CPU 负担。 * **阈值触发**：只有当局部实体密度达到设定阈值时才会使用 C++ 加速算法，保证常规游戏场景下的稳定与原版体验。 * **多端支持**：同时包含Windows/Linux/MacOS的运行库，未来版本将支持arm64 * **动态后端选择机制**: 同时包含多个后端并自动选择当前可以应用且效率最高的后端 | 后端 | 实现说明 | 要求 | 性能 (预期) | 状态 | | :--- | :--- | :--- | :--- | :--- | | **GPU** | 使用 GPU 算法加速碰撞 | 需图形硬件支持 | 最高 | 可用 | | **FFM** | 使用 FFM API 与 C++ 层进行通信 | 需要使用 JDK 21或以上的Java版本启动游戏 | 非常高 | 可用 | | **JNI** | 使用 JNI 与 C++ 层进行通信 | 无 | 非常高 | 可用 | | **Java SIMD** | 使用加速碰撞的 Java VectorAPI 算法 | 需添加启动参数 | 高 | 可用 | | **Java** | 使用加速碰撞的 Java 原生算法 | 无 | 良好 | 可用 | | **Java Vanilla** | 在原版的实体遍历下直接修改实体碰撞筛选逻辑（原版特性还原程度最高） | 无 | 偏差 | 可用 | | **Vanilla** | 原版的碰撞逻辑 | 无 | 最差 | - | 如果需要手动切换后端，请在游戏启动时添加参数`-Dacceleratedrecoiling.backend=后端名称` ## 环境要求与前置 * **64位操作系统**：本机库 (`.dll` / `.so`) 仅支持 64 位环境。 * **Leaves 端**：启动参数中必须包含 `-Dleavesclip.enable.mixin=true`。 ## 安装与配置 首次启动时，模组会自动在根目录释放本机库文件，并生成 `acceleratedRecoiling.json` 配置文件。 **默认配置及说明：** ```json { "enableEntityCollision": true, // 是否启用实体挤压优化 "enableEntityGetterOptimization": true, // 启用EntityGetter接口优化(暂时无效) "maxCollision": 32, // 单个实体最大碰撞交互数 "gridSize": 1, // 算法网格大小 "densityWindow": 4, // 密度平滑窗口 "densityThreshold": 16 // 触发加速碰撞的周围实体密度阈值 } ``` *注：若开启后性能不升反降，请尝试调低 `densityThreshold`。* *如果CPU占用过高，请调低maxThreads* ## 常见问题 (Q&A) **Q: 为什么游戏崩溃或无法启动？**
**A:** 请按以下步骤排查： 1. 确认已正确安装 Java 17+ 2. 若使用 **Leaves** 服务端，确保启动参数包含 `-Dleavesclip.enable.mixin=true`。 3. 如果更新过模组，尝试删除根目录或 `.minecraft` 下的 `acceleratedRecoilingLib.dll`与`acceleratedRecoiling.json`，然后重启游戏让其重新生成。 **Q: 开启后实体挤压表现和原版一样吗？**
**A:** 不完全一致。本模组目前为实验性质，改变了底层计算逻辑，因此挤压表现会与原版有差异。**请务必在使用前做好存档备份。** **Q: 会影响生电特性吗？**
**A:** 目前没有找到因加速碰撞而失效的红石机器，但推测可能会影响与实体挤压有关的红石机器，**请务必在使用前做好存档备份。** **Q: 为什么开启模组后，服务器性能反而下降了？**
**A:** 可能是周围实体密度未达到触发优化的条件，因此同时走了原版和加速碰撞的两条路径。请尝试打开配置文件，适当调低 `densityThreshold` 的数值。或尝试调低`maxThreads`。 **Q: 会不会和某些模组不兼容？**
**A:** 完全不会，根据我们目前的测试，加速碰撞与 ATM9 整合包完全兼容 同时兼容 * [Lithium](https://github.com/CaffeineMC/lithium) * [FlatCollision](https://github.com/PooSmacker/FlatCollision) * [RuOK](https://github.com/MCTeamPotato/RuOK) * [Create](https://github.com/Creators-of-Create/Create) * [Valkyrien-Skies-2](https://github.com/ValkyrienSkies/Valkyrien-Skies-2)
等多个大型模组。如果发现有不兼容的模组，请在本仓库提交Issue。 **Q: FFM 是Java 21的预览功能，我是否应该使用Java 21+启动游戏？**
**A:** 如果你的游戏版本是*1.21.1*以上，那么是的，但这是**1.21.1**版本本身需要**Java 21**来运行。
如果你的游戏是*1.20.1*，那么不需要，加速碰撞*v0.10.0-alpha-1.20.1*以上的版本**同时支持最新版JDK到Java 17**之间的任意JDK版本。
（* 注: 1.20.1 的最低可运行 Java 即为 Java 17 *） ## 性能基准测试 **测试环境:** i5-12600KF | 32GB RAM | RTX 3060 Ti | Leaves 1.21.8 | GraalVM JDK 21 **测试一：TPS 变化 (同一区块 2x2 空间内生成实体)** | 实体数量 | Leaves + 加速碰撞 | 原版 Leaves | 提升倍率 | | :--- | :--- | :--- | :--- | | **2,048** | **20.0 TPS** (16 MSPT) | 3.0 TPS | 20.8x | | **4,096** | **20.0 TPS** (27 MSPT) | 0.5 TPS | 74x | | **16,384** | **8.6 TPS** (115 MSPT) | - | - | | **32,768** | **4.3 TPS** (230 MSPT) | - | - | **测试二：BroadPhase 耗时 (纯 C++ 端处理性能)** | 实体数量 | MS / Frame (每帧耗时) | 等效 FPS | | :--- | :--- | :--- | | 10,000 | 0.2 ms | 5000 | | 50,000 | 1.1 ms | 909 | | 100,000 | 2.5 ms | 400 | | 400,000 | 21.3 ms | 46 | ## 源码编译 项目通过 Gradle 调用 MSVC 和 WSL 进行双端跨平台编译 (生成 `.dll` 和 `.so`)，建议在装有 WSL 的 Windows 10/11 环境下操作。 **1. 环境准备** * 安装 JDK 21。(必须) * 克隆本仓库 **2. 构建** 在项目根目录运行以下命令： ```bash gradlew jar gradlew build ``` 编译产物 (包含双端动态库的 Jar) 将生成在 `build/libs/` 目录下。 ## 支持与赞助 如果你喜欢 **加速碰撞 (Accelerated Recoiling)**，欢迎来 **[这里](https://github.com/wiyuka0/AcceleratedRecoiling/blob/master/3ae91be2c6a1e7447635b7b1b7454ffc.jpeg)** 请wiyuka吃一顿带鱼哦 owo ## 鸣谢与开源协议 本项目基于 **MIT 协议** 开源。 特别感谢以下开发者对本项目的核心思路与代码移植提供的巨大帮助： * **[Argon4W](https://github.com/Argon4W)**: 原始构思与核心思路。 * **[fireboy637](https://github.com/fireboy637)**: Architectury API 移植方案的核心代码。 * **[hydropuse](https://github.com/hydropuse)**: JDK 22 兼容方案的核心代码。 * **[wellcoming](https://github.com/wellcoming)**: Docker Ubuntu镜像解决方案。 * **[grayawa](https://github.com/grayawa)**: Linux 上的构建问题修复 * **[TomatoPuddin](https://github.com/TomatoPuddin)**: 跨平台构建(Windows/Linux/MacOS/Android) 与 C++ 层的重构 --- ## 开源协议 该项目使用 MIT 开源协议开源。 # Accelerated Recoiling (English) Accelerated Recoiling is a mod focused on optimizing server-side entity collision logic. It utilizes the FFM (Foreign Function & Memory) API/JNI to take over entity AABB collision detection, offloading highly intensive computing pressure to a native C++ library, thereby significantly improving server performance. **This mod is currently in the experimental phase, and entity cramming/collision behavior is not entirely identical to Vanilla. Please use it with caution and ENSURE YOU HAVE WORLD BACKUPS before using it. If you strictly care about Vanilla parity, please switch to the Java Vanilla backend.** Official QQ Group: 1023713677 ## Features * **Entity Collision Performance Boost**: By handing over low-level collision logic to C++, it breaks through Java's performance bottlenecks when processing massive entity collisions. Under test conditions (thousands of entities in the same chunk), TPS can be increased by dozens of times. * **Algorithm Optimization**: Introduces highly efficient collision algorithms, avoiding Vanilla's $O(N^2)$ entity iteration complexity and reducing CPU load. * **Threshold Trigger**: The C++ acceleration algorithm is only utilized when the local entity density reaches a configured threshold. This ensures stability and a Vanilla-like experience in regular gameplay scenarios. * **Multi-Platform Support**: Includes native libraries for Windows, Linux, and macOS. ARM64 support will be added in future versions. * **Dynamic Backend Selection**: Contains multiple backends and automatically selects the most efficient one applicable to your current environment. | Backend | Implementation Details | Requirements | Performance (Expected) | Status | | :--- | :--- | :--- | :--- | :--- | | **GPU** | Uses GPU algorithms to accelerate collisions | Requires Graphics Hardware | Highest | Available | | **FFM** | Uses FFM API to communicate with the C++ layer | Requires launching the game with JDK 21+ | Very High | Available | | **JNI** | Uses JNI to communicate with the C++ layer | None | Very High | Available | | **Java SIMD** | Uses Java VectorAPI algorithms for acceleration | Requires specific launch arguments | High | Available | | **Java** | Uses native Java algorithms for acceleration | None | Good | Available | | **Java Vanilla** | Modifies entity collision filtering logic directly under Vanilla's entity iteration (Highest Vanilla parity) | None | Variant | Available | | **Vanilla** | Default Vanilla collision logic | None | Lowest | - | If you need to manually switch backends, please add the launch argument `-Dacceleratedrecoiling.backend=` when starting the game. ## Requirements & Prerequisites * **64-bit OS**: Native libraries (`.dll` / `.so`) only support 64-bit environments. * **Leaves Server**: The launch arguments must include `-Dleavesclip.enable.mixin=true`. ## Installation & Configuration Upon the first launch, the mod will automatically extract the native library files to the root directory and generate an `acceleratedRecoiling.json` configuration file. **Default Configuration & Explanation:** ```json { "enableEntityCollision": true, // Whether to enable entity collision optimization "enableEntityGetterOptimization": true, // Enable EntityGetter interface optimization (Currently inactive/WIP) "maxCollision": 32, // Maximum collision interactions per single entity "gridSize": 1, // Algorithm grid size "densityWindow": 4, // Density smoothing window "densityThreshold": 16 // Surrounding entity density threshold to trigger acceleration } ``` *Note: If performance drops after enabling the mod, try lowering `densityThreshold`.* *If CPU usage is too high, try lowering `maxThreads`.* ## Q&A **Q: Why does the game crash or fail to start?**
**A:** Please troubleshoot using the following steps: 1. Ensure Java 17+ is installed correctly. 2. If using a **Leaves** server, make sure the launch arguments include `-Dleavesclip.enable.mixin=true`. 3. If you recently updated the mod, try deleting `acceleratedRecoilingLib.dll` and `acceleratedRecoiling.json` from the root directory or `.minecraft` folder, then restart the game to let them regenerate. **Q: Is the entity cramming behavior the same as Vanilla after enabling?**
**A:** Not entirely identical. This mod is currently experimental and alters the low-level calculation logic, so cramming behaviors will differ from Vanilla. **Please make sure to back up your saves before using.** **Q: Will it break Technical Minecraft (TMC) / Redstone mechanics?**
**A:** Currently, we haven't found any redstone contraptions broken specifically by Accelerated Recoiling, but it is speculated that it might affect machines reliant on entity cramming. **Please make sure to back up your saves before using.** **Q: Why did server performance drop after enabling the mod?**
**A:** It might be because the surrounding entity density hasn't reached the threshold to trigger the optimization, causing the game to run both the Vanilla and Accelerated collision paths simultaneously. Try opening the config file and lowering the `densityThreshold` value, or try lowering `maxThreads`. **Q: Will it be incompatible with certain mods?**
**A:** Not at all. Based on our current testing, Accelerated Recoiling is fully compatible with the ATM9 modpack. It is also compatible with several major mods including: * [Lithium](https://github.com/CaffeineMC/lithium) * [FlatCollision](https://github.com/PooSmacker/FlatCollision) * [RuOK](https://github.com/MCTeamPotato/RuOK) * [Create](https://github.com/Creators-of-Create/Create) * [Valkyrien-Skies-2](https://github.com/ValkyrienSkies/Valkyrien-Skies-2)
If you discover any incompatible mods, please submit an Issue on this repository. **Q: FFM is a preview feature in Java 21. Should I launch the game with Java 21+?**
**A:** If your game version is *1.21.1* or higher, then yes, but that's because **1.21.1** itself requires **Java 21** to run.
If your game is *1.20.1*, then no. Accelerated Recoiling versions *v0.10.0-alpha-1.20.1* and above support **any JDK version from Java 17 up to the latest JDK**.
(*Note: The minimum runnable Java version for 1.20.1 is Java 17.*) ## Performance Benchmarks **Test Environment:** i5-12600KF | 32GB RAM | RTX 3060 Ti | Leaves 1.21.8 | GraalVM JDK 21 **Test 1: TPS Change (Entities spawned in a 2x2 space within the same chunk)** | Entity Count | Leaves + Accelerated Recoiling | Vanilla Leaves | Multiplier | | :--- | :--- | :--- | :--- | | **2,048** | **20.0 TPS** (16 MSPT) | 3.0 TPS | 20.8x | | **4,096** | **20.0 TPS** (27 MSPT) | 0.5 TPS | 74x | | **16,384** | **8.6 TPS** (115 MSPT) | - | - | | **32,768** | **4.3 TPS** (230 MSPT) | - | - | **Test 2: BroadPhase Time (Pure C++ Backend Performance)** | Entity Count | MS / Frame | Equivalent FPS | | :--- | :--- | :--- | | 10,000 | 0.2 ms | 5000 | | 50,000 | 1.1 ms | 909 | | 100,000 | 2.5 ms | 400 | | 400,000 | 21.3 ms | 46 | ## Source Code Compilation The project uses Gradle to invoke MSVC and WSL for cross-platform compilation (generating `.dll` and `.so`). It is recommended to perform this in a Windows 10/11 environment with WSL installed. **1. Environment Preparation** * Install JDK 21 (Required). * Clone this repository. **2. Building** Run the following commands in the project root directory: ```bash gradlew jar gradlew build ``` The compiled artifacts (a Jar containing the cross-platform dynamic libraries) will be generated in the `build/libs/` directory. ## Support & Sponsorship If you like **Accelerated Recoiling**, feel free to come **[here](https://github.com/wiyuka0/AcceleratedRecoiling/blob/master/3ae91be2c6a1e7447635b7b1b7454ffc.jpeg)** to buy wiyuka a meal of ribbonfish owo! ## Credits & Open Source License This project is open-sourced under the **MIT License**. Special thanks to the following developers for their massive help with the core concepts and code porting of this project: * **[Argon4W](https://github.com/Argon4W)**: Original concept and core ideas. * **[fireboy637](https://github.com/fireboy637)**: Core code for the Architectury API port. * **[hydropuse](https://github.com/hydropuse)**: Core code for JDK 22 compatibility. * **[wellcoming](https://github.com/wellcoming)**: Docker Ubuntu image solutions. * **[grayawa](https://github.com/grayawa)**: Build issue fixes on Linux. * **[TomatoPuddin](https://github.com/TomatoPuddin)**: Cross-platform building (Windows/Linux/MacOS/Android) and C++ layer refactoring.