Current Limitations

The Naucto Lua API is focused and growing. Here are the current limitations to be aware of when designing your games, along with recommended workarounds.

No collision queries

There are no built-in collision detection functions. You must implement overlap checks yourself. Use mget() and fget() when you want those checks to be driven by the tilemap and sprite flags.

Workaround: Use a simple AABB (axis-aligned bounding box) overlap function:

function overlaps(ax, ay, aw, ah, bx, by, bw, bh)
  return ax < bx + bw
     and ax + aw > bx
     and ay < by + bh
     and ay + ah > by
end

No delta time

The engine does not expose a delta time value. The game loop runs at a fixed frame rate that targets 60 frames per second, so movement values are per-frame rather than per-second.

Workaround: Tune your movement speeds, gravity, and jump forces as per-frame values. The platformer tutorial demonstrates this approach with values like speed = 1.8 and gravity = 0.30.

Instruction limit

To protect the browser from infinite loops, each call into your script – _init(), and every per-frame _update() and _draw() invocation – may execute at most roughly 10 million Lua instructions. Exceeding the budget raises a runtime error:

execution aborted: possible infinite loop or recursion

The budget is generous: normal game logic never gets close. It typically triggers on a while loop whose exit condition can never become true.

Workaround: None needed for correct code. If a legitimate computation is that heavy, spread it across frames (do a slice of the work per _update()).

Runtime errors stop the game

An uncaught runtime error in _init(), _update(), or _draw() does not just print to the output panel – it stops the game loop. The screen freezes on the last rendered frame until you fix the error and re-run. This includes the instruction-limit abort above, invalid clear() palette indexes, and out-of-bounds mget() / fget() calls.

What works well today

Despite these limitations, the current API supports a wide range of games:

  • Sprite-based characters with animation

  • Arcade-style movement

  • Basic platformers

  • Top-down adventure games

  • Puzzle games

  • Simple action games

  • HUDs and debug overlays with rectangles and lines

  • Palette swap effects for visual variety

  • Tilemap-driven logic with mget() and sprite flags

  • Music playback from Sound Editor slots