# goosedes/undertale-fight-engine architecture

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

- Interactive diagram: https://gitdiagram.com/goosedes/undertale-fight-engine
- Repository: https://github.com/goosedes/undertale-fight-engine

## Overview

##### Project type and purpose
- This is a browser-based, Undertale-style 2D combat engine written in JavaScript with a Lua-based modding layer.
- It ships as a static web app (index.html + script.js + style.css + assets) and can be repackaged via Electron or Cordova for desktop/mobile.
- Mods live under the “mods” directory and use a simple file structure (characters, attacks, script files) driven by a Lua VM.

##### File structure
- Top-level:
– index.html / example.html – entry points
– script.js – bootstraps the engine
– style.css – core styles
– assets/ – images, fonts, audio
– src/ – engine modules (character, dialogs, enemies, engine, particle, field, global, etc.)
– mods/ – default mod (“totskiy”), definitions in JSON + Lua scripts (init.lua, update.lua)
- Patterns:
– Modular JS engine (each feature in its own file under src/)
– Plugin architecture for mods using a Lua interpreter implemented in JS (src/engine/lua.js)
– Asset management and game loop live in separate engine modules
- Build/packaging hints: no build scripts here, but README mentions Electron/Cordova wrappers.

##### Insights from README
- Core engine = JS + HTML5 canvas + Web Audio API
- Mod API = Lua scripts loaded via lua.js interpreter
- Example mod demonstrates characters + attack definitions, plus dynamic update hooks

##### Diagramming the architecture
– Browser / Runtime (Chrome, Electron shell, Cordova WebView)
– HTML/CSS layer (index.html + style.css)
– Engine Core (script.js + modules in src/)
· Game Loop Manager
· Renderer (sprite.js, particle.js)
· Input Handler
· Audio Manager (progress_bar, music playback)
· Asset Loader (images, fonts, sounds)
· Dialogue & UI (dialog_text.js, dialogs.js, splash_text.js)
– Lua VM (src/engine/lua.js)
– Mod Loader (reads mods/mods.txt, drives character.json and attack .lua scripts)
– Mod Content (JSON + Lua scripts)
– External Packaging (Electron / Cordova)
b. Component interactions / data flow:
– Browser DOM → index.html loads script.js → instantiates Engine Core
– Engine Core ↔ Asset Loader → fetches assets/…
– Engine Core invokes Lua VM → loads mod definitions → invokes init.lua / update.lua
– Game Loop ticks → Engine Core update → Lua mod hooks → JS rendering via canvas
– User Input → Engine Core → passes control to Lua mod logic if needed
– Audio Manager plays background music / SFX
– Packaging layer provides file system API (Electron/Cordova) for loading local mods
c. Architectural patterns / principles:
– Modular separation (one file per responsibility)
– Plugin architecture: clear core vs. mod boundary
– Event-driven game loop with data-driven content (JSON + Lua)
d. Key technologies/frameworks:
– Vanilla JavaScript modules under src/
– Custom Lua interpreter in JS (fengari-style) in src/engine/lua.js
– HTML5 Canvas for rendering
– Web Audio API for sound
– Electron / Cordova for desktop/mobile packaging

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["Browser Runtime (Chrome/Electron/Cordova)"]:::runtime
    subgraph "HTML/CSS Layer"
        HTML["index.html / example.html"]:::frontend
        CSS["style.css"]:::frontend
    end
    script["script.js (Bootstrapping)"]:::core
    subgraph "Engine Core"
        Global["Global Manager"]:::core
        Loop["Game Loop Manager"]:::core
        Input["Input & Field Handler"]:::core
        Soul["Soul Controller"]:::core
        Character["Character Module"]:::core
        EnemyBase["Enemy Base"]:::core
        EnemyBlaster["Enemy Blaster"]:::core
        RendererSp["Sprite Renderer"]:::core
        Particle["Particle System"]:::core
        Progress["Progress Bar UI"]:::core
        DialogText["Dialog Text Renderer"]:::core
        Dialogs["Dialog Management"]:::core
        Splash["Splash Text"]:::core
        AssetLoader["Asset Loader"]:::asset
        Audio["Audio Manager"]:::core
        LuaVM["Lua VM"]:::mod
        ModLoader["Mod Loader"]:::mod
        ModsContent["Mod Content"]:::mod
        Assets["Assets (images/fonts/audio)"]:::asset
    end
    subgraph "Packaging Layer"
        Electron["Electron / Cordova Wrapper"]:::packaging
    end

    Browser --> HTML
    HTML --> script
    script --> Global
    Global --> Loop
    Loop --> Input
    Loop --> LuaVM
    Loop --> RendererSp
    Loop --> Particle
    Loop --> Progress
    Loop --> DialogText
    Loop --> Dialogs
    Loop --> Splash
    Loop --> Audio
    Global --> AssetLoader
    AssetLoader --> Assets
    LuaVM --> ModLoader
    ModLoader --> ModsContent
    Input --> Global
    Electron --> Browser

    click HTML "https://github.com/goosedes/undertale-fight-engine/blob/main/index.html"
    click CSS "https://github.com/goosedes/undertale-fight-engine/blob/main/style.css"
    click script "https://github.com/goosedes/undertale-fight-engine/blob/main/script.js"
    click Global "https://github.com/goosedes/undertale-fight-engine/blob/main/src/global.js"
    click Character "https://github.com/goosedes/undertale-fight-engine/blob/main/src/character.js"
    click EnemyBase "https://github.com/goosedes/undertale-fight-engine/blob/main/src/enemies/enemy.js"
    click EnemyBlaster "https://github.com/goosedes/undertale-fight-engine/blob/main/src/enemies/blaster.js"
    click RendererSp "https://github.com/goosedes/undertale-fight-engine/blob/main/src/engine/sprite.js"
    click Particle "https://github.com/goosedes/undertale-fight-engine/blob/main/src/particle.js"
    click Progress "https://github.com/goosedes/undertale-fight-engine/blob/main/src/engine/progress_bar.js"
    click DialogText "https://github.com/goosedes/undertale-fight-engine/blob/main/src/dialog_text.js"
    click Dialogs "https://github.com/goosedes/undertale-fight-engine/blob/main/src/dialogs.js"
    click Splash "https://github.com/goosedes/undertale-fight-engine/blob/main/src/splash_text.js"
    click Input "https://github.com/goosedes/undertale-fight-engine/blob/main/src/field.js"
    click Soul "https://github.com/goosedes/undertale-fight-engine/blob/main/src/soul.js"
    click LuaVM "https://github.com/goosedes/undertale-fight-engine/blob/main/src/engine/lua.js"
    click ModLoader "https://github.com/goosedes/undertale-fight-engine/blob/main/mods/mods.txt"
    click ModsContent "https://github.com/goosedes/undertale-fight-engine/tree/main/mods/totskiy/"
    click Assets "https://github.com/goosedes/undertale-fight-engine/tree/main/assets/"

    classDef runtime fill:#ffe4b3,stroke:#cc8400,color:#333;
    classDef frontend fill:#d0e1f9,stroke:#3a7bd5,color:#000;
    classDef core fill:#e8f6e4,stroke:#2a9d8f,color:#000;
    classDef asset fill:#f9e2ae,stroke:#e07a5f,color:#000;
    classDef mod fill:#f3e9d2,stroke:#b56576,color:#000;
    classDef packaging fill:#f0d9ff,stroke:#7b2cbf,color:#000;
```
