# abisxir/alasgar architecture

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

- Interactive diagram: https://gitdiagram.com/abisxir/alasgar
- Repository: https://github.com/abisxir/alasgar

## Overview

##### Main Components
- Core Engine: This includes the engine’s initialization and main loop (modules like engine.nim, context.nim, system.nim, container.nim, error.nim, and logger.nim). These modules manage the central game loop, update cycles, and error handling.
- Math & Utility: The “aljebra” directory provides a custom math library (vector, quaternion, matrix modules, noise functions, etc.) which is critical for 3D computations.
- Graphics & Rendering:
– Ports: These are platform-specific interfaces for graphics and windowing (modules in “ports” like gl410.nim, gl460.nim, sdl2.nim, etc.) that abstract the underlying APIs.
– Render and Shaders: The “render” directory contains the render context, frame buffer management, and GPU interactions, while the “shaders” directory houses shader compilation and various shader types (vertex, fragment, BRDF, etc.). There is also integration for Vulkan in render/vulkan.nim.
– Effects: The “effects” folder includes modules for bloom, FXAA, SSAO, HBAO, and other post-processing effects.
- Scene & Entity Management:
– Scene and Entity: Modules such as scene.nim organize the scene graph. Entities are created with a combination of components.
– Components: The “components” directory has modules for various functionalities – animation, camera, collision, interactive behavior, lights, sprite, timer, transform, etc. These embody the “component-based” design.
– Systems: The “systems” directory (prepare.nim, render.nim, traverse.nim) likely implements the update and render systems that operate on the scene graph.
- Asset & Resource Management:
– Loader: Loader modules for asset file formats (such as obj and STL) help to import and prepare meshes, textures, and other resources.
– Resources: The “resources” folder handles loading images, models, and other asset types using relative paths (“res://…”).
- Physics & Collision: The “physics” directory provides collision detection and physics utilities (collision, ray, and plane calculations) that interact with components for collisions.
- Input & Scripting:
– Input: Input handling is provided (input.nim) along with interactive components for user events.
– Scripting: The engine supports “script” components allowing behavior definition through nim functions (as shown in the README’s examples using anonymous procedures).

- How the Graphics layer (via Ports and Render modules) receives instructions from Materials/Shader systems and how Effects are layered onto Camera Components.
- Asset flow from the Resource Loader (and assets folder) into Components that require textures or models.

##### Architectural Patterns and Design Principles
- Component-based Entity System: Entities are built from self-contained components (transform, camera, material, etc.) that can be mixed and matched.
- Abstraction Layers: There is a clear separation between the hardware/platform interfaces (ports) and the higher-level engine logic and scene management.
- Modularization: The engine separates concerns into directories (aljebra for math, components for game features, render for graphics, systems for processing, etc.) making the design highly modular.
- Shader/Effect Integration: The design allows writing shaders in Nim that are then transpiled to GLSL. The effects system leverages this to allow configurable post-processing.

##### Relevant Technologies and Frameworks
- Programming Language: Nim.
- Graphics APIs: OpenGL (with modules for specific versions and GLSL), and experimental Vulkan support.

##### Summary
- Around this, layer the “Scene & Entity Management” module that hosts components, including transform, camera, light, animation, material, and interactive elements.
- “Resource Loader/Assets” to both the Scene (for meshes and textures) and the Rendering Pipeline (for shaders and effects).
- Also, represent “Physics & Collision” feeding into the interactive system for handling user events.
- Finally, annotate the flow of data and configuration (for example, showing that scripts can affect the scene properties, or how uniform values get updated in shader effects).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core and Utility Layers
    Math1["Math & Utility"]:::math
    Core1["Core Engine"]:::core
    Math1 -->|"supports"| Core1

    %% Core Engine initiates hardware and resource management
    Core1 -->|"initiates"| Ports1["Ports (Hardware Abstraction)"]:::render
    Core1 -->|"loads"| Loader1["Asset Loader"]:::asset
    Core1 -->|"loads"| Resources1["Resources"]:::asset

    %% Scene & Entity Management Block
    Core1 -->|"updates"| Scene1["Scene Graph"]:::scene
    Scene1 -->|"organizes"| Components1["Components"]:::scene
    Components1 -->|"processedBy"| Systems1["Systems"]:::scene
    Script1["Scripting"]:::script
    Script1 -->|"customizes"| Scene1
    Input1["Input Handling"]:::input
    Input1 -->|"influences"| Components1
    Physics1["Physics & Collision"]:::physics
    Physics1 -->|"affects"| Components1

    %% Graphics & Rendering Block
    Systems1 -->|"renders"| Render1["Render & GPU"]:::render
    Ports1 -->|"providesAPI"| Render1
    Shaders1["Shaders"]:::render
    Shaders1 -->|"appliedIn"| Render1
    Effects1["Effects"]:::render
    Components1 -->|"activates"| Effects1
    Effects1 -->|"postProcesses"| Render1

    %% Asset & Resource integration with Scene & Rendering
    Loader1 -->|"suppliesAssets"| Components1
    Loader1 -->|"suppliesAssets"| Render1
    Resources1 -->|"suppliesAssets"| Components1
    Resources1 -->|"suppliesAssets"| Render1

    %% Additional Connections
    Core1 -->|"initiates"| Input1

    %% Nodes not yet connected in flow
    %% Scripting and Input are already connected above

    %% Click Events
    click Core1 "https://github.com/abisxir/alasgar/blob/main/alasgar/engine.nim"
    click Math1 "https://github.com/abisxir/alasgar/tree/main/alasgar/aljebra"
    click Ports1 "https://github.com/abisxir/alasgar/tree/main/alasgar/ports"
    click Render1 "https://github.com/abisxir/alasgar/tree/main/alasgar/render"
    click Shaders1 "https://github.com/abisxir/alasgar/tree/main/alasgar/shaders"
    click Effects1 "https://github.com/abisxir/alasgar/tree/main/alasgar/effects"
    click Scene1 "https://github.com/abisxir/alasgar/blob/main/alasgar/scene.nim"
    click Components1 "https://github.com/abisxir/alasgar/tree/main/alasgar/components"
    click Systems1 "https://github.com/abisxir/alasgar/tree/main/alasgar/systems"
    click Loader1 "https://github.com/abisxir/alasgar/tree/main/alasgar/loader"
    click Resources1 "https://github.com/abisxir/alasgar/tree/main/alasgar/resources"
    click Physics1 "https://github.com/abisxir/alasgar/tree/main/alasgar/physics"
    click Input1 "https://github.com/abisxir/alasgar/blob/main/alasgar/input.nim"
    click Script1 "https://github.com/abisxir/alasgar/blob/main/alasgar/components/script.nim"

    %% Class Definitions for Colors
    classDef core fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef math fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef scene fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef render fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef asset fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef physics fill:#FF7F7F,stroke:#000,stroke-width:2px;
    classDef input fill:#40E0D0,stroke:#000,stroke-width:2px;
    classDef script fill:#FFC0CB,stroke:#000,stroke-width:2px;
```
