# toplib/v-engine architecture

> Architecture diagram of the GitHub repository toplib/v-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/toplib/v-engine
- Repository: https://github.com/toplib/v-engine

## Overview

##### Project Type and Purpose
- Project Type: A Java-based 3D engine.
- Purpose: Providing lightweight 3D rendering capabilities, asset management, and input handling for game or visualization applications.
- Indications: The README explicitly states it’s a “lightweight and simple 3D java engine,” and the file tree shows dedicated packages for rendering (shaders, window, camera), file management (filesystem), and interactive features (HID/input).

##### File Structure
- Notice key directories:
- “src/main/java/org/engine/vengine”: Contains the core engine modules.
- Subdirectories like “render” (camera, window, shader, materials), “hid” (input-related classes), “filesystem” (asset management, package system), “mesh”, “objects”, “parser”, “time”, and “utils”.
- The existence of a “resources” directory containing configuration files (engine.conf.ini), shader files (fragment.glsl, vertex.glsl), and a sample 3D model (cube.obj) indicates resource loading and shader management.
- The Maven build configuration (pom.xml) and GitHub workflows (in .github/workflows) reflect standard build and release processes but are less directly related to the runtime architecture.

##### README for Additional Insights
- It simply highlights that this engine is lightweight and simple, so the focus will be on clear delineation of responsibilities within the engine rather than heavy abstraction layers.

##### Main Components and Their Relationships
a. Core Engine:
- Entry Point: Application.java. This file likely bootstraps the engine and sets up the core loop.
- Engine Components: Test.java and UnsafeMemoryExample.java (for performance or experimental features).
b. Filesystem Module:
- Components: Asset.java, PackageSystem.java, RamStorage.java, and Default.java in the filesystem package.
- Role: To manage assets (models, textures, shaders) and possibly configuration files.
c. Rendering Module:
- Components in the “render” package: Render.java, Camera.java, Window.java, and related shader (Shader.java) and material (Texture.java) classes.
- Relationships: The rendering component likely retrieves 3D objects and meshes (from the mesh package) and uses shader programs (vertex.glsl and fragment.glsl from resources) to render scenes.
d. Mesh and Object Management:
- Components: Mesh.java, GameObject.java.
- Role: Represent geometry and scene objects.
e. Input / Human Interface Device (HID):
- Components: Input.java and KeyCode.java in the hid/input package.
- Role: Capture and process user input for interactive applications.
f. Parsing and Resource Interpretation:
- Component: ObjectParser.java.
- Likely used to parse 3D models or configuration files.
g. Utility Components:
- Utilities in “utils” (e.g., Face.java, Normal.java, Vertex.java) support the underlying data structures and calculations needed for rendering.

- "Application / Main Engine"
- "Filesystem Manager" (including Asset, PackageSystem, RamStorage)
- "Rendering Engine" (with subcomponents: Render, Camera, Window, Shader, Materials)
- "Mesh & Object Management" (Mesh, GameObject)
- "Input Handling" (Input, KeyCode)
- "Parser" (ObjectParser)
- "Utility Library" (all the utility classes like Face, Vertex, etc.)
- For example, Application.java calls into the Rendering Engine and sets up the render loop.
- The Rendering Engine requests resources (models, shaders) from the Filesystem Manager.
- Mesh & Object Management supplies data to the Rendering Engine.
- Input Handling feeds user-generated events to control the engine state.
- The Parser may be used to initialize objects or process configuration data.
- Mention that it’s using Java (and Maven as the build tool).
- Resource types (GLSL shaders, .obj files) in the rendering module.
- That experimental or utility components (e.g., UnsafeMemoryExample) represent advanced usage scenarios.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Layer
    subgraph "Core Engine"
        core["Application / Main Engine"]:::core
    end

    %% Modules Layer
    subgraph "Engine Modules"
        filesystem["Filesystem Manager"]:::filesystem
        rendering["Rendering Engine"]:::rendering
        input["Input Handling"]:::input
        parser["Parser Module"]:::parser
        utils["Utility Library"]:::utils
        subgraph "Mesh & Object Management"
            mesh["Mesh"]:::mesh
            gameobject["GameObject"]:::mesh
        end
    end

    %% Connections
    core -->|"bootstraps"| rendering
    core -->|"loadsAssets"| filesystem
    input -->|"sendInput"| core
    rendering -->|"getAssets"| filesystem
    rendering -->|"meshData"| mesh
    parser -->|"parseToMesh"| mesh
    parser -->|"parseToObject"| gameobject
    utils -->|"supportsCore"| core
    utils -->|"supportsRender"| rendering
    utils -->|"supportsMesh"&gameobject| mesh

    %% Click Events
    click core "https://github.com/toplib/v-engine/blob/master/src/main/java/org/engine/vengine/Application.java"
    click filesystem "https://github.com/toplib/v-engine/tree/master/src/main/java/org/engine/vengine/filesystem/"
    click rendering "https://github.com/toplib/v-engine/tree/master/src/main/java/org/engine/vengine/render/"
    click mesh "https://github.com/toplib/v-engine/blob/master/src/main/java/org/engine/vengine/mesh/Mesh.java"
    click gameobject "https://github.com/toplib/v-engine/blob/master/src/main/java/org/engine/vengine/objects/GameObject.java"
    click input "https://github.com/toplib/v-engine/tree/master/src/main/java/org/engine/vengine/hid/input/"
    click parser "https://github.com/toplib/v-engine/blob/master/src/main/java/org/engine/vengine/parser/ObjectParser.java"
    click utils "https://github.com/toplib/v-engine/tree/master/src/main/java/org/engine/vengine/utils/"

    %% Styles
    classDef core fill:#f9a,stroke:#333,stroke-width:2px;
    classDef filesystem fill:#9cf,stroke:#333,stroke-width:2px;
    classDef rendering fill:#9f9,stroke:#333,stroke-width:2px;
    classDef mesh fill:#fc9,stroke:#333,stroke-width:2px;
    classDef input fill:#cff,stroke:#333,stroke-width:2px;
    classDef parser fill:#ff9,stroke:#333,stroke-width:2px;
    classDef utils fill:#ddd,stroke:#333,stroke-width:2px;
```
