# knightfemale/gdextensionecs architecture

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

- Interactive diagram: https://gitdiagram.com/knightfemale/gdextensionecs
- Repository: https://github.com/knightfemale/gdextensionecs

## Overview

##### Project type and purpose
- This is an open-source Godot plugin (a GDExtension) that implements a minimal-intrusion ECS (Entity-Component-System) framework in C++.
- Its purpose is to let Godot 4.x users compose game logic via an ECS architecture, using sparse sets for component storage, and register custom native nodes in the Godot editor.

##### File structure
Top-level items:
- SConstruct – build script (SCons) for compiling the GDExtension.
- godot-cpp (git submodule) – Godot’s C++ binding generator and runtime headers.
- src/ – core C++ ECS source files and generated binding code:
– gde_entity, gde_component, gde_system, gde_system_manager, sparse_set (the heart of ECS).
– gen/ (doc_data.gen.cpp, register_types.cpp/h) for Godot type registration.
- demo/ – two demo projects: one using GDExtension (bin/*.gdextension) and one in GDScript (DEMO0-GDS).
- doc_classes/ – XML documentation exported for each ECS element.
- README.md, LICENSE, .gitignore – metadata.

##### Extract architecture hints from the README
- The framework is built from scratch around sparse sets to overcome Godot’s type-registration quirks.
- You compile via SCons into a .gdextension, open demo in Godot 4.4.1 to see usage.
- Future roadmap: multithreading, version compatibility.

1. Godot Engine / Editor
2. GDExtension Loader (.gdextension plugin)
3. Native ECS Module (C++ code)
- Entity Manager (GdeEntity)
- Component Storage (sparse set)
- Component base class & derived Components
- System base class & user-defined Systems
- System Manager (GdeSystemManager)
4. Generated Bindings (register_types)
5. Demo Scenes (DEMO0 & GDScript version)
6. Build System (SCons + godot-cpp submodule)

- Engine → GDExtension Loader: load plugin at startup.
- Loader → register_types: register native types with Godot.
- Godot Scenes instantiate GdeSystemManager node.
- SystemManager → Entities & Components: create and manage entities, attach components at run time.
- Systems iterate each frame: read/write component data in sparse sets.
- Component events propagate back to Godot API (e.g., transform changes).

c. Architectural patterns & principles:
- ECS: separation of data (Components) from behavior (Systems).
- Data-oriented design: sparse sets for fast component storage & iteration.
- Godot plugin pattern: native nodes registered via GDExtension binding.
- Minimal intrusion: components are Godot Nodes, users write only scenes and scripts.

d. Key technologies & frameworks:
- Godot 4.x, GDExtension API, godot-cpp bindings
- C++, SCons build system, conda/Python for build environment
- .tscn scene files for demo
- XML documentation in doc_classes

##### Detail
- C++ class or group of related classes (entity, component, system, manager).
- How generated files in src/gen feed into the plugin.
- Demo’s two branches (native vs. GDScript) hooking into the same ECS core.
- Don’t omit the build pipeline: SCons + godot-cpp → output .gdextension loaded by Godot.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Binding Layer
    subgraph "Build & Binding" 
        direction TB
        SCons["SConstruct"]:::build
        GodotCPP["godot-cpp (submodule)"]:::build
        RegisterTypes["register_types.cpp/h"]:::build
        GenDoc["doc_data.gen.cpp"]:::build
        SCons -->|build pipeline| GodotCPP
        SCons -->|invoke SCons| RegisterTypes
        RegisterTypes -->|generates binding| GenDoc
    end

    %% Plugin Artifact
    Plugin[".gdextension Plugin"]:::artifact
    SCons -->|compile| Plugin

    %% Godot Engine & Scenes
    subgraph "Godot Side" 
        direction TB
        Engine["Godot Engine / Editor"]:::godot
        Scenes["Demo Scenes (.tscn)"]:::godot
        Engine -->|loads plugin| Plugin
        Plugin -->|registers types| RegisterTypes
        Scenes -->|instantiate| SystemManager
    end

    %% Native ECS Core
    subgraph "ECS Core (C++)"
        direction TB
        EntityMgr["GdeEntity (Entity Manager)"]:::core
        ComponentBase["GdeComponent (Component Base)"]:::core
        SparseSet["Sparse Set Storage"]:::core
        SystemBase["GdeSystem (System Base)"]:::core
        SystemMgr["GdeSystemManager (System Manager)"]:::core
        EntityMgr -->|create/manage| ComponentBase
        ComponentBase -->|store in| SparseSet
        SystemMgr -->|manage| SystemBase
        SystemBase -->|iterate each frame| SparseSet
        SystemMgr -->|creates Entities| EntityMgr
    end

    %% Demo & Tests
    subgraph "Demo & Test Examples"
        direction TB
        DemoNative["demo/DEMO0 (Native ECS)"]:::demo
        DemoGDS["demo/DEMO0-GDS (GDScript)"]:::demo
        DemoTest["demo/TEST"]:::demo
        Scenes --> DemoNative
        Scenes --> DemoGDS
        Scenes --> DemoTest
    end

    %% Documentation
    subgraph "XML Documentation"
        direction TB
        DocEntity["GdeEntity.xml"]:::doc
        DocComponent["GdeComponent.xml"]:::doc
        DocSystem["GdeSystem.xml"]:::doc
        DocSystemMgr["GdeSystemManager.xml"]:::doc
    end

    %% Metadata
    subgraph "Project Metadata"
        direction TB
        README["README.md"]:::meta
        LICENSE["LICENSE"]:::meta
        GitIgnore[".gitignore"]:::meta
        Presets["demo/export_presets.cfg"]:::meta
        ProjectFile["demo/project.godot"]:::meta
    end

    %% Click Events
    click SCons "https://github.com/knightfemale/gdextensionecs/tree/master/SConstruct"
    click GodotCPP "https://github.com/knightfemale/gdextensionecs/tree/master/godot-cpp/"
    click Plugin "https://github.com/knightfemale/gdextensionecs/blob/master/demo/bin/gdexample.gdextension"
    click Plugin "https://github.com/knightfemale/gdextensionecs/blob/master/demo/bin/gdexample.gdextension.uid"
    click EntityMgr "https://github.com/knightfemale/gdextensionecs/blob/master/src/gde_entity.h"
    click EntityMgr "https://github.com/knightfemale/gdextensionecs/blob/master/src/gde_entity.cpp"
    click ComponentBase "https://github.com/knightfemale/gdextensionecs/blob/master/src/gde_component.h"
    click ComponentBase "https://github.com/knightfemale/gdextensionecs/blob/master/src/gde_component.cpp"
    click SparseSet "https://github.com/knightfemale/gdextensionecs/blob/master/src/gde_sparse_set.h"
    click SystemBase "https://github.com/knightfemale/gdextensionecs/blob/master/src/gde_system.h"
    click SystemBase "https://github.com/knightfemale/gdextensionecs/blob/master/src/gde_system.cpp"
    click SystemMgr "https://github.com/knightfemale/gdextensionecs/blob/master/src/gde_system_manager.h"
    click SystemMgr "https://github.com/knightfemale/gdextensionecs/blob/master/src/gde_system_manager.cpp"
    click RegisterTypes "https://github.com/knightfemale/gdextensionecs/blob/master/src/register_types.h"
    click RegisterTypes "https://github.com/knightfemale/gdextensionecs/blob/master/src/register_types.cpp"
    click GenDoc "https://github.com/knightfemale/gdextensionecs/blob/master/src/gen/doc_data.gen.cpp"
    click DemoNative "https://github.com/knightfemale/gdextensionecs/tree/master/demo/DEMO0/"
    click DemoGDS "https://github.com/knightfemale/gdextensionecs/tree/master/demo/DEMO0-GDS/"
    click DemoTest "https://github.com/knightfemale/gdextensionecs/tree/master/demo/TEST/"
    click DocEntity "https://github.com/knightfemale/gdextensionecs/blob/master/doc_classes/GdeEntity.xml"
    click DocComponent "https://github.com/knightfemale/gdextensionecs/blob/master/doc_classes/GdeComponent.xml"
    click DocSystem "https://github.com/knightfemale/gdextensionecs/blob/master/doc_classes/GdeSystem.xml"
    click DocSystemMgr "https://github.com/knightfemale/gdextensionecs/blob/master/doc_classes/GdeSystemManager.xml"
    click README "https://github.com/knightfemale/gdextensionecs/blob/master/README.md"
    click LICENSE "https://github.com/knightfemale/gdextensionecs/tree/master/LICENSE"
    click GitIgnore "https://github.com/knightfemale/gdextensionecs/blob/master/.gitignore"
    click Presets "https://github.com/knightfemale/gdextensionecs/blob/master/demo/export_presets.cfg"
    click ProjectFile "https://github.com/knightfemale/gdextensionecs/blob/master/demo/project.godot"

    %% Styles
    classDef build fill:#ffd6a5,stroke:#333,stroke-width:1px;
    classDef artifact fill:#ffadad,stroke:#333,stroke-width:1px;
    classDef godot fill:#a0c4ff,stroke:#333,stroke-width:1px;
    classDef core fill:#caffbf,stroke:#333,stroke-width:1px;
    classDef demo fill:#d3d3d3,stroke:#333,stroke-width:1px;
    classDef doc fill:#e0e0e0,stroke:#333,stroke-width:1px;
    classDef meta fill:#f1f1f1,stroke:#333,stroke-width:1px;
```
