# grimanticheat/grim architecture

> Architecture diagram of the GitHub repository grimanticheat/grim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/grimanticheat/grim
- Repository: https://github.com/grimanticheat/grim

## Overview

GrimAC is a Minecraft server anticheat. Server packet events feed per-player state and checks; movement checks compare observed motion against version-aware movement predictions, using a latency-compensated world and inventory replica. Violations can then inform alerts, punishment, and operator commands. Bukkit and Fabric provide server-specific adapters around the shared core. The README documents the major simulation, replication, and compensation capabilities; source excerpts show prediction, player state, platform initialization, and command registration, but do not expose every runtime dispatch.

Main entry points: [`common/src/main/java/ac/grim/grimac/predictionengine/predictions/PredictionEngine.java`](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/predictionengine/predictions/PredictionEngine.java) (Movement prediction), [`common/src/main/java/ac/grim/grimac/player/GrimPlayer.java`](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/player/GrimPlayer.java) (Player state), [`common/src/main/java/ac/grim/grimac/checks/Check.java`](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/checks/Check.java) (Anticheat checks), [`common/src/main/java/ac/grim/grimac/utils/nmsutil/Collisions.java`](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/nmsutil/Collisions.java) (Collision geometry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Server integration"]
  node_bukkit["Bukkit adapter"]
  node_fabric["Fabric adapters"]
  node_api["Platform API"]
  node_permission["Permission defaults"]
end

subgraph group_runtime["Player runtime"]
  node_lifecycle["Core lifecycle<br/>[GrimAPI.java]"]
  node_player["Player state<br/>[GrimPlayer.java]"]
  node_packets["Packet processing"]
  node_world[("World replica")]
  node_inventory["Inventory tracking"]
end

subgraph group_detection["Detection and response"]
  node_checks["Anticheat checks<br/>[Check.java]"]
  node_checkmanager["Check manager<br/>[CheckManager.java]"]
end

subgraph group_simulation["Simulation internals"]
  node_prediction["Movement prediction"]
  node_rideable["Vehicle prediction"]
  node_collision["Collision geometry<br/>[Collisions.java]"]
  node_bounds["Player bounds"]
  node_stuck["Movement modifiers<br/>[StuckSpeed.java]"]
  node_vectors["Motion vectors<br/>[VectorData.java]"]
  node_math["Vector math<br/>[Vector3dm.java]"]
  node_entities["Entity state<br/>[PacketEntity.java]"]
  node_blockproperties["Block properties"]
  node_materials["Materials<br/>[Materials.java]"]
  node_box["Collision boxes"]
  node_grimmath["Numeric helpers<br/>[GrimMath.java]"]
end

subgraph group_operations["Operations"]
  node_logging["Logging<br/>[LogUtil.java]"]
  node_commands["Admin commands"]
  node_alerts["Alerts and punishment"]
end

node_server(("Minecraft server"))
node_operator(("Server operator"))

node_server -.->|"hosts plugin"| node_bukkit
node_server -.->|"hosts mod"| node_fabric
node_bukkit -.->|"initializes core"| node_lifecycle
node_fabric -.->|"initializes core"| node_lifecycle
node_lifecycle -.->|"manages players"| node_player
node_packets -.->|"updates state"| node_player
node_packets -->|"tracks world packets"| node_world
node_player -->|"tracks inventory"| node_inventory
node_player -.->|"owns checks"| node_checkmanager
node_checkmanager -.->|"dispatches checks"| node_checks
node_checks -.->|"checks movement"| node_prediction
node_prediction -->|"reads state"| node_player
node_prediction -.->|"builds candidates"| node_vectors
node_prediction -.->|"tests movement"| node_collision
node_collision -->|"reads replica"| node_world
node_collision -.->|"uses geometry"| node_box
node_prediction -->|"applies modifiers"| node_stuck
node_rideable -->|"extends engine"| node_prediction
node_rideable -->|"computes bounds"| node_bounds
node_vectors -->|"stores motion"| node_math
node_operator -->|"runs commands"| node_commands
node_commands -.->|"manages alerts"| node_alerts
node_checks -.->|"reports violations"| node_alerts

click node_bukkit "https://github.com/grimanticheat/grim/blob/2.0/bukkit/src/main/java/ac/grim/grimac/platform/bukkit/BukkitPlatformPlugin.java"
click node_fabric "https://github.com/grimanticheat/grim/blob/2.0/fabric/shared/src/main/java/ac/grim/grimac/platform/fabric/FabricPlatformServices.java"
click node_api "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/platform/api/player/PlatformPlayer.java"
click node_lifecycle "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/GrimAPI.java"
click node_player "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/player/GrimPlayer.java"
click node_packets "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/events/packets/CheckManagerListener.java"
click node_world "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/events/packets/worldreader/BasePacketWorldReader.java"
click node_inventory "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/lists/CorrectingPlayerInventoryStorage.java"
click node_checks "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/checks/Check.java"
click node_checkmanager "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/manager/CheckManager.java"
click node_prediction "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/predictionengine/predictions/PredictionEngine.java"
click node_rideable "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/predictionengine/predictions/rideable/PredictionEngineBoat.java"
click node_collision "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/nmsutil/Collisions.java"
click node_bounds "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/nmsutil/GetBoundingBox.java"
click node_stuck "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/nmsutil/StuckSpeed.java"
click node_vectors "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/data/VectorData.java"
click node_math "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/math/Vector3dm.java"
click node_entities "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/data/packetentity/PacketEntity.java"
click node_blockproperties "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/nmsutil/BlockProperties.java"
click node_materials "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/nmsutil/Materials.java"
click node_box "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/collisions/datatypes/SimpleCollisionBox.java"
click node_grimmath "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/math/GrimMath.java"
click node_permission "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/platform/api/permissions/PermissionDefaultValue.java"
click node_logging "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/anticheat/LogUtil.java"
click node_commands "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/command/CloudCommandService.java"
click node_alerts "https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/manager/AlertManagerImpl.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bukkit,node_fabric,node_api,node_permission toneBlue
class node_lifecycle,node_player,node_packets,node_world,node_inventory toneAmber
class node_checks,node_checkmanager,node_server,node_operator toneMint
class node_prediction,node_rideable,node_collision,node_bounds,node_stuck,node_vectors,node_math,node_entities,node_blockproperties,node_materials,node_box,node_grimmath toneRose
class node_logging,node_commands,node_alerts toneIndigo
```

## Components

### Server integration

- [Bukkit adapter](https://github.com/grimanticheat/grim/blob/2.0/bukkit/src/main/java/ac/grim/grimac/platform/bukkit/BukkitPlatformPlugin.java): `bukkit/src/main/java/ac/grim/grimac/platform/bukkit/BukkitPlatformPlugin.java`
- [Fabric adapters](https://github.com/grimanticheat/grim/blob/2.0/fabric/shared/src/main/java/ac/grim/grimac/platform/fabric/FabricPlatformServices.java): `fabric/shared/src/main/java/ac/grim/grimac/platform/fabric/FabricPlatformServices.java`
- [Platform API](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/platform/api/player/PlatformPlayer.java): `common/src/main/java/ac/grim/grimac/platform/api/player/PlatformPlayer.java`
- [Permission defaults](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/platform/api/permissions/PermissionDefaultValue.java): `common/src/main/java/ac/grim/grimac/platform/api/permissions/PermissionDefaultValue.java`

### Player runtime

- [Core lifecycle](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/GrimAPI.java): `common/src/main/java/ac/grim/grimac/GrimAPI.java`
- [Player state](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/player/GrimPlayer.java): `common/src/main/java/ac/grim/grimac/player/GrimPlayer.java`
- [Packet processing](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/events/packets/CheckManagerListener.java): `common/src/main/java/ac/grim/grimac/events/packets/CheckManagerListener.java`
- [World replica](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/events/packets/worldreader/BasePacketWorldReader.java): `common/src/main/java/ac/grim/grimac/events/packets/worldreader/BasePacketWorldReader.java`
- [Inventory tracking](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/lists/CorrectingPlayerInventoryStorage.java): `common/src/main/java/ac/grim/grimac/utils/lists/CorrectingPlayerInventoryStorage.java`

### Detection and response

- [Anticheat checks](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/checks/Check.java): `common/src/main/java/ac/grim/grimac/checks/Check.java`
- [Check manager](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/manager/CheckManager.java): `common/src/main/java/ac/grim/grimac/manager/CheckManager.java`

### Simulation internals

- [Movement prediction](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/predictionengine/predictions/PredictionEngine.java): `common/src/main/java/ac/grim/grimac/predictionengine/predictions/PredictionEngine.java`
- [Vehicle prediction](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/predictionengine/predictions/rideable/PredictionEngineBoat.java): `common/src/main/java/ac/grim/grimac/predictionengine/predictions/rideable/PredictionEngineBoat.java`
- [Collision geometry](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/nmsutil/Collisions.java): `common/src/main/java/ac/grim/grimac/utils/nmsutil/Collisions.java`
- [Player bounds](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/nmsutil/GetBoundingBox.java): `common/src/main/java/ac/grim/grimac/utils/nmsutil/GetBoundingBox.java`
- [Movement modifiers](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/nmsutil/StuckSpeed.java): `common/src/main/java/ac/grim/grimac/utils/nmsutil/StuckSpeed.java`
- [Motion vectors](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/data/VectorData.java): `common/src/main/java/ac/grim/grimac/utils/data/VectorData.java`
- [Vector math](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/math/Vector3dm.java): `common/src/main/java/ac/grim/grimac/utils/math/Vector3dm.java`
- [Entity state](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/data/packetentity/PacketEntity.java): `common/src/main/java/ac/grim/grimac/utils/data/packetentity/PacketEntity.java`
- [Block properties](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/nmsutil/BlockProperties.java): `common/src/main/java/ac/grim/grimac/utils/nmsutil/BlockProperties.java`
- [Materials](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/nmsutil/Materials.java): `common/src/main/java/ac/grim/grimac/utils/nmsutil/Materials.java`
- [Collision boxes](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/collisions/datatypes/SimpleCollisionBox.java): `common/src/main/java/ac/grim/grimac/utils/collisions/datatypes/SimpleCollisionBox.java`
- [Numeric helpers](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/math/GrimMath.java): `common/src/main/java/ac/grim/grimac/utils/math/GrimMath.java`

### Operations

- [Logging](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/utils/anticheat/LogUtil.java): `common/src/main/java/ac/grim/grimac/utils/anticheat/LogUtil.java`
- [Admin commands](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/command/CloudCommandService.java): `common/src/main/java/ac/grim/grimac/command/CloudCommandService.java`
- [Alerts and punishment](https://github.com/grimanticheat/grim/blob/2.0/common/src/main/java/ac/grim/grimac/manager/AlertManagerImpl.java): `common/src/main/java/ac/grim/grimac/manager/AlertManagerImpl.java`

### Other components

- **Minecraft server**
- **Server operator**

## Connections

- Minecraft server → Bukkit adapter: hosts plugin
- Minecraft server → Fabric adapters: hosts mod
- Bukkit adapter → Core lifecycle: initializes core
- Fabric adapters → Core lifecycle: initializes core
- Core lifecycle → Player state: manages players (evidence: `common/src/main/java/ac/grim/grimac/player/GrimPlayer.java`)
- Packet processing → Player state: updates state (evidence: `common/src/main/java/ac/grim/grimac/events/packets/CheckManagerListener.java`)
- Packet processing → World replica: tracks world packets
- Player state → Inventory tracking: tracks inventory (evidence: `common/src/main/java/ac/grim/grimac/utils/lists/CorrectingPlayerInventoryStorage.java`)
- Player state → Check manager: owns checks (evidence: `common/src/main/java/ac/grim/grimac/manager/CheckManager.java`)
- Check manager → Anticheat checks: dispatches checks (evidence: `common/src/main/java/ac/grim/grimac/manager/CheckManager.java`)
- Anticheat checks → Movement prediction: checks movement
- Movement prediction → Player state: reads state (evidence: `common/src/main/java/ac/grim/grimac/predictionengine/predictions/PredictionEngine.java`)
- Movement prediction → Motion vectors: builds candidates (evidence: `common/src/main/java/ac/grim/grimac/predictionengine/predictions/PredictionEngine.java`)
- Movement prediction → Collision geometry: tests movement (evidence: `common/src/main/java/ac/grim/grimac/predictionengine/predictions/PredictionEngine.java`)
- Collision geometry → World replica: reads replica (evidence: `common/src/main/java/ac/grim/grimac/utils/nmsutil/Collisions.java`)
- Collision geometry → Collision boxes: uses geometry (evidence: `common/src/main/java/ac/grim/grimac/utils/nmsutil/Collisions.java`)
- Movement prediction → Movement modifiers: applies modifiers (evidence: `common/src/main/java/ac/grim/grimac/predictionengine/predictions/PredictionEngine.java`)
- Vehicle prediction → Movement prediction: extends engine (evidence: `common/src/main/java/ac/grim/grimac/predictionengine/predictions/rideable/PredictionEngineBoat.java`)
- Vehicle prediction → Player bounds: computes bounds (evidence: `common/src/main/java/ac/grim/grimac/predictionengine/predictions/rideable/PredictionEngineBoat.java`)
- Motion vectors → Vector math: stores motion (evidence: `common/src/main/java/ac/grim/grimac/utils/data/VectorData.java`)
- Server operator → Admin commands: runs commands (evidence: `common/src/main/java/ac/grim/grimac/command/CloudCommandService.java`)
- Admin commands → Alerts and punishment: manages alerts
- Anticheat checks → Alerts and punishment: reports violations