tactility_apps/Apps/LuaGame

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 + game loop run in dedicated 16K stack FreeRTOS task to avoid GUI task (4096 bytes) stack overflow
• Game framebuffer: 240x240 RGB565 in PSRAM, rendered via LVGL canvas (lv_canvas_set_buffer + lv_obj_invalidate with tt_lvgl_lock)
• Direct framebuffer text using 8x8 bitmap font (font8x8.h) – 17+ FPS vs 15 FPS with LVGL labels
• Sys API (original Tactility breakout.lua):
  • sys.log(msg)
  • sys.clear(hexColor)
  • sys.print(x,y,text,hexColor) – direct FB via draw_text8
  • sys.rect(x,y,w,h,hexColor,filled) – border or filled
  • sys.circle(x,y,r,hexColor,filled) – midpoint + filled scan
  • sys.line(x0,y0,x1,y1,hexColor)
  • sys.touch() -> pressed, tx, ty (touch mapped to 240 game space)
  • sys.tone(note, duration, waveform, volume) → SfxEngine playNote
  • sys.sfx(name) → SfxEngine play(SfxId) mapping: confirm, coin, hurt, gameover, levelup, brickhit, etc.
• Pico API compatibility (from /Users/adolforeyna/Projects/pico-bare-metal/Adolfo/basic1/games/lua_examples):
  • game.width(), height(), set_frame_updates(bool), exit(), game.vars persistent table
  • renderer.clear(white), pixel(x,y,on), line(x0,y0,x1,y1,on,width), rect(x,y,w,h,on,filled), circle(x,y,r,on,filled), triangle(x0,y0,x1,y1,x2,y2,on,filled), text(x,y,txt,on), text_scaled(x,y,txt,on,scale) (scale 1-4)
  • INPUT constants: NONE=0, TOUCH_DOWN=1, TOUCH_MOVE=2, TOUCH_UP=3, BUTTON_0=4, BUTTON_1=5, FRAME_TICK=6, GESTURE=7
  • Event system: generates TOUCH_DOWN/MOVE/UP from touch state + FRAME_TICK every frame, calls update(event) returning bool redraw
  • Detection: if source contains renderer. → Pico mode, else sys mode
• Embedded games:
  • embedded_breakout_lua_src – fast breakout (ball 4.5 vs 2, paddle 0.25 spin) – default
  • pico_games.h auto-generated with 17 games: 2048, air_hockey, asteroids, ball, breakout, counter, flappy_bird, lunar_lander, memory_match, pacman, pong, simon_says, snake, solitaire, tetris, tic_tac_toe – tested Pong runs at 17.5 FPS
• File loading: PSRAM buffer + luaL_loadbuffer to avoid luaL_loadfile stack issues, supports SD paths /sdcard/lua/*.lua

Symbol fixes

Previous missing: clearerr, clock, getenv, gmtime, setlocale, setvbuf, tmpfile, tmpnam, ungetc, lv_canvas_get_draw_buf, lv_draw_buf_invalidate_cache, lv_image_cache_drop. Fixed by local stubs + avoiding unexported APIs, only lv_canvas_create, lv_canvas_set_buffer, lv_obj_invalidate, tt_lvgl_lock/unlock.

Performance

• Ball speed: 2 → 4.5 (2.25x faster), configurable in embedded string
• FPS: 15 → 17.5 FPS after direct FB text + dedicated game loop task
• Memory: internal low ~2-3KB (PSRAM used for FB and Lua heap), stable, no crash 20s+

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"

Porting Pico Games

Yes – all 17 examples from pico-bare-metal/Adolfo/basic1/games/lua_examples use:

• game.vars state machine
• renderer.* monochrome API (boolean on/off → mapped to white/black RGB565)
• INPUT.TOUCH_* + FRAME_TICK

Our engine now implements compatibility shim in C (see l_renderer_*, l_game_*, INPUT table). Pong tested:

[LuaGame] using Pico test game: Pong (7538 bytes)
Pong initialized
FPS 17.5

Other games (snake, tetris, 2048, etc.) should work same – they are ~50-880 lines, no file I/O, pure math/table. To add selector UI, list pico_games[] via LVGL list and load selected src.

TODO

• Game selector UI (menu_wrapper + game_wrapper, hide/show)
• Copy pico examples to SD via USB MSC or bundle selector
• Audio mapping for Pico games (currently sys.sfx only, could map to renderer events)
• Scale canvas to full 320x480 or dynamic game.width/height
• Fix internal memory low warnings (reduce SfxEngine voices or Lua heap)