How goosedes/undertale-fight-engine works
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