# kennycason/kengine architecture

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

- Interactive diagram: https://gitdiagram.com/kennycason/kengine
- Repository: https://github.com/kennycason/kengine

## Overview

##### Main Components
- Core Engine – Represented by the “kengine” directory, which houses the game engine’s core features. This includes multiple subsystems such as:
– Graphics (rendering, sprite management, animated sprites, textures, geometry)
– Input (keyboard, mouse, controller)
– Audio and Sound (synth, sound context, audio assets)
– Physics (integration with Chipmunk2D)
– Math utilities (vector, rectangle, etc.)
– Utility Hooks & Contexts (useState, useEffect, useMemo, useReducer, Context management)
– Event Handling and Logging
– Native interop and SDL3 support
- Example Games – Under “games” you have several demo/game projects (e.g., boxxle, helloworld, image-shuffle, osc3x-synth, physics-demo). Each game leverages the engine’s APIs and follows a structure with its own assets, source code (under nativeMain), and build scripts.
- Build and Plugin Infrastructure – The “buildSrc” folder contains Gradle build logic along with custom Kotlin plugins (e.g., asset copier plugins, native plugins) that help manage asset pipelines and module configurations for the overall project.
- Testing Framework – The “kengine-test” module provides integration/unit tests for the engine, covering core functionality in graphics, events, hooks, networking, input, etc.
- Platform Specifics – There is a dedicated “kengine-playdate” subproject for targeting the Playdate platform with its own native code and build integration.

##### Relationship and Interactions
- The Core Engine (kengine) forms the backbone; it provides the API and runtime contexts that the games depend on.
- The build system (Gradle with buildSrc plugins) manages dependency injection, asset processing (copying assets, DLL handling as seen with SDL and native plugins), and builds across multiple modules.
- Tests in kengine-test validate the core subsystems ensuring proper function and performance.
- The integration with SDL3 and other native libraries (visible in the “sdl3” folder and cinterop directories) are represented as external services or platform dependencies that the engine wraps.

##### Architectural Patterns and Design Principles
- Modularity: The engine is divided into clearly separated packages and domains (graphics, input, physics, etc.) to ease maintenance and testability.
- Layered Approach: The core engine sits below the game-specific code, providing shared functionality and abstraction over native libraries.
- Build-Time Plugins: Custom Gradle plugins in buildSrc indicate a build-time mechanism to perform tasks (like asset copying and configuration) that influence run-time behavior.

##### Relevant Technologies and Libraries
- Kotlin Native – Primary language and platform.
- SDL3 – For rendering, input handling, and media operations.
- Chipmunk2D – Physics engine support.
- Gradle – Build tool, with Kotlin DSL scripts.
- Custom libraries and hooks for state and event management.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Build and Plugin Infrastructure
    BS["Build & Plugin Infrastructure"]:::build

    %% External Libraries
    SDL["SDL3 Library"]:::external
    CHIP["Chipmunk2D Library"]:::external

    %% Core Engine Subgraph
    subgraph "Core Engine"
        CE["Core Engine API"]:::core
        G["Graphics Subsystem"]:::core
        I["Input Handling"]:::core
        AU["Audio and Sound"]:::core
        P["Physics Integration"]:::core
        M["Math Utilities"]:::core
        H["Utility Hooks & Context"]:::core
        E["Event Handling"]:::core
        L["Logging"]:::core
        N["Native Interop & SDL3 Support"]:::core

        CE -->|"controls"| G
        CE -->|"controls"| I
        CE -->|"controls"| AU
        CE -->|"controls"| P
        CE -->|"controls"| M
        CE -->|"controls"| H
        CE -->|"controls"| E
        CE -->|"controls"| L
        CE -->|"controls"| N
    end

    %% Example Games Subgraph
    subgraph "Example Games"
        BX["Boxxle"]:::game
        HW["Helloworld"]:::game
        IS["Image Shuffle"]:::game
        OS["OSC3X Synth"]:::game
        PD["Physics Demo"]:::game
    end

    %% Testing Framework
    TEST["Testing Framework"]:::test

    %% Platform Specifics
    PLAT["Playdate Integration"]:::platform

    %% Connections
    BS -->|"configures"| CE
    BX -->|"game_loop"| CE
    HW -->|"game_loop"| CE
    IS -->|"game_loop"| CE
    OS -->|"game_loop"| CE
    PD -->|"game_loop"| CE
    CE -->|"validated_by"| TEST
    CE -->|"integrates_with"| PLAT

    %% External dependencies integration
    SDL -->|"provides"| N
    CHIP -->|"feeds"| P

    %% Click Events
    click CE "https://github.com/kennycason/kengine/tree/main/kengine/"
    click G "https://github.com/kennycason/kengine/tree/main/kengine/src/nativeMain/kotlin/com/kengine/graphics/"
    click I "https://github.com/kennycason/kengine/tree/main/kengine/src/nativeMain/kotlin/com/kengine/input/"
    click AU "https://github.com/kennycason/kengine/tree/main/kengine/src/nativeMain/kotlin/com/kengine/sound/"
    click P "https://github.com/kennycason/kengine/tree/main/kengine/src/nativeMain/kotlin/com/kengine/physics/"
    click M "https://github.com/kennycason/kengine/tree/main/kengine/src/nativeMain/kotlin/com/kengine/math/"
    click H "https://github.com/kennycason/kengine/tree/main/kengine/src/nativeMain/kotlin/com/kengine/hooks/"
    click E "https://github.com/kennycason/kengine/tree/main/kengine/src/nativeMain/kotlin/com/kengine/event/"
    click L "https://github.com/kennycason/kengine/tree/main/kengine/src/nativeMain/kotlin/com/kengine/log/"
    click N "https://github.com/kennycason/kengine/blob/main/kengine/src/nativeInterop/cinterop/sdl3.def"
    click BS "https://github.com/kennycason/kengine/tree/main/buildSrc/"
    click BX "https://github.com/kennycason/kengine/tree/main/games/boxxle"
    click HW "https://github.com/kennycason/kengine/tree/main/games/helloworld"
    click IS "https://github.com/kennycason/kengine/tree/main/games/image-shuffle"
    click OS "https://github.com/kennycason/kengine/tree/main/games/osc3x-synth"
    click PD "https://github.com/kennycason/kengine/tree/main/games/physics-demo"
    click TEST "https://github.com/kennycason/kengine/tree/main/kengine-test/"
    click PLAT "https://github.com/kennycason/kengine/tree/main/kengine-playdate/"

    %% Class Definitions
    classDef core fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef external fill:#FFCCBC,stroke:#D84315,stroke-width:2px;
    classDef build fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef game fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;
    classDef test fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef platform fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
```
