# Lua Compatibility

Rules and constraints for all Lua code in Solar2D.

## Runtime Version

The engine embeds a modified Lua 5.1 runtime whose source reports **Lua 5.1.5**, retained in the legacy `external/lua-5.1.3/` directory. Solar2D adds a custom require/loader chain, Corona plugin loading, and runtime-managed Lua state lifecycle.

## Hard Requirement: Lua 5.1 Compatibility

All Lua code **must** use the Lua 5.1 language and API. Do not use features from Lua 5.2 or later.

### Features NOT available (5.2+):

| Feature | Introduced | Alternative in 5.1 |
|---------|-----------|-------------------|
| `goto` and `::label::` | 5.2 | Use conditionals or restructure logic |
| `_ENV` table | 5.2 | Use `setfenv`/`getfenv` (but see deprecation note below) |
| `\x` hex escapes in strings | 5.2 | Use `string.char(0xNN)` |
| Bitwise operators (`&`, `\|`, `~`, `<<`, `>>`) | 5.3 | Use a Lua 5.1-compatible dependency verified for the target, or an existing project helper |
| `table.pack` / `table.unpack` | 5.2 | Use global `unpack`; use `select('#', ...)` when the value count matters |
| `__gc` metamethod on tables | 5.2 | Use full userdata or the subsystem's existing ownership pattern |
| `table.move` | 5.3 | Implement manually with loops |
| Integer division `//` | 5.3 | Choose a Lua 5.1-compatible implementation that preserves the required rounding and error semantics |
| `utf8` library | 5.3 | Use a supported dependency verified for the target |
| `load()` with string argument | 5.2 behavior | Use `loadstring()` in 5.1 |

## Forward Compatibility Guidelines

While Lua 5.1 is the hard requirement, prefer patterns that ease future migration:

### Do:
- **Return-table module pattern**: `local M = {} ... return M` instead of `module()`
- **Use `require` return values**: `local json = require("json")` instead of relying on global registration
- **Explicit `unpack`**: Use `unpack(t)` — it's a global in 5.1, moved to `table.unpack` in 5.2

### Avoid when practical:
- **`module()` function**: Valid legacy code in 5.1, but avoid it in new modules; do not migrate existing modules mechanically
- **`setfenv`/`getfenv`**: Works in 5.1 but removed in 5.2+. Use sparingly and only where necessary
- **`arg` global in varargs**: This source enables `LUA_COMPAT_VARARG`, but new code should use `{...}` or `select()` instead

String method syntax such as `s:find()` is supported; match the surrounding style.

## Solar2D-Specific Lua Modifications

Solar2D modifies the Lua runtime in ways that may differ from stock Lua 5.1:
- Custom require/loader chain for Corona plugins and asset loading
- Runtime-managed Lua state lifecycle (tied to `Rtt_Runtime`)
- Corona-specific Lua libraries bootstrapped from `librtt/Corona/*.lua`
- **Native Objective-C exception handling**: Apple targets that define `LUA_USE_OBJC_EXCEPTIONS` compile `external/lua-5.1.3/src/lobjectivec_exceptions.m`. The implementation throws a static `NSString` for ordinary Lua errors and translates caught Objective-C exceptions—and C++ exceptions when compiled as Objective-C++—into Lua error status and stack values. Verify target compile flags and error behavior; do not infer performance beyond measured evidence.

When modifying Lua-related engine code, verify behavior against the source in `external/lua-5.1.3/` and standard Lua 5.1 documentation.

## Reference Documentation

- **Lua 5.1 Reference Manual**: https://www.lua.org/manual/5.1/
- **Solar2D API docs**: https://docs.coronalabs.com/ (may not be 1:1 with source code)
- **Solar2D docs source**: https://github.com/coronalabs/corona-docs
- **Lua source**: modified Lua 5.1.5 source in the legacy `external/lua-5.1.3/` directory