Accelerated Recoiling

Accelerated Recoiling is a mod focused on optimizing server-side entity collision logic. It utilizes the Java 21+ FFM (Foreign Function & Memory) API to take over entity AABB collision detection, offloading highly intensive computational workloads to a native C++ library, thereby significantly improving server performance.

This mod is currently experimental, and the entity cramming behavior is not entirely identical to vanilla. Please be sure to use it with caution and back up your saves beforehand.

Official QQ Group: 1023713677

Requirements & Dependencies

Java 21 or higher: You must use Java 21 or Java 21+ to launch the game/server (the FFM API is a preview feature in Java 21).
64-bit OS: Native libraries (.dll / .so) only support 64-bit environments.
Windows Platform: Requires the Microsoft Visual C++ Redistributable (if the game fails to launch, please install this first).
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 the acceleratedRecoiling.json configuration file.

Default Configuration & Explanations:

{
   "enableEntityCollision": true,      // Whether to enable entity cramming optimization
   "enableEntityGetterOptimization": true, // Enable EntityGetter interface optimization (currently ineffective)
   "maxCollision": 32,                 // Maximum number of collision interactions per entity
   "gridSize": 1,                      // Algorithm grid size
   "densityWindow": 4,                 // Density smoothing window
   "densityThreshold": 16              // Density threshold of surrounding entities to trigger accelerated recoiling
}

Note: If performance decreases instead of improving after enabling the mod, please try lowering the densityThreshold.

FAQ (Q&A)

Q: Why does the game crash or fail to launch? A: Please troubleshoot using the following steps:

Ensure Java 21+ and the MSVC Redistributable are correctly installed.
If your client is NeoForge 1.21.1/1.21.8, try launching the game with Java 22+.
If using a Leaves server, ensure your launch arguments include -Dleavesclip.enable.mixin=true.
If you recently updated the mod, try deleting acceleratedRecoilingLib.dll and acceleratedRecoiling.json in the root directory or your .minecraft folder, then restart the game to let them regenerate.

Q: Is the entity cramming behavior identical to vanilla? A: Not completely. This mod is currently experimental and alters the underlying calculation logic, so the cramming behavior will differ from vanilla. Please make sure to back up your saves before using.

Q: Will it affect Technical Minecraft (TMC) mechanics? A: It is currently unknown. It might affect Redstone contraptions/farms that rely 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 is possible that the density of surrounding entities hasn't reached the threshold to trigger the optimization, causing the game to run both the vanilla and accelerated recoiling calculation paths simultaneously. Please open the config file and try appropriately lowering the densityThreshold value.

Performance Benchmarks

Test Environment: i5-12600KF | 32GB RAM | RTX 3060 Ti | Leaves 1.21.8 | GraalVM JDK 21

Test 1: TPS Changes (Spawning entities within a 2x2 space in the same chunk)

Entity Count	Leaves + Accelerated Recoiling	Vanilla Leaves	Performance Boost
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 Execution Time (Pure C++ side 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

To-Do List (TODO)

MacOS compatibility
Luminol support

Building from Source

The project uses Gradle to invoke MSVC and WSL for cross-platform compilation (generating .dll and .so). It is recommended to operate in a Windows 10/11 environment with WSL installed.

1. Environment Preparation

Install JDK 21.
Install Visual Studio 2022, ensuring "Desktop development with C++" is checked.
Install build tools in WSL: sudo apt update && sudo apt install build-essential libgomp1 -y

2. Modify Script Path Open build.gradle.kts, find the compileNativeLib task, and replace the value of the vcvarsScript variable with the actual path to vcvars64.bat on your local machine.

3. Build Run the following commands in the project's root directory:

gradlew jar
gradlew build

The compiled artifacts (Jars containing the dynamic libraries for both platforms) will be generated in the build/libs/ directory.

Credits & License

This project is open-sourced under the MIT License. Special thanks to the following developers for their tremendous help with the core concepts and code porting of this project:

Argon4W: Original concept and core ideas.
fireboy637: Core code for the Architectury API porting solution.
hydropuse: Core code for the JDK 22 compatibility solution.