# caffeinemc/sodium architecture

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

- Interactive diagram: https://gitdiagram.com/caffeinemc/sodium
- Repository: https://github.com/caffeinemc/sodium

## Overview

Sodium is a Minecraft client rendering engine and optimization mod. The principal workflow is: Minecraft launches Sodium; compatibility checks validate the graphics environment; world changes become render-section updates; visible sections are culled and asynchronously rebuilt; lighting and model data are uploaded through GPU arenas; the renderer submits batches to the graphics device for faster frames. The repository also exposes configuration APIs and GUI controls, resource-pack checks, block-entity rendering, and platform-specific compatibility workarounds. Some orchestration is inferred from sampled files and directory structure.

Main entry points: [`common/src/main/java/net/caffeinemc/mods/sodium/client/render/chunk/RenderSectionManager.java`](https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/render/chunk/RenderSectionManager.java) (Section Manager), [`common/src/main/java/net/caffeinemc/mods/sodium/client/SodiumClientMod.java`](https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/SodiumClientMod.java) (Sodium Entry), [`common/src/main/java/net/caffeinemc/mods/sodium/client/gui/VideoSettingsScreen.java`](https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/gui/VideoSettingsScreen.java) (Video Settings UI), [`common/src/main/java/net/caffeinemc/mods/sodium/client/render/chunk/ChunkRenderer.java`](https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/render/chunk/ChunkRenderer.java) (Chunk Renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry_compat["Entry &amp; Compatibility"]
  node_sodium_entry["Sodium Entry"]
  node_compat_checks["Compatibility Checks"]
  node_driver_workarounds["Driver Workarounds"]
  node_resource_checks["Resource Checks"]
end

subgraph group_config_ui["Configuration UI"]
  node_config_api["Config API"]
  node_config_manager[("Config Manager<br/>[ConfigManager.java]")]
  node_config_gui["Video Settings UI"]
  node_config_search["Option Search"]
end

subgraph group_world_geometry["World Geometry"]
  node_world_renderer["World Renderer"]
  node_section_manager["Section Manager"]
  node_section_storage[("Section Storage")]
  node_chunk_renderer["Chunk Renderer<br/>[ChunkRenderer.java]"]
  node_lighting["Lighting Pipelines"]
  node_block_entity_api["Block Entity API"]
end

subgraph group_gpu_rendering["GPU Rendering"]
  node_render_data[("Section Mesh Data")]
  node_gpu_arenas[("GPU Buffer Arenas")]
  node_draw_backend["Draw Backend<br/>[DrawBackend.java]"]
  node_draw_batches["Draw Batches"]
end

node_minecraft_client(("Minecraft Client"))
node_graphics_device{{"Graphics Device"}}

node_minecraft_client -->|"launches"| node_sodium_entry
node_sodium_entry -->|"runs checks"| node_compat_checks
node_compat_checks -->|"selects workarounds"| node_driver_workarounds
node_sodium_entry -->|"checks resources"| node_resource_checks
node_minecraft_client -->|"opens settings"| node_config_gui
node_config_gui -->|"saves options"| node_config_manager
node_config_api -->|"binds options"| node_config_manager
node_config_gui -->|"searches options"| node_config_search
node_minecraft_client -->|"renders world"| node_world_renderer
node_world_renderer -->|"updates sections"| node_section_manager
node_section_manager -->|"queues sections"| node_section_storage
node_section_manager -->|"submits builds"| node_chunk_renderer
node_chunk_renderer -->|"calculates lighting"| node_lighting
node_chunk_renderer -->|"stores meshes"| node_render_data
node_render_data -->|"allocates buffers"| node_gpu_arenas
node_section_manager -->|"renders visible sections"| node_draw_backend
node_draw_backend -->|"dispatches batches"| node_draw_batches
node_draw_batches -->|"submits draws"| node_graphics_device
node_block_entity_api -.->|"extends rendering"| node_world_renderer

click node_sodium_entry "https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/SodiumClientMod.java"
click node_compat_checks "https://github.com/caffeinemc/sodium/tree/dev/common/src/boot/java/net/caffeinemc/mods/sodium/client/compatibility/checks"
click node_driver_workarounds "https://github.com/caffeinemc/sodium/tree/dev/common/src/boot/java/net/caffeinemc/mods/sodium/client/compatibility/workarounds"
click node_resource_checks "https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/checks/ResourcePackScanner.java"
click node_config_api "https://github.com/caffeinemc/sodium/tree/dev/common/src/api/java/net/caffeinemc/mods/sodium/api/config"
click node_config_manager "https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/config/ConfigManager.java"
click node_config_gui "https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/gui/VideoSettingsScreen.java"
click node_config_search "https://github.com/caffeinemc/sodium/tree/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/config/search"
click node_world_renderer "https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/render/SodiumWorldRenderer.java"
click node_section_manager "https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/render/chunk/RenderSectionManager.java"
click node_section_storage "https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/render/chunk/storage/QueuedSectionStorage.java"
click node_chunk_renderer "https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/render/chunk/ChunkRenderer.java"
click node_lighting "https://github.com/caffeinemc/sodium/tree/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/model/light"
click node_render_data "https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/render/chunk/data/SectionRenderDataStorage.java"
click node_gpu_arenas "https://github.com/caffeinemc/sodium/tree/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/gpu/arena"
click node_draw_backend "https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/gpu/device/backend/DrawBackend.java"
click node_draw_batches "https://github.com/caffeinemc/sodium/tree/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/gpu/device/batch"
click node_block_entity_api "https://github.com/caffeinemc/sodium/tree/dev/common/src/api/java/net/caffeinemc/mods/sodium/api/blockentity"

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_sodium_entry,node_compat_checks,node_driver_workarounds,node_resource_checks,node_minecraft_client toneBlue
class node_config_api,node_config_manager,node_config_gui,node_config_search toneAmber
class node_world_renderer,node_section_manager,node_section_storage,node_chunk_renderer,node_lighting,node_block_entity_api toneMint
class node_render_data,node_gpu_arenas,node_draw_backend,node_draw_batches toneRose
class node_graphics_device toneIndigo
```

## Components

### Entry & Compatibility

- [Sodium Entry](https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/SodiumClientMod.java): `common/src/main/java/net/caffeinemc/mods/sodium/client/SodiumClientMod.java`
- [Compatibility Checks](https://github.com/caffeinemc/sodium/tree/dev/common/src/boot/java/net/caffeinemc/mods/sodium/client/compatibility/checks): `common/src/boot/java/net/caffeinemc/mods/sodium/client/compatibility/checks`
- [Driver Workarounds](https://github.com/caffeinemc/sodium/tree/dev/common/src/boot/java/net/caffeinemc/mods/sodium/client/compatibility/workarounds): `common/src/boot/java/net/caffeinemc/mods/sodium/client/compatibility/workarounds`
- [Resource Checks](https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/checks/ResourcePackScanner.java): `common/src/main/java/net/caffeinemc/mods/sodium/client/checks/ResourcePackScanner.java`

### Configuration UI

- [Config API](https://github.com/caffeinemc/sodium/tree/dev/common/src/api/java/net/caffeinemc/mods/sodium/api/config): `common/src/api/java/net/caffeinemc/mods/sodium/api/config`
- [Config Manager](https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/config/ConfigManager.java): `common/src/main/java/net/caffeinemc/mods/sodium/client/config/ConfigManager.java`
- [Video Settings UI](https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/gui/VideoSettingsScreen.java): `common/src/main/java/net/caffeinemc/mods/sodium/client/gui/VideoSettingsScreen.java`
- [Option Search](https://github.com/caffeinemc/sodium/tree/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/config/search): `common/src/main/java/net/caffeinemc/mods/sodium/client/config/search`

### World Geometry

- [World Renderer](https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/render/SodiumWorldRenderer.java): `common/src/main/java/net/caffeinemc/mods/sodium/client/render/SodiumWorldRenderer.java`
- [Section Manager](https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/render/chunk/RenderSectionManager.java): `common/src/main/java/net/caffeinemc/mods/sodium/client/render/chunk/RenderSectionManager.java`
- [Section Storage](https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/render/chunk/storage/QueuedSectionStorage.java): `common/src/main/java/net/caffeinemc/mods/sodium/client/render/chunk/storage/QueuedSectionStorage.java`
- [Chunk Renderer](https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/render/chunk/ChunkRenderer.java): `common/src/main/java/net/caffeinemc/mods/sodium/client/render/chunk/ChunkRenderer.java`
- [Lighting Pipelines](https://github.com/caffeinemc/sodium/tree/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/model/light): `common/src/main/java/net/caffeinemc/mods/sodium/client/model/light`
- [Block Entity API](https://github.com/caffeinemc/sodium/tree/dev/common/src/api/java/net/caffeinemc/mods/sodium/api/blockentity): `common/src/api/java/net/caffeinemc/mods/sodium/api/blockentity`

### GPU Rendering

- [Section Mesh Data](https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/render/chunk/data/SectionRenderDataStorage.java): `common/src/main/java/net/caffeinemc/mods/sodium/client/render/chunk/data/SectionRenderDataStorage.java`
- [GPU Buffer Arenas](https://github.com/caffeinemc/sodium/tree/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/gpu/arena): `common/src/main/java/net/caffeinemc/mods/sodium/client/gpu/arena`
- [Draw Backend](https://github.com/caffeinemc/sodium/blob/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/gpu/device/backend/DrawBackend.java): `common/src/main/java/net/caffeinemc/mods/sodium/client/gpu/device/backend/DrawBackend.java`
- [Draw Batches](https://github.com/caffeinemc/sodium/tree/dev/common/src/main/java/net/caffeinemc/mods/sodium/client/gpu/device/batch): `common/src/main/java/net/caffeinemc/mods/sodium/client/gpu/device/batch`

### Other components

- **Minecraft Client**
- **Graphics Device**

## Connections

- Minecraft Client → Sodium Entry: launches
- Sodium Entry → Compatibility Checks: runs checks
- Compatibility Checks → Driver Workarounds: selects workarounds
- Sodium Entry → Resource Checks: checks resources
- Minecraft Client → Video Settings UI: opens settings
- Video Settings UI → Config Manager: saves options
- Config API → Config Manager: binds options
- Video Settings UI → Option Search: searches options
- Minecraft Client → World Renderer: renders world
- World Renderer → Section Manager: updates sections
- Section Manager → Section Storage: queues sections
- Section Manager → Chunk Renderer: submits builds
- Chunk Renderer → Lighting Pipelines: calculates lighting
- Chunk Renderer → Section Mesh Data: stores meshes
- Section Mesh Data → GPU Buffer Arenas: allocates buffers
- Section Manager → Draw Backend: renders visible sections
- Draw Backend → Draw Batches: dispatches batches
- Draw Batches → Graphics Device: submits draws
- Block Entity API → World Renderer: extends rendering
