index.md

layout	default
title	lua-objc documentation

lua-objc

Build native macOS and iOS interfaces with SwiftUI-style declarative Lua, AppKit/UIKit controls, and no compile cycle for every UI change.

Start here

• Agent quickstart: the shortest path from an idea to a tested app.
• Application architecture: small-app MVC, feature composition, etlua rendering, and native lifetimes.
• XML syntax: the supported etlua/XML tags and attributes.
• Apple UI checklist: design and accessibility rules for polished native apps.
• Delight vs coverage: which interaction-gallery patterns Adventure Arena may use, and which stay out of the framework.
• Stocks app example: a complete Model/Controller/views example with a screenshot.
• Weather app example: async HTTP, loading, selection, and normalized API data.
• Project reference: detailed Lua API, bridge behavior, and layout contracts.
• Component reference: one page per widget, generated from --- docblocks in Lua sources (start with Button, Text, VStack).
• SceneKit scenes and games: <SceneView> scene graphs in etlua, per-frame poses, and how to structure a game (Coin Quest).
• Table behavior: list sizing, styles, columns, and loading state.
• iOS host and hot reload: iPhone Simulator host, UIKit coverage, streamed Lua/assets, and in-process reload (the app does not quit).
• Swift/SwiftUI pain points: what developers complain about in Xcode/SwiftUI, and which of those gaps lua-objc should close.

The core loop

1. Describe the view in Lua or an etlua template.
2. Run it: ./lua-objc apps/<app> on macOS, or make ios-run ARGS=apps/<app> on the iPhone Simulator. Framework demos live under demo/; test harness apps live under test/.
3. On iOS, save a Lua/etlua/asset file; the running host reloads in place (no quit, no rebuild).
4. Exercise the behavior with a headless Lua test.
5. Inspect a screenshot or native layout dump when the change is visual.

The runtime uses real AppKit/UIKit controls. Use semantic system colors, SF Symbols, native lists, native toolbars, and platform-owned containers instead of simulating them with text or custom drawing.

Repository layout

apps/<app>/     product application
demo/<name>/     runnable framework demo
test/<name>/     runnable test harness
  init.lua        entry point; returns the controller class
  Model.lua       pure data and domain logic
  Controller.lua  screen coordination, actions, and template wiring
  views/          etlua/XML templates

Build and test

make
make test
./lua-objc --screenshot=/tmp/app.png apps/stocks/init.lua
./lua-objc --dump-layout=/tmp/layout.xml apps/stocks/init.lua

Contributors are very welcome. See the repository README for contribution paths and open an issue or pull request when you find a missing widget, unclear API, design improvement, or documentation gap.