# hytopiagg/world-editor architecture

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

- Interactive diagram: https://gitdiagram.com/hytopiagg/world-editor
- Repository: https://github.com/hytopiagg/world-editor

## Overview

##### Project type and purpose
- This is a single-page, client-side world editor built with Create React App. Its purpose is to let users import or procedurally generate Minecraft-style worlds in the browser, view and manipulate blocks, models, and textures in 3D, and export or save their creations.

##### File structure
- Top-level:
- package.json, .env, build scripts (scripts/generate-model-manifest.js) – typical CRA config
- public/ – static assets (blocks, models, sounds, UI images, certificates) served by the web server
- src/ – application source code
- src/index.js + App.js – React entry point and root component
- src/css/ & src/images – static styling and images consumed by components
- src/js/ – the core JavaScript modules, organized by function:
- components/ – React UI panel, toolbar, editors, wizard steps
- tools/ – user actions (GroundTool, WallTool, SeedGeneratorTool, etc.)
- managers/ – high-level orchestration (BlockTypesManager, SpatialGridManager)
- utils/ – helper libraries (PerlinNoise, NBTParser, AnvilParser)
- workers/ – Web Workers for CPU-intensive tasks (SpatialHashWorker, minecraftParserWorker)
- DatabaseManager.js – in-browser storage abstraction (IndexedDB or similar)
- EnvironmentBuilder.js, TerrainBuilder.js, Camera.js, Sound.js – 3D scene and media orchestration

##### README for additional insights
- Confirms Create React App, static hosting, development vs. production builds. No server-side code beyond static file serving.

##### Main components & their interactions
a. Frontend React Application
– React UI Layer (components/*) orchestrates user interactions, renders toolbars, sidebars, modals.
– Uses CSS modules (src/css) for styling.
b. Asset & Data Layer
– Asset Loader (public/assets + generate-model-manifest.js) fetches glTF, textures, sounds.
– DatabaseManager persists user sessions, undo history, imported world data.
c. Engine Layer
– EnvironmentBuilder, TerrainBuilder, ChunkManager build and update 3D scene graph.
– Camera controls via Camera.js.
– Sound manager (Sound.js) streams audio assets.
d. Tools & Managers
– ToolManager delegates pointer events to specific tools (e.g., Block placement, PipeTool, SchematicPlacementTool).
– BlockTypesManager and SpatialGridManager maintain metadata and spatial partitioning for fast lookups.
e. Web Workers
– spatialHashWorker: builds/queries spatial hash grid off main thread.
– minecraftParserWorker: parses NBT/Anvil files into world data asynchronously.
f. External Libraries & Frameworks
– React, React-DOM, Webpack (CRA), Three.js (implied by glTF usage), Web Workers API, possibly Tone.js or Web Audio API for sounds.

##### Architectural patterns & design principles
- Modular, feature-based code organization
- Separation of Concerns: UI (React) vs. business logic (managers, tools) vs. rendering engine vs. data parsing (workers)
- Asynchronous parsing and heavy computation offloaded to Web Workers
- In-browser persistence via DatabaseManager (IndexedDB or localStorage)
- Asset pipeline: static assets (public/) + manifest generation script

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Static Server
    subgraph "Static File Server / CDN"
        AssetServer("Static File Server / CDN"):::external
        Generate["Asset Manifest Generator"]:::external
    end

    %% Browser Boundary
    subgraph "Browser"
        %% Frontend UI Layer
        subgraph "Frontend UI Layer"
            Entry["React Entry Point (index.js, App.js)"]:::ui
            Components["UI Components"]:::ui
            CSS["CSS Styling"]:::ui
        end

        %% Business Logic Layer
        subgraph "Business Logic Layer"
            ToolManager["ToolManager"]:::logic
            subgraph "Tools"
                Ground["GroundTool"]:::logic
                Wall["WallTool"]:::logic
                Pipe["PipeTool"]:::logic
                Schematic["SchematicPlacementTool"]:::logic
                Seed["SeedGeneratorTool"]:::logic
            end
            subgraph "Managers"
                BTM["BlockTypesManager"]:::logic
                SGM["SpatialGridManager"]:::logic
            end
            ImportExport["Import/Export Utilities"]:::logic
            LoadingManager["Loading Manager"]:::logic
            UndoRedo["Undo/Redo History"]:::logic
            Utils["Utilities"]:::logic
        end

        %% Engine Layer
        subgraph "Engine Layer"
            EnvBuilder["EnvironmentBuilder"]:::engine
            TerrainBuilder["TerrainBuilder"]:::engine
            subgraph "Chunk & Partitioning"
                CM["ChunkManager"]:::engine
                CMM["ChunkMeshManager"]:::engine
                SHG["SpatialHashGrid"]:::engine
            end
            Camera["Camera Controls"]:::engine
            Sound["Sound Manager"]:::engine
        end

        %% Database
        Database["DatabaseManager"]:::db

        %% Web Workers
        subgraph "Web Workers"
            WH1["SpatialHashWorker"]:::worker
            WH2["minecraftParserWorker"]:::worker
        end

        %% Outputs
        Canvas["Canvas/WebGL"]:::output
        Audio["Audio API"]:::output
    end

    %% Connections
    AssetServer -->|"serves index.html, JS, CSS"| Entry
    Generate -->|"generates manifest for"| AssetServer

    Entry -->|renders| Components
    Components -->|dispatches events| ToolManager
    Components -->|styled by| CSS

    ToolManager -->|delegates to| Ground
    ToolManager -->|delegates to| Wall
    ToolManager -->|delegates to| Pipe
    ToolManager -->|delegates to| Schematic
    ToolManager -->|delegates to| Seed

    BTM -->|metadata| Ground
    SGM -->|partition data| Ground
    Utils -->|helpers & parsing| BTM

    ToolManager -->|scene commands| EnvBuilder
    EnvBuilder -->|builds world| TerrainBuilder
    TerrainBuilder -->|mesh data| CM
    CM -->|mesh upkeep| CMM
    CMM -->|grid updates| SHG
    CM -->|scene updates| EnvBuilder

    EnvBuilder -->|renders| Canvas
    Sound -->|plays| Audio

    ToolManager <-->|"read/write"| Database
    EnvBuilder <-->|"persist/load"| Database

    ToolManager -->|postMessage| WH1
    WH1 -->|onmessage| ToolManager
    Utils -->|postMessage| WH2
    WH2 -->|onmessage| Utils

    %% Click Events
    click Entry "https://github.com/hytopiagg/world-editor/blob/main/src/index.js"
    click Entry "https://github.com/hytopiagg/world-editor/blob/main/src/App.js"
    click Components "https://github.com/hytopiagg/world-editor/tree/main/src/js/components/"
    click CSS "https://github.com/hytopiagg/world-editor/tree/main/src/css/"
    click AssetServer "https://github.com/hytopiagg/world-editor/tree/main/public/assets/"
    click AssetServer "https://github.com/hytopiagg/world-editor/blob/main/public/index.html"
    click Generate "https://github.com/hytopiagg/world-editor/blob/main/scripts/generate-model-manifest.js"
    click Database "https://github.com/hytopiagg/world-editor/blob/main/src/js/DatabaseManager.js"
    click EnvBuilder "https://github.com/hytopiagg/world-editor/blob/main/src/js/EnvironmentBuilder.js"
    click TerrainBuilder "https://github.com/hytopiagg/world-editor/blob/main/src/js/TerrainBuilder.js"
    click Camera "https://github.com/hytopiagg/world-editor/blob/main/src/js/Camera.js"
    click Sound "https://github.com/hytopiagg/world-editor/blob/main/src/js/Sound.js"
    click ToolManager "https://github.com/hytopiagg/world-editor/blob/main/src/js/tools/ToolManager.js"
    click Ground "https://github.com/hytopiagg/world-editor/blob/main/src/js/tools/GroundTool.js"
    click Wall "https://github.com/hytopiagg/world-editor/blob/main/src/js/tools/WallTool.js"
    click Pipe "https://github.com/hytopiagg/world-editor/blob/main/src/js/tools/PipeTool.js"
    click Schematic "https://github.com/hytopiagg/world-editor/blob/main/src/js/tools/SchematicPlacementTool.js"
    click Seed "https://github.com/hytopiagg/world-editor/blob/main/src/js/tools/SeedGeneratorTool.js"
    click BTM "https://github.com/hytopiagg/world-editor/blob/main/src/js/managers/BlockTypesManager.js"
    click SGM "https://github.com/hytopiagg/world-editor/blob/main/src/js/managers/SpatialGridManager.js"
    click CM "https://github.com/hytopiagg/world-editor/blob/main/src/js/chunks/ChunkManager.js"
    click CMM "https://github.com/hytopiagg/world-editor/blob/main/src/js/chunks/ChunkMeshManager.js"
    click SHG "https://github.com/hytopiagg/world-editor/blob/main/src/js/chunks/SpatialHashGrid.js"
    click WH1 "https://github.com/hytopiagg/world-editor/blob/main/src/js/workers/SpatialHashWorker.js"
    click WH2 "https://github.com/hytopiagg/world-editor/blob/main/src/js/workers/minecraftParserWorker.js"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366d6,stroke-width:1px;
    classDef logic fill:#E2F0CB,stroke:#6A993E,stroke-width:1px;
    classDef engine fill:#FDE2B5,stroke:#D17F01,stroke-width:1px;
    classDef worker fill:#FFF4B1,stroke:#D4A017,stroke-width:1px;
    classDef db fill:#E0E0E0,stroke:#888888,stroke-width:1px,stroke-dasharray: 5 5;
    classDef external fill:#EBF5FB,stroke:#3498DB,stroke-width:1px,stroke-dasharray: 5 5;
    classDef output fill:#F3E5F5,stroke:#8E44AD,stroke-width:1px,stroke-dasharray: 2 2;
```
