# valiec/deepercaves architecture

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

- Interactive diagram: https://gitdiagram.com/valiec/deepercaves
- Repository: https://github.com/valiec/deepercaves

## Overview

DeeperCaves is a Forge mod that adds successive cave dimensions beneath the Overworld. The principal workflow is exploration: player-height thresholds trigger transfers between configured layers, whose providers and biome/chunk-generation code create distinct underground worlds. The mod also supplies cave blocks, items, structures and hostile mobs, plus a sculk vibration-and-activation feature with client effects. The README documents the multi-level-cave goal; the sampled excerpts confirm dimension transfers and parts of sculk and client behavior, but do not expose all registration and generation wiring.

Main entry points: [`src/main/java/com/kpabr/DeeperCaves/DeeperCaves.java`](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/DeeperCaves.java) (Mod entry point), [`src/main/java/com/kpabr/DeeperCore/dimstack/DeeperDimensionHandler.java`](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCore/dimstack/DeeperDimensionHandler.java) (Dimension handler), [`src/main/java/com/kpabr/DeeperCore/world/WorldProviderDeeperBase.java`](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCore/world/WorldProviderDeeperBase.java) (World providers), [`src/main/java/com/kpabr/DeeperCaves/DeeperSculkManager.java`](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/DeeperSculkManager.java) (Vibration events)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dimensions["Dimensions and terrain"]
  node_dimhandler["Dimension handler"]
  node_layers["Dimension layers<br/>[DeeperLayer.java]"]
  node_teleporter["Layer teleporter"]
  node_provider["World providers"]
  node_chunk["Chunk generation"]
  node_biomes["Biome selection"]
  node_biomelayer["Biome layers"]
  node_deco["Biome decoration"]
  node_worldgen["Cave dimensions"]
end

subgraph group_content["Cave content"]
  node_biomedefs["Cave biomes"]
  node_structures["Cave villages<br/>[CaveVillage.java]"]
  node_blocks["Blocks and fluids<br/>[DeeperBlocks.java]"]
  node_items["Items and charms<br/>[DeeperItems.java]"]
  node_mobs["Cave creatures<br/>[DeeperMobs.java]"]
end

subgraph group_sculk["Sculk interactions"]
  node_sculkblocks["Sculk blocks"]
  node_vibration["Vibration events"]
  node_activation["Sculk activation"]
  node_network["Sculk packets"]
end

subgraph group_runtime["Mod runtime"]
  node_playerdata["Player effects"]
  node_client["Client effects<br/>[ClientProxy.java]"]
  node_mod["Mod entry point<br/>[DeeperCaves.java]"]
end

node_player(("Player"))
node_forge(("Forge runtime"))

node_player -->|"crosses layer thresholds"| node_dimhandler
node_dimhandler -->|"checks layer rules"| node_layers
node_dimhandler -->|"transfers player"| node_teleporter
node_layers -->|"configures dimensions"| node_worldgen
node_worldgen -->|"provides worlds"| node_provider
node_provider -->|"generates chunks"| node_chunk
node_provider -->|"selects biomes"| node_biomes
node_biomes -->|"queries biome IDs"| node_biomelayer
node_biomedefs -->|"supplies biome set"| node_biomes
node_chunk -->|"decorates terrain"| node_deco
node_structures -->|"places structures"| node_blocks
node_forge -->|"dispatches events"| node_dimhandler
node_forge -->|"dispatches events"| node_playerdata
node_playerdata -->|"checks charm inventory"| node_items
node_sculkblocks -->|"posts vibrations"| node_vibration
node_vibration -->|"broadcasts activation"| node_activation
node_vibration -->|"sends activation packet"| node_network
node_network -->|"delivers client effect"| node_client
node_mod -->|"initializes worldgen"| node_worldgen
node_mod -->|"registers content"| node_blocks
node_mod -->|"registers content"| node_items
node_mod -->|"registers creatures"| node_mobs

