# clockworklabs/spacetimedb-minecraft architecture

> Architecture diagram of the GitHub repository clockworklabs/spacetimedb-minecraft, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/clockworklabs/spacetimedb-minecraft
- Repository: https://github.com/clockworklabs/spacetimedb-minecraft

## Overview

The project is a specialized Minecraft server implementation written in Rust that runs on SpacetimeDB. It is split into two main applications:
- A SpacetimeDB module (located in crates/mc173-module and also partly in crates/module) that encapsulates the core game logic (such as handling biomes, blocks, entities, world simulation, terrain generation, and more)—essentially all the server-side mechanics of Minecraft.
- A Minecraft Proxy Server (in crates/mc173-server) that acts as a bridge between the Minecraft client and the SpacetimeDB module, because SpacetimeDB cannot interface directly with the client.

##### Main Components
– Minecraft Client: Represents the end-user client connecting to the game server.
– Minecraft Proxy Server: Handles network communication with the client. Inside this component, include subsystems such as network handling, command processing, protocol conversion (note the “autogen” files), and player management.
– SpacetimeDB Module: Hosted on SpacetimeDB; responsible for the internal game rules and simulation logic. This divides further into various submodules, for example:
- Block handling (with files for different block types such as bed, button, door, etc.),
- Block entity management (chest, dispenser, furnace, jukebox, etc.),
- World and chunk management (world, chunk, storage, etc.),
- Entity and physics handling (entity, tick logic, random generation, etc.),
- World generation and terrain processing (cave, dungeon, nether, noise, etc.).
– External Service: SpacetimeDB itself (the cloud or external service platform where the module is deployed), which will be integrated via the SpacetimeDB CLI or API endpoints.

##### Architectural Patterns and Internal Structure
– Emphasize the clear separation of concerns: the Proxy Server handles protocol-level and network communication concerns, while the Module encapsulates core game logic and simulation.
– Highlight use of auto-generated code in the mc173-server (under “autogen”), which likely represents protocol definitions or data conversion utilities that support client and server communication.

##### Relevant Technologies and Frameworks
– Rust and Cargo as the primary technology stack.
– SpacetimeDB as the deployment platform for the game logic module.
– The design should also reference internal libraries for network I/O, game simulation, and protocol handling (e.g., items, block logic, world tick processing).

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Components
    subgraph "External Components"
        Client["Minecraft Client"]:::client
        Service["SpacetimeDB Service"]:::external
    end

    %% Proxy Server and its subsystems
    subgraph "Minecraft Proxy Server"
        Proxy["Minecraft Proxy Server"]:::proxy
        Net["Network Handling"]:::proxy
        Command["Command Processing"]:::proxy
        Player["Player Management"]:::proxy
        Auto["Protocol Conversion (autogen)"]:::autogen
    end

    %% SpacetimeDB Module and its subsystems
    subgraph "SpacetimeDB Module"
        Module["SpacetimeDB Module"]:::module
        Supp["Supplementary Code"]:::module
        Block["Block Handling"]:::module
        BlockEntity["Block Entity Management"]:::module
        WorldChunk["World and Chunk Management"]:::module
        EntityPhys["Entity & Physics Handling"]:::module
        WorldGen["World Generation & Terrain Processing"]:::module
    end

    %% Main Interactions
    Client -->|"connects"| Proxy
    Proxy -->|"forwards commands"| Module
    Module -->|"game state updates"| Proxy
    Proxy -->|"integrates"| Service
    Module -->|"deployed_on"| Service

    %% Internal Proxy Structure
    Proxy -->|"handles"| Net
    Proxy -->|"processes"| Command
    Proxy -->|"manages"| Player
    Proxy -->|"converts"| Auto

    %% Internal Module Structure
    Module -->|"delegates"| Block
    Module -->|"manages"| BlockEntity
    Module -->|"controls"| WorldChunk
    Module -->|"updates"| EntityPhys
    Module -->|"generates"| WorldGen
    Module -->|"includes"| Supp

    %% Click Events for Component Mapping
    click Module "https://github.com/clockworklabs/spacetimedb-minecraft/tree/master/crates/mc173-module"
    click Supp "https://github.com/clockworklabs/spacetimedb-minecraft/tree/master/crates/module"
    click Proxy "https://github.com/clockworklabs/spacetimedb-minecraft/tree/master/crates/mc173-server"
    click Auto "https://github.com/clockworklabs/spacetimedb-minecraft/tree/master/crates/mc173-server/src/autogen"
    click Block "https://github.com/clockworklabs/spacetimedb-minecraft/tree/master/crates/mc173-module/src/block"
    click BlockEntity "https://github.com/clockworklabs/spacetimedb-minecraft/tree/master/crates/mc173-module/src/block_entity"
    click WorldChunk "https://github.com/clockworklabs/spacetimedb-minecraft/tree/master/crates/mc173-module/src/world"
    click EntityPhys "https://github.com/clockworklabs/spacetimedb-minecraft/tree/master/crates/mc173-module/src/entity"
    click WorldGen "https://github.com/clockworklabs/spacetimedb-minecraft/tree/master/crates/mc173-module/src/gen"

    %% Styles
    classDef client fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef proxy fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef autogen fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef module fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:2px;
```
