# hollow-cube/mapmaker architecture

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

- Interactive diagram: https://gitdiagram.com/hollow-cube/mapmaker
- Repository: https://github.com/hollow-cube/mapmaker

## Overview

Map Maker is Hollow Cube’s Minecraft creative map-building server. Players enter a server to build and edit maps; map-world logic, scripting, Terraform editing and replay support provide the main authoring/runtime capabilities, while server binaries delegate persistent storage and processing to the API server. The graph preserves the documented editor, map, compatibility and replay branches. Several subsystem implementations are unsampled, so their internal call relationships are omitted rather than inferred.

Main entry points: [`bin/api-server/src/main/java/net/hollowcube/apiserver/Main.java`](https://github.com/hollow-cube/mapmaker/blob/main/bin/api-server/src/main/java/net/hollowcube/apiserver/Main.java) (API Server), [`bin/map/src/main/java/net/hollowcube/mapmaker/map/MapMain.java`](https://github.com/hollow-cube/mapmaker/blob/main/bin/map/src/main/java/net/hollowcube/mapmaker/map/MapMain.java) (Map Servers), [`modules/map-core/src/main/java/net/hollowcube/mapmaker/map`](https://github.com/hollow-cube/mapmaker/tree/main/modules/map-core/src/main/java/net/hollowcube/mapmaker/map) (Map World), [`modules/map-runtime/src/main/java/net/hollowcube/mapmaker/runtime/replay/ApiSegmentedReplayStorage.java`](https://github.com/hollow-cube/mapmaker/blob/main/modules/map-runtime/src/main/java/net/hollowcube/mapmaker/runtime/replay/ApiSegmentedReplayStorage.java) (Replay Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_servers["Game Servers"]
  node_mapserver["Map Servers<br/>[MapMain.java]"]
  node_isolate["Isolated Maps<br/>[IsolateMain.java]"]
  node_proxy["Velocity Proxy<br/>[ProxyPlugin.java]"]
end

subgraph group_authoring["Map Authoring"]
  node_mapcore["Map World"]
  node_editor["Map Editor"]
  node_terraform["Terraform Editing<br/>[ApplyEngine.java]"]
  node_editbuffer["Edit Buffer<br/>[EditBuffer.java]"]
end

subgraph group_services["Platform Services"]
  node_api["API Server<br/>[Main.java]"]
  node_mapservice["Map Service"]
  node_replayservice["Replay Service"]
  node_session["Session Service"]
end

subgraph group_runtime["Runtime Systems"]
  node_scripts["Script Engine<br/>[ScriptEngine.java]"]
  node_replay["Replay Runtime"]
  node_replayformat["Replay Format"]
  node_packer["Resource Pack<br/>[Packer.java]"]
end

subgraph group_integrity["Capture and Compatibility"]
  node_anticheat["Anticheat Capture<br/>[CaptureEngine.java]"]
  node_trace["Trace Logs<br/>[TraceWriter.java]"]
  node_compat["Client Compatibility"]
end

node_player(("Map Builder"))

node_player -->|"builds on"| node_mapserver
node_mapserver -->|"delegates storage"| node_api
node_isolate -->|"delegates storage"| node_api
node_mapserver -.->|"hosts maps"| node_mapcore
node_mapserver -.->|"provides editing"| node_editor
node_editor -.->|"applies edits"| node_terraform
node_terraform -->|"reads edits"| node_editbuffer
node_mapcore -.->|"runs scripts"| node_scripts
node_scripts -->|"binds world"| node_mapcore
node_replay -->|"loads and writes"| node_replayformat
node_replay -->|"calls replay API"| node_replayservice
node_api -.->|"hosts map APIs"| node_mapservice
node_api -.->|"hosts replay APIs"| node_replayservice
node_api -.->|"hosts session APIs"| node_session
node_anticheat -->|"assembles traces"| node_trace
node_proxy -.->|"uses services"| node_api
node_mapserver -.->|"supports clients"| node_compat

click node_mapserver "https://github.com/hollow-cube/mapmaker/blob/main/bin/map/src/main/java/net/hollowcube/mapmaker/map/MapMain.java"
click node_isolate "https://github.com/hollow-cube/mapmaker/blob/main/bin/map-isolate/src/main/java/net/hollowcube/mapmaker/isolate/IsolateMain.java"
click node_proxy "https://github.com/hollow-cube/mapmaker/blob/main/bin/proxy-plugin/src/main/java/net/hollowcube/proxy/ProxyPlugin.java"
click node_mapcore "https://github.com/hollow-cube/mapmaker/tree/main/modules/map-core/src/main/java/net/hollowcube/mapmaker/map"
click node_editor "https://github.com/hollow-cube/mapmaker/tree/main/modules/map-editor/src/main/java/net/hollowcube/mapmaker/editor"
click node_terraform "https://github.com/hollow-cube/mapmaker/blob/main/modules/terraform/src/main/java/net/hollowcube/terraform/apply/ApplyEngine.java"
click node_editbuffer "https://github.com/hollow-cube/mapmaker/blob/main/modules/terraform/src/main/java/net/hollowcube/terraform/buffer/EditBuffer.java"
click node_scripts "https://github.com/hollow-cube/mapmaker/blob/main/modules/map-runtime/src/main/java/net/hollowcube/mapmaker/scripting/ScriptEngine.java"
click node_replay "https://github.com/hollow-cube/mapmaker/blob/main/modules/map-runtime/src/main/java/net/hollowcube/mapmaker/runtime/replay/ApiSegmentedReplayStorage.java"
click node_replayformat "https://github.com/hollow-cube/mapmaker/blob/main/modules/replay/src/main/java/dev/hollowcube/replay/io/SegmentedReplay.java"
click node_api "https://github.com/hollow-cube/mapmaker/blob/main/bin/api-server/src/main/java/net/hollowcube/apiserver/Main.java"
click node_mapservice "https://github.com/hollow-cube/mapmaker/blob/main/bin/api-server/src/main/java/net/hollowcube/apiserver/map/MapServiceImpl.java"
click node_replayservice "https://github.com/hollow-cube/mapmaker/blob/main/bin/api-server/src/main/java/net/hollowcube/apiserver/replay/ReplayServiceImpl.java"
click node_session "https://github.com/hollow-cube/mapmaker/blob/main/bin/api-server/src/main/java/net/hollowcube/apiserver/session/SessionServiceImpl.java"
click node_anticheat "https://github.com/hollow-cube/mapmaker/blob/main/modules/anticheat/src/main/java/net/hollowcube/anticheat/capture/CaptureEngine.java"
click node_trace "https://github.com/hollow-cube/mapmaker/blob/main/modules/anticheat/src/main/java/net/hollowcube/anticheat/log/TraceWriter.java"
click node_compat "https://github.com/hollow-cube/mapmaker/blob/main/modules/compat/src/main/java/net/hollowcube/compat/axiom/AxiomPacketHandler.java"
click node_packer "https://github.com/hollow-cube/mapmaker/blob/main/bin/packer/src/main/java/net/hollowcube/mapmaker/Packer.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_mapserver,node_isolate,node_proxy toneBlue
class node_mapcore,node_editor,node_terraform,node_editbuffer toneAmber
class node_api,node_mapservice,node_replayservice,node_session toneMint
class node_scripts,node_replay,node_replayformat,node_packer toneRose
class node_anticheat,node_trace,node_compat,node_player toneIndigo
```

## Components

### Game Servers

- [Map Servers](https://github.com/hollow-cube/mapmaker/blob/main/bin/map/src/main/java/net/hollowcube/mapmaker/map/MapMain.java): `bin/map/src/main/java/net/hollowcube/mapmaker/map/MapMain.java`
- [Isolated Maps](https://github.com/hollow-cube/mapmaker/blob/main/bin/map-isolate/src/main/java/net/hollowcube/mapmaker/isolate/IsolateMain.java): `bin/map-isolate/src/main/java/net/hollowcube/mapmaker/isolate/IsolateMain.java`
- [Velocity Proxy](https://github.com/hollow-cube/mapmaker/blob/main/bin/proxy-plugin/src/main/java/net/hollowcube/proxy/ProxyPlugin.java): `bin/proxy-plugin/src/main/java/net/hollowcube/proxy/ProxyPlugin.java`

### Map Authoring

- [Map World](https://github.com/hollow-cube/mapmaker/tree/main/modules/map-core/src/main/java/net/hollowcube/mapmaker/map): `modules/map-core/src/main/java/net/hollowcube/mapmaker/map`
- [Map Editor](https://github.com/hollow-cube/mapmaker/tree/main/modules/map-editor/src/main/java/net/hollowcube/mapmaker/editor): `modules/map-editor/src/main/java/net/hollowcube/mapmaker/editor`
- [Terraform Editing](https://github.com/hollow-cube/mapmaker/blob/main/modules/terraform/src/main/java/net/hollowcube/terraform/apply/ApplyEngine.java): `modules/terraform/src/main/java/net/hollowcube/terraform/apply/ApplyEngine.java`
- [Edit Buffer](https://github.com/hollow-cube/mapmaker/blob/main/modules/terraform/src/main/java/net/hollowcube/terraform/buffer/EditBuffer.java): `modules/terraform/src/main/java/net/hollowcube/terraform/buffer/EditBuffer.java`

### Platform Services

- [API Server](https://github.com/hollow-cube/mapmaker/blob/main/bin/api-server/src/main/java/net/hollowcube/apiserver/Main.java): `bin/api-server/src/main/java/net/hollowcube/apiserver/Main.java`
- [Map Service](https://github.com/hollow-cube/mapmaker/blob/main/bin/api-server/src/main/java/net/hollowcube/apiserver/map/MapServiceImpl.java): `bin/api-server/src/main/java/net/hollowcube/apiserver/map/MapServiceImpl.java`
- [Replay Service](https://github.com/hollow-cube/mapmaker/blob/main/bin/api-server/src/main/java/net/hollowcube/apiserver/replay/ReplayServiceImpl.java): `bin/api-server/src/main/java/net/hollowcube/apiserver/replay/ReplayServiceImpl.java`
- [Session Service](https://github.com/hollow-cube/mapmaker/blob/main/bin/api-server/src/main/java/net/hollowcube/apiserver/session/SessionServiceImpl.java): `bin/api-server/src/main/java/net/hollowcube/apiserver/session/SessionServiceImpl.java`

### Runtime Systems

- [Script Engine](https://github.com/hollow-cube/mapmaker/blob/main/modules/map-runtime/src/main/java/net/hollowcube/mapmaker/scripting/ScriptEngine.java): `modules/map-runtime/src/main/java/net/hollowcube/mapmaker/scripting/ScriptEngine.java`
- [Replay Runtime](https://github.com/hollow-cube/mapmaker/blob/main/modules/map-runtime/src/main/java/net/hollowcube/mapmaker/runtime/replay/ApiSegmentedReplayStorage.java): `modules/map-runtime/src/main/java/net/hollowcube/mapmaker/runtime/replay/ApiSegmentedReplayStorage.java`
- [Replay Format](https://github.com/hollow-cube/mapmaker/blob/main/modules/replay/src/main/java/dev/hollowcube/replay/io/SegmentedReplay.java): `modules/replay/src/main/java/dev/hollowcube/replay/io/SegmentedReplay.java`
- [Resource Pack](https://github.com/hollow-cube/mapmaker/blob/main/bin/packer/src/main/java/net/hollowcube/mapmaker/Packer.java): `bin/packer/src/main/java/net/hollowcube/mapmaker/Packer.java`

### Capture and Compatibility

- [Anticheat Capture](https://github.com/hollow-cube/mapmaker/blob/main/modules/anticheat/src/main/java/net/hollowcube/anticheat/capture/CaptureEngine.java): `modules/anticheat/src/main/java/net/hollowcube/anticheat/capture/CaptureEngine.java`
- [Trace Logs](https://github.com/hollow-cube/mapmaker/blob/main/modules/anticheat/src/main/java/net/hollowcube/anticheat/log/TraceWriter.java): `modules/anticheat/src/main/java/net/hollowcube/anticheat/log/TraceWriter.java`
- [Client Compatibility](https://github.com/hollow-cube/mapmaker/blob/main/modules/compat/src/main/java/net/hollowcube/compat/axiom/AxiomPacketHandler.java): `modules/compat/src/main/java/net/hollowcube/compat/axiom/AxiomPacketHandler.java`

### Other components

- **Map Builder**

## Connections

- Map Builder → Map Servers: builds on (evidence: `README.md`)
- Map Servers → API Server: delegates storage (evidence: `README.md`)
- Isolated Maps → API Server: delegates storage (evidence: `README.md`)
- Map Servers → Map World: hosts maps
- Map Servers → Map Editor: provides editing
- Map Editor → Terraform Editing: applies edits
- Terraform Editing → Edit Buffer: reads edits (evidence: `modules/terraform/src/main/java/net/hollowcube/terraform/apply/ApplyEngine.java`)
- Map World → Script Engine: runs scripts (evidence: `modules/map-runtime/src/main/java/net/hollowcube/mapmaker/scripting/ScriptEngine.java`)
- Script Engine → Map World: binds world (evidence: `modules/map-runtime/src/main/java/net/hollowcube/mapmaker/scripting/ScriptEngine.java`)
- Replay Runtime → Replay Format: loads and writes (evidence: `modules/map-runtime/src/main/java/net/hollowcube/mapmaker/runtime/replay/ApiSegmentedReplayStorage.java`)
- Replay Runtime → Replay Service: calls replay API (evidence: `modules/map-runtime/src/main/java/net/hollowcube/mapmaker/runtime/replay/ApiSegmentedReplayStorage.java`)
- API Server → Map Service: hosts map APIs
- API Server → Replay Service: hosts replay APIs
- API Server → Session Service: hosts session APIs
- Anticheat Capture → Trace Logs: assembles traces (evidence: `modules/anticheat/src/main/java/net/hollowcube/anticheat/capture/CaptureEngine.java`)
- Velocity Proxy → API Server: uses services
- Map Servers → Client Compatibility: supports clients