click node_dimhandler "https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCore/dimstack/DeeperDimensionHandler.java"
click node_layers "https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCore/dimstack/DeeperLayer.java"
click node_teleporter "https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCore/dimstack/DeeperTeleporter.java"
click node_provider "https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCore/world/WorldProviderDeeperBase.java"
click node_chunk "https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCore/world/chunk/ChunkProviderDeeperBase.java"
click node_biomes "https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCore/world/WorldChunkManagerDeeper.java"
click node_biomelayer "https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCore/world/GenLayerDeeperCaves.java"
click node_deco "https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCore/world/biome/DeeperBaseDecorator.java"
click node_worldgen "https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/DeeperWorldgen.java"
click node_biomedefs "https://github.com/valiec/deepercaves/tree/master/src/main/java/com/kpabr/DeeperCaves/world/biome"
click node_structures "https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/structure/cavevillage/CaveVillage.java"
click node_blocks "https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/DeeperBlocks.java"
click node_items "https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/DeeperItems.java"
click node_mobs "https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/DeeperMobs.java"
click node_playerdata "https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/DeeperEventHandler.java"
click node_sculkblocks "https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/block/BlockSculkSensor.java"
click node_vibration "https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/DeeperSculkManager.java"
click node_activation "https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/SculkActivation.java"
click node_network "https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/network/PacketSculkActivationS2C.java"
click node_client "https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/client/ClientProxy.java"
click node_mod "https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/DeeperCaves.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_dimhandler,node_layers,node_teleporter,node_provider,node_chunk,node_biomes,node_biomelayer,node_deco,node_worldgen toneBlue
class node_biomedefs,node_structures,node_blocks,node_items,node_mobs toneAmber
class node_sculkblocks,node_vibration,node_activation,node_network toneMint
class node_playerdata,node_client,node_mod toneRose
class node_player,node_forge toneIndigo
```

## Components

### Dimensions and terrain

- [Dimension handler](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCore/dimstack/DeeperDimensionHandler.java): `src/main/java/com/kpabr/DeeperCore/dimstack/DeeperDimensionHandler.java`
- [Dimension layers](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCore/dimstack/DeeperLayer.java): `src/main/java/com/kpabr/DeeperCore/dimstack/DeeperLayer.java`
- [Layer teleporter](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCore/dimstack/DeeperTeleporter.java): `src/main/java/com/kpabr/DeeperCore/dimstack/DeeperTeleporter.java`
- [World providers](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCore/world/WorldProviderDeeperBase.java): `src/main/java/com/kpabr/DeeperCore/world/WorldProviderDeeperBase.java`
- [Chunk generation](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCore/world/chunk/ChunkProviderDeeperBase.java): `src/main/java/com/kpabr/DeeperCore/world/chunk/ChunkProviderDeeperBase.java`
- [Biome selection](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCore/world/WorldChunkManagerDeeper.java): `src/main/java/com/kpabr/DeeperCore/world/WorldChunkManagerDeeper.java`
- [Biome layers](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCore/world/GenLayerDeeperCaves.java): `src/main/java/com/kpabr/DeeperCore/world/GenLayerDeeperCaves.java`
- [Biome decoration](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCore/world/biome/DeeperBaseDecorator.java): `src/main/java/com/kpabr/DeeperCore/world/biome/DeeperBaseDecorator.java`
- [Cave dimensions](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/DeeperWorldgen.java): `src/main/java/com/kpabr/DeeperCaves/DeeperWorldgen.java`

### Cave content

- [Cave biomes](https://github.com/valiec/deepercaves/tree/master/src/main/java/com/kpabr/DeeperCaves/world/biome): `src/main/java/com/kpabr/DeeperCaves/world/biome`
- [Cave villages](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/structure/cavevillage/CaveVillage.java): `src/main/java/com/kpabr/DeeperCaves/structure/cavevillage/CaveVillage.java`
- [Blocks and fluids](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/DeeperBlocks.java): `src/main/java/com/kpabr/DeeperCaves/DeeperBlocks.java`
- [Items and charms](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/DeeperItems.java): `src/main/java/com/kpabr/DeeperCaves/DeeperItems.java`
- [Cave creatures](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/DeeperMobs.java): `src/main/java/com/kpabr/DeeperCaves/DeeperMobs.java`

### Sculk interactions

- [Sculk blocks](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/block/BlockSculkSensor.java): `src/main/java/com/kpabr/DeeperCaves/block/BlockSculkSensor.java`
- [Vibration events](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/DeeperSculkManager.java): `src/main/java/com/kpabr/DeeperCaves/DeeperSculkManager.java`
- [Sculk activation](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/SculkActivation.java): `src/main/java/com/kpabr/DeeperCaves/SculkActivation.java`
- [Sculk packets](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/network/PacketSculkActivationS2C.java): `src/main/java/com/kpabr/DeeperCaves/network/PacketSculkActivationS2C.java`

### Mod runtime

- [Player effects](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/DeeperEventHandler.java): `src/main/java/com/kpabr/DeeperCaves/DeeperEventHandler.java`
- [Client effects](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/client/ClientProxy.java): `src/main/java/com/kpabr/DeeperCaves/client/ClientProxy.java`
- [Mod entry point](https://github.com/valiec/deepercaves/blob/master/src/main/java/com/kpabr/DeeperCaves/DeeperCaves.java): `src/main/java/com/kpabr/DeeperCaves/DeeperCaves.java`

### Other components

- **Player**
- **Forge runtime**

## Connections

- Player → Dimension handler: crosses layer thresholds
- Dimension handler → Dimension layers: checks layer rules
- Dimension handler → Layer teleporter: transfers player
- Dimension layers → Cave dimensions: configures dimensions
- Cave dimensions → World providers: provides worlds
- World providers → Chunk generation: generates chunks
- World providers → Biome selection: selects biomes
- Biome selection → Biome layers: queries biome IDs
- Cave biomes → Biome selection: supplies biome set
- Chunk generation → Biome decoration: decorates terrain
- Cave villages → Blocks and fluids: places structures
- Forge runtime → Dimension handler: dispatches events
- Forge runtime → Player effects: dispatches events
- Player effects → Items and charms: checks charm inventory
- Sculk blocks → Vibration events: posts vibrations
- Vibration events → Sculk activation: broadcasts activation
- Vibration events → Sculk packets: sends activation packet
- Sculk packets → Client effects: delivers client effect
- Mod entry point → Cave dimensions: initializes worldgen
- Mod entry point → Blocks and fluids: registers content
- Mod entry point → Items and charms: registers content
- Mod entry point → Cave creatures: registers creatures