# ryanhcode/sable architecture

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

- Interactive diagram: https://gitdiagram.com/ryanhcode/sable
- Repository: https://github.com/ryanhcode/sable

## Overview

Sable is a Minecraft library mod for interactive moving block structures (“sub-levels”) that contain ordinary chunks, entities, and block entities while moving independently in position and orientation. Its product workflow spans assembly and sub-level lifecycle, optional physics simulation, persistence, and integration of game interactions and rendering; commands expose management operations. The tree and README establish these capabilities, while sampled code confirms storage access and several interaction hooks. Wiring among unsampled runtime subsystems is therefore shown only where documented or directly evidenced.

Main entry points: [`common/src/main/java/dev/ryanhcode/sable/api/SubLevelHelper.java`](https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/api/SubLevelHelper.java) (Sub-level API), [`common/src/main/java/dev/ryanhcode/sable/api/sublevel/ServerSubLevelContainer.java`](https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/api/sublevel/ServerSubLevelContainer.java) (Server container), [`common/src/main/java/dev/ryanhcode/sable/command/SableStorageCommands.java`](https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/command/SableStorageCommands.java) (Storage commands), [`common/src/main/java/dev/ryanhcode/sable/api/physics/PhysicsPipeline.java`](https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/api/physics/PhysicsPipeline.java) (Physics pipeline API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lifecycle["Sub-level lifecycle"]
  node_sable["Sable entry<br/>[Sable.java]"]
  node_assembly["Assembly helpers"]
  node_containers["Sub-level containers"]
  node_servercontainer["Server container"]
  node_clientcontainer["Client container"]
  node_sublevelapi["Sub-level API"]
end

subgraph group_physics["Physics simulation"]
  node_physicsapi["Physics pipeline API"]
  node_rapier["Rapier pipeline"]
  node_staticphysics["Static pipeline"]
end

subgraph group_persistence["Persistence"]
  node_storage["Storage service"]
  node_regionfile[("Region storage file")]
end

subgraph group_integration["Game integration"]
  node_mixins["Game mixins"]
  node_particlehooks["Particle integration"]
  node_soundhooks["Sound integration"]
  node_flywheel["Flywheel rendering"]
  node_flywheellight["Flywheel light storage"]
end

subgraph group_access["User and developer access"]
  node_commands["Management commands<br/>[SableCommand.java]"]
  node_storagecommands["Storage commands"]
end

node_operator(("Player / mod"))

node_operator -->|"runs commands"| node_commands
node_sable -->|"exposes helpers"| node_assembly
node_assembly -->|"assembles sub-levels"| node_servercontainer
node_servercontainer -->|"implements lifecycle"| node_containers
node_clientcontainer -->|"implements lifecycle"| node_containers
node_sublevelapi -->|"locates sub-levels"| node_servercontainer
node_commands -->|"dispatches storage"| node_storagecommands
node_storagecommands -->|"gets container"| node_servercontainer
node_storagecommands -->|"reads storage"| node_storage
node_storage -->|"uses file storage"| node_regionfile
node_physicsapi -->|"implemented by"| node_rapier
node_physicsapi -->|"implemented by"| node_staticphysics
node_particlehooks -->|"finds containing level"| node_sublevelapi
node_soundhooks -->|"finds containing level"| node_sublevelapi
node_flywheel -->|"finds containing level"| node_sublevelapi
node_flywheellight -->|"finds containing level"| node_sublevelapi
node_mixins -->|"includes hook"| node_particlehooks
node_mixins -->|"includes hook"| node_soundhooks

click node_sable "https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/Sable.java"
click node_assembly "https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/api/SubLevelAssemblyHelper.java"
click node_containers "https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/api/sublevel/SubLevelContainer.java"
click node_servercontainer "https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/api/sublevel/ServerSubLevelContainer.java"
click node_clientcontainer "https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/api/sublevel/ClientSubLevelContainer.java"
click node_sublevelapi "https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/api/SubLevelHelper.java"
click node_physicsapi "https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/api/physics/PhysicsPipeline.java"
click node_rapier "https://github.com/ryanhcode/sable/blob/main/sable_rapier/src/main/java/dev/ryanhcode/sable/physics/impl/rapier/RapierPhysicsPipeline.java"
click node_staticphysics "https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/physics/impl/none/StaticPhysicsPipeline.java"
click node_storage "https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/sublevel/storage/serialization/SubLevelStorage.java"
click node_regionfile "https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/sublevel/storage/region/SubLevelStorageFile.java"
click node_commands "https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/command/SableCommand.java"
click node_storagecommands "https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/command/SableStorageCommands.java"
click node_mixins "https://github.com/ryanhcode/sable/tree/main/common/src/main/java/dev/ryanhcode/sable/mixin"
click node_particlehooks "https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/mixin/particle/ParticleEngineMixin.java"
click node_soundhooks "https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/mixin/sublevel_sounds/SoundEngineMixin.java"
click node_flywheel "https://github.com/ryanhcode/sable/blob/main/neoforge/src/main/java/dev/ryanhcode/sable/neoforge/mixin/compatibility/flywheel/BlockEntityStorageMixin.java"
click node_flywheellight "https://github.com/ryanhcode/sable/blob/main/neoforge/src/main/java/dev/ryanhcode/sable/neoforge/compatibility/flywheel/SableFlywheelLightStorage.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_sable,node_assembly,node_containers,node_servercontainer,node_clientcontainer,node_sublevelapi toneBlue
class node_physicsapi,node_rapier,node_staticphysics toneAmber
class node_storage,node_regionfile toneMint
class node_mixins,node_particlehooks,node_soundhooks,node_flywheel,node_flywheellight toneRose
class node_commands,node_storagecommands,node_operator toneIndigo
```

## Components

### Sub-level lifecycle

- [Sable entry](https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/Sable.java): `common/src/main/java/dev/ryanhcode/sable/Sable.java`
- [Assembly helpers](https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/api/SubLevelAssemblyHelper.java): `common/src/main/java/dev/ryanhcode/sable/api/SubLevelAssemblyHelper.java`
- [Sub-level containers](https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/api/sublevel/SubLevelContainer.java): `common/src/main/java/dev/ryanhcode/sable/api/sublevel/SubLevelContainer.java`
- [Server container](https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/api/sublevel/ServerSubLevelContainer.java): `common/src/main/java/dev/ryanhcode/sable/api/sublevel/ServerSubLevelContainer.java`
- [Client container](https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/api/sublevel/ClientSubLevelContainer.java): `common/src/main/java/dev/ryanhcode/sable/api/sublevel/ClientSubLevelContainer.java`
- [Sub-level API](https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/api/SubLevelHelper.java): `common/src/main/java/dev/ryanhcode/sable/api/SubLevelHelper.java`

### Physics simulation

- [Physics pipeline API](https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/api/physics/PhysicsPipeline.java): `common/src/main/java/dev/ryanhcode/sable/api/physics/PhysicsPipeline.java`
- [Rapier pipeline](https://github.com/ryanhcode/sable/blob/main/sable_rapier/src/main/java/dev/ryanhcode/sable/physics/impl/rapier/RapierPhysicsPipeline.java): `sable_rapier/src/main/java/dev/ryanhcode/sable/physics/impl/rapier/RapierPhysicsPipeline.java`
- [Static pipeline](https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/physics/impl/none/StaticPhysicsPipeline.java): `common/src/main/java/dev/ryanhcode/sable/physics/impl/none/StaticPhysicsPipeline.java`

### Persistence

- [Storage service](https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/sublevel/storage/serialization/SubLevelStorage.java): `common/src/main/java/dev/ryanhcode/sable/sublevel/storage/serialization/SubLevelStorage.java`
- [Region storage file](https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/sublevel/storage/region/SubLevelStorageFile.java): `common/src/main/java/dev/ryanhcode/sable/sublevel/storage/region/SubLevelStorageFile.java`

### Game integration

- [Game mixins](https://github.com/ryanhcode/sable/tree/main/common/src/main/java/dev/ryanhcode/sable/mixin): `common/src/main/java/dev/ryanhcode/sable/mixin`
- [Particle integration](https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/mixin/particle/ParticleEngineMixin.java): `common/src/main/java/dev/ryanhcode/sable/mixin/particle/ParticleEngineMixin.java`
- [Sound integration](https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/mixin/sublevel_sounds/SoundEngineMixin.java): `common/src/main/java/dev/ryanhcode/sable/mixin/sublevel_sounds/SoundEngineMixin.java`
- [Flywheel rendering](https://github.com/ryanhcode/sable/blob/main/neoforge/src/main/java/dev/ryanhcode/sable/neoforge/mixin/compatibility/flywheel/BlockEntityStorageMixin.java): `neoforge/src/main/java/dev/ryanhcode/sable/neoforge/mixin/compatibility/flywheel/BlockEntityStorageMixin.java`
- [Flywheel light storage](https://github.com/ryanhcode/sable/blob/main/neoforge/src/main/java/dev/ryanhcode/sable/neoforge/compatibility/flywheel/SableFlywheelLightStorage.java): `neoforge/src/main/java/dev/ryanhcode/sable/neoforge/compatibility/flywheel/SableFlywheelLightStorage.java`

### User and developer access

- [Management commands](https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/command/SableCommand.java): `common/src/main/java/dev/ryanhcode/sable/command/SableCommand.java`
- [Storage commands](https://github.com/ryanhcode/sable/blob/main/common/src/main/java/dev/ryanhcode/sable/command/SableStorageCommands.java): `common/src/main/java/dev/ryanhcode/sable/command/SableStorageCommands.java`

### Other components

- **Player / mod**

## Connections

- Player / mod → Management commands: runs commands
- Sable entry → Assembly helpers: exposes helpers
- Assembly helpers → Server container: assembles sub-levels
- Server container → Sub-level containers: implements lifecycle
- Client container → Sub-level containers: implements lifecycle
- Sub-level API → Server container: locates sub-levels
- Management commands → Storage commands: dispatches storage
- Storage commands → Server container: gets container
- Storage commands → Storage service: reads storage
- Storage service → Region storage file: uses file storage
- Physics pipeline API → Rapier pipeline: implemented by
- Physics pipeline API → Static pipeline: implemented by
- Particle integration → Sub-level API: finds containing level
- Sound integration → Sub-level API: finds containing level
- Flywheel rendering → Sub-level API: finds containing level
- Flywheel light storage → Sub-level API: finds containing level
- Game mixins → Particle integration: includes hook
- Game mixins → Sound integration: includes hook