Files

T

Adolfo 827fdb41c2 feat(LuaGame): Lua interpreter game engine with audio, 17 FPS, 4.5x ball speed

- Embed Lua 5.4.7 source to avoid missing symbols (clearerr, clock, getenv, etc)
- Provide local stubs for missing libc and avoid unexported LVGL cache APIs
- Fix float handling in sys.* bindings (checknumber vs checkinteger)
- Move Lua init and game loop to dedicated 16K FreeRTOS task to avoid GUI 4K stack overflow
- Implement sys API: clear, print (8x8 bitmap font direct FB), rect, circle, line, touch, sfx, tone
- Audio via SfxEngine (SfxId mapping, playNote for tone)
- Ball speed 2 -> 4.5, FPS counter (~17 FPS after direct FB text optimization)
- Supports loading from /sdcard/lua/breakout.lua and embedded fallback
- Verified symbols: 0 missing, builds esp32s3, installs on 192.168.68.107

2026-07-31 12:52:02 -04:00

main

feat(LuaGame): Lua interpreter game engine with audio, 17 FPS, 4.5x ball speed

2026-07-31 12:52:02 -04:00

CMakeLists.txt

feat(LuaGame): Lua interpreter game engine with audio, 17 FPS, 4.5x ball speed

2026-07-31 12:52:02 -04:00

manifest.properties

feat(LuaGame): Lua interpreter game engine with audio, 17 FPS, 4.5x ball speed

2026-07-31 12:52:02 -04:00

README.md

feat(LuaGame): Lua interpreter game engine with audio, 17 FPS, 4.5x ball speed

2026-07-31 12:52:02 -04:00

README.md

LuaGame - Lua Interpreter Game Engine

External ELF app that runs Lua games on Tactility OS (ES3C35P 320x480 tested on 192.168.68.107).

How it works

Embeds Lua 5.4.7 source (no external dependency, avoids missing symbol issues)
Lua init runs in dedicated 16K stack FreeRTOS task to avoid GUI task (4096 bytes) stack overflow
Game framebuffer: 240x240 RGB565 in PSRAM, rendered via LVGL canvas
Sys API (as used in breakout.lua):
- sys.log(msg)
- sys.clear(hexColor)
- sys.print(x,y,text,hexColor) - uses LVGL labels overlay
- sys.rect(x,y,w,h,hexColor,filled)
- sys.circle(x,y,r,hexColor,filled)
- sys.line(x0,y0,x1,y1,hexColor)
- sys.touch() -> pressed, tx, ty (touch coords mapped to 240 game space)
- sys.tone, sys.sfx stubs (logs)
Embedded breakout.lua as fallback, but tries to load from SD in order:
- /sdcard/lua/breakout.lua
- /sdcard/lua/game.lua
- /data/lua/breakout.lua
- /sdcard/breakout.lua
File loading uses PSRAM buffer + luaL_loadbuffer to avoid luaL_loadfile stack issues.

Symbol fixes

Previous attempts hit missing symbols: clearerr, clock, getenv, gmtime, setlocale, setvbuf, tmpfile, tmpnam, ungetc, plus LVGL lv_canvas_get_draw_buf, lv_draw_buf_invalidate_cache, lv_image_cache_drop. Fixed by:

Providing local stubs for missing libc functions
Removing use of unexported LVGL cache APIs, using only lv_canvas_create, lv_canvas_set_buffer, lv_obj_invalidate
Verifying with verify_symbols.py - 0 missing.

Build / Install

cd /Users/adolforeyna/Projects/Tactility/apps
unset PYTHONPATH; unset PYTHONHOME
export IDF_PYTHON_ENV_PATH=/Users/adolforeyna/.espressif/python_env/idf5.3_py3.9_env
source /Users/adolforeyna/esp/esp-idf/export.sh
export TACTILITY_SDK_PATH=/Users/adolforeyna/Projects/Tactility/firmware/release/TactilitySDK
export ESP_IDF_VERSION=5.5
python tactility.py Apps/LuaGame build esp32s3 --local-sdk
curl -X PUT http://192.168.68.107/api/apps/install -F "file=@Apps/LuaGame/build/LuaGame.app"
curl -X POST "http://192.168.68.107/api/apps/run?id=one.tactility.luagame"

Testing

Serial logs: /dev/cu.usbmodem1101 115200
Screenshot: curl -s http://192.168.68.107/api/screenshot -o /tmp/fb.png
Current status: boots, loads /sdcard/lua/breakout.lua (5207 bytes), no stack overflow, renders bricks/ball/paddle, handles float coords for circle.

TODO

Implement proper game selection UI for /sdcard/lua/ directory
Map touch to paddle correctly (currently uses canvas coords)
Implement audio via SfxEngine
Scale canvas to full display or allow dynamic resolution via sys.width/height
Add file browser in-app