# polari-stars-mc/relativity-craft architecture

> Architecture diagram of the GitHub repository polari-stars-mc/relativity-craft, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/polari-stars-mc/relativity-craft
- Repository: https://github.com/polari-stars-mc/relativity-craft

## Overview

RelativityCraft is a Minecraft mod that turns selected block volumes into movable, physics-driven entities while retaining block interactions and world behavior. The principal path runs from client interaction and server handling through physicalized-volume state and world physics, backed by a Java-to-native Rapier layer. Separate branches represent enclaves, celestial bodies, redstone, rendering, and fluids. The README is empty; unsampled subsystem links are included only where the source index supports them, so some event-driven wiring is not shown.

Main entry points: [`src/main/java/org/polaris2023/relativity/world/PhysicsWorldManager.java`](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/world/PhysicsWorldManager.java) (Physics world manager), [`src/main/java/org/polaris2023/relativity/interaction/PhysicalizedInteractionHandler.java`](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/interaction/PhysicalizedInteractionHandler.java) (Interaction handler), [`src/main/java/org/polaris2023/relativity/entity/PhysicalizedVolumeEntity.java`](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/entity/PhysicalizedVolumeEntity.java) (Volume entity), [`src/main/java/org/polaris2023/relativity/physicalization/PhysicalizedVolumeSnapshot.java`](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/physicalization/PhysicalizedVolumeSnapshot.java) (Volume snapshot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mod["Mod and interaction"]
  node_client_interactions["Client interactions"]
  node_interaction_network["Interaction network"]
  node_interaction_handler["Interaction handler"]
  node_raycaster["Physicalized raycaster"]
  node_volume_mapping["Volume mapping"]
end

subgraph group_volume["Physicalized volumes"]
  node_volume_manager["Volume manager"]
  node_volume_entity["Volume entity"]
  node_volume_snapshot["Volume snapshot"]
  node_block_snapshot["Block snapshot"]
end

subgraph group_simulation["Physics simulation"]
  node_physics_manager["Physics world manager"]
  node_physics_commands["Physics commands"]
end

subgraph group_world_features["World features"]
  node_redstone["Redstone mapping"]
  node_fluid_manager["Fluid domains"]
  node_water_colliders["Water colliders"]
  node_celestial["Celestial bodies<br/>[CelestialBody.java]"]
  node_enclave["Enclave entity<br/>[EnclaveEntity.java]"]
  node_rendering["Volume rendering"]
  node_enclave_storage["Enclave storage<br/>[Enclave.java]"]
end

subgraph group_native["Native physics"]
  node_native_world["Rapier native world"]
  node_native_api["Native API"]
  node_ffi["Rust physics FFI<br/>[ffi.rs]"]
end

node_player(("Minecraft player"))

node_player -.->|"initiates"| node_client_interactions
node_client_interactions -->|"sends actions"| node_interaction_network
node_interaction_network -->|"dispatches actions"| node_interaction_handler
node_interaction_handler -->|"raycasts targets"| node_raycaster
node_interaction_handler -->|"updates blocks"| node_volume_entity
node_interaction_handler -->|"reads and updates"| node_volume_snapshot
node_volume_entity -->|"holds state"| node_volume_snapshot
node_volume_snapshot -->|"indexes cells"| node_block_snapshot
node_raycaster -.->|"maps hits"| node_volume_mapping
node_physics_manager -->|"manages volumes"| node_volume_manager
node_physics_manager -->|"registers bodies"| node_volume_entity
node_physics_manager -.->|"queues work"| node_physics_commands
node_physics_manager -->|"runs simulation"| node_native_world
node_physics_manager -->|"registers bodies"| node_celestial
node_physics_manager -->|"registers bodies"| node_enclave
node_native_world -.->|"calls native API"| node_native_api
node_native_api -.->|"bridges calls"| node_ffi
node_fluid_manager -->|"applies fluid forces"| node_native_world
node_water_colliders -->|"samples water"| node_fluid_manager
node_water_colliders -->|"queues updates"| node_physics_commands
node_redstone -->|"queries bodies"| node_physics_manager
node_enclave -.->|"stores blocks"| node_enclave_storage
node_volume_entity -.->|"renders volume"| node_rendering

click node_client_interactions "https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/client/PhysicalizedClientInteractions.java"
click node_interaction_network "https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/network/PhysicalizedInteractionNetwork.java"
click node_interaction_handler "https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/interaction/PhysicalizedInteractionHandler.java"
click node_volume_manager "https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/physicalization/PhysicalizedVolumeManager.java"
click node_volume_entity "https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/entity/PhysicalizedVolumeEntity.java"
click node_volume_snapshot "https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/physicalization/PhysicalizedVolumeSnapshot.java"
click node_block_snapshot "https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/physicalization/PhysicalizedBlockSnapshot.java"
click node_raycaster "https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/interaction/PhysicalizedRaycaster.java"
click node_volume_mapping "https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/interaction/PhysicalizedVolumeMapping.java"
click node_redstone "https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/interaction/PhysicalizedRedstoneMapping.java"
click node_physics_manager "https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/world/PhysicsWorldManager.java"
click node_physics_commands "https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/world/PhysicsCommand.java"
click node_fluid_manager "https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/fluid/FluidDomainManager.java"
click node_water_colliders "https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/world/WaterSurfaceColliderManager.java"
click node_celestial "https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/celestial/CelestialBody.java"
click node_enclave "https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/entity/EnclaveEntity.java"
click node_native_world "https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/nativeaccess/RapierNativeWorld.java"
click node_native_api "https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/nativeaccess/RelativityCraftRapier.java"
click node_ffi "https://github.com/polari-stars-mc/relativity-craft/blob/main/native/src/ffi.rs"
click node_rendering "https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/render/PhysicalizedVolumeRenderer.java"
click node_enclave_storage "https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/enclave/Enclave.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_client_interactions,node_interaction_network,node_interaction_handler,node_raycaster,node_volume_mapping toneBlue
class node_volume_manager,node_volume_entity,node_volume_snapshot,node_block_snapshot toneAmber
class node_physics_manager,node_physics_commands toneMint
class node_redstone,node_fluid_manager,node_water_colliders,node_celestial,node_enclave,node_rendering,node_enclave_storage toneRose
class node_native_world,node_native_api,node_ffi,node_player toneIndigo
```

## Components

### Mod and interaction

- [Client interactions](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/client/PhysicalizedClientInteractions.java): `src/main/java/org/polaris2023/relativity/client/PhysicalizedClientInteractions.java`
- [Interaction network](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/network/PhysicalizedInteractionNetwork.java): `src/main/java/org/polaris2023/relativity/network/PhysicalizedInteractionNetwork.java`
- [Interaction handler](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/interaction/PhysicalizedInteractionHandler.java): `src/main/java/org/polaris2023/relativity/interaction/PhysicalizedInteractionHandler.java`
- [Physicalized raycaster](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/interaction/PhysicalizedRaycaster.java): `src/main/java/org/polaris2023/relativity/interaction/PhysicalizedRaycaster.java`
- [Volume mapping](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/interaction/PhysicalizedVolumeMapping.java): `src/main/java/org/polaris2023/relativity/interaction/PhysicalizedVolumeMapping.java`

### Physicalized volumes

- [Volume manager](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/physicalization/PhysicalizedVolumeManager.java): `src/main/java/org/polaris2023/relativity/physicalization/PhysicalizedVolumeManager.java`
- [Volume entity](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/entity/PhysicalizedVolumeEntity.java): `src/main/java/org/polaris2023/relativity/entity/PhysicalizedVolumeEntity.java`
- [Volume snapshot](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/physicalization/PhysicalizedVolumeSnapshot.java): `src/main/java/org/polaris2023/relativity/physicalization/PhysicalizedVolumeSnapshot.java`
- [Block snapshot](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/physicalization/PhysicalizedBlockSnapshot.java): `src/main/java/org/polaris2023/relativity/physicalization/PhysicalizedBlockSnapshot.java`

### Physics simulation

- [Physics world manager](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/world/PhysicsWorldManager.java): `src/main/java/org/polaris2023/relativity/world/PhysicsWorldManager.java`
- [Physics commands](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/world/PhysicsCommand.java): `src/main/java/org/polaris2023/relativity/world/PhysicsCommand.java`

### World features

- [Redstone mapping](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/interaction/PhysicalizedRedstoneMapping.java): `src/main/java/org/polaris2023/relativity/interaction/PhysicalizedRedstoneMapping.java`
- [Fluid domains](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/fluid/FluidDomainManager.java): `src/main/java/org/polaris2023/relativity/fluid/FluidDomainManager.java`
- [Water colliders](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/world/WaterSurfaceColliderManager.java): `src/main/java/org/polaris2023/relativity/world/WaterSurfaceColliderManager.java`
- [Celestial bodies](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/celestial/CelestialBody.java): `src/main/java/org/polaris2023/relativity/celestial/CelestialBody.java`
- [Enclave entity](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/entity/EnclaveEntity.java): `src/main/java/org/polaris2023/relativity/entity/EnclaveEntity.java`
- [Volume rendering](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/render/PhysicalizedVolumeRenderer.java): `src/main/java/org/polaris2023/relativity/render/PhysicalizedVolumeRenderer.java`
- [Enclave storage](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/enclave/Enclave.java): `src/main/java/org/polaris2023/relativity/enclave/Enclave.java`

### Native physics

- [Rapier native world](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/nativeaccess/RapierNativeWorld.java): `src/main/java/org/polaris2023/relativity/nativeaccess/RapierNativeWorld.java`
- [Native API](https://github.com/polari-stars-mc/relativity-craft/blob/main/src/main/java/org/polaris2023/relativity/nativeaccess/RelativityCraftRapier.java): `src/main/java/org/polaris2023/relativity/nativeaccess/RelativityCraftRapier.java`
- [Rust physics FFI](https://github.com/polari-stars-mc/relativity-craft/blob/main/native/src/ffi.rs): `native/src/ffi.rs`

### Other components

- **Minecraft player**

## Connections

- Minecraft player → Client interactions: initiates
- Client interactions → Interaction network: sends actions (evidence: `src/main/java/org/polaris2023/relativity/client/PhysicalizedClientInteractions.java`)
- Interaction network → Interaction handler: dispatches actions (evidence: `src/main/java/org/polaris2023/relativity/network/PhysicalizedInteractionNetwork.java`)
- Interaction handler → Physicalized raycaster: raycasts targets (evidence: `src/main/java/org/polaris2023/relativity/interaction/PhysicalizedInteractionHandler.java`)
- Interaction handler → Volume entity: updates blocks (evidence: `src/main/java/org/polaris2023/relativity/interaction/PhysicalizedInteractionHandler.java`)
- Interaction handler → Volume snapshot: reads and updates (evidence: `src/main/java/org/polaris2023/relativity/interaction/PhysicalizedInteractionHandler.java`)
- Volume entity → Volume snapshot: holds state (evidence: `src/main/java/org/polaris2023/relativity/entity/PhysicalizedVolumeEntity.java`)
- Volume snapshot → Block snapshot: indexes cells (evidence: `src/main/java/org/polaris2023/relativity/physicalization/PhysicalizedVolumeSnapshot.java`)
- Physicalized raycaster → Volume mapping: maps hits
- Physics world manager → Volume manager: manages volumes (evidence: `src/main/java/org/polaris2023/relativity/world/PhysicsWorldManager.java`)
- Physics world manager → Volume entity: registers bodies (evidence: `src/main/java/org/polaris2023/relativity/world/PhysicsWorldManager.java`)
- Physics world manager → Physics commands: queues work (evidence: `src/main/java/org/polaris2023/relativity/world/PhysicsWorldManager.java`)
- Physics world manager → Rapier native world: runs simulation (evidence: `src/main/java/org/polaris2023/relativity/world/PhysicsWorldManager.java`)
- Physics world manager → Celestial bodies: registers bodies (evidence: `src/main/java/org/polaris2023/relativity/world/PhysicsWorldManager.java`)
- Physics world manager → Enclave entity: registers bodies (evidence: `src/main/java/org/polaris2023/relativity/world/PhysicsWorldManager.java`)
- Rapier native world → Native API: calls native API (evidence: `src/main/java/org/polaris2023/relativity/nativeaccess/RapierNativeWorld.java`)
- Native API → Rust physics FFI: bridges calls
- Fluid domains → Rapier native world: applies fluid forces (evidence: `src/main/java/org/polaris2023/relativity/fluid/FluidDomainManager.java`)
- Water colliders → Fluid domains: samples water (evidence: `src/main/java/org/polaris2023/relativity/world/WaterSurfaceColliderManager.java`)
- Water colliders → Physics commands: queues updates (evidence: `src/main/java/org/polaris2023/relativity/world/WaterSurfaceColliderManager.java`)
- Redstone mapping → Physics world manager: queries bodies (evidence: `src/main/java/org/polaris2023/relativity/world/PhysicsWorldManager.java`)
- Enclave entity → Enclave storage: stores blocks
- Volume entity → Volume rendering: renders volume
