1.0

What is Teal++?

Teal++ (.tpp) is a small superset of Lua with Teal's type system, plus a game development framework (GameKit) and a packaging pipeline. It compiles to Teal, which compiles to Lua. It runs on LÖVE.

The pitch from day one:

Write a game in one .tpp file. Run one command. Get a game.

That's now true. This is the first release that actually delivers it.

---

Highlights

One-file install

Linux users get a 1.4 MB self-contained AppImage with everything bundled:

• Lua 5.4 (static, not a dynamic executable)
• The tl compiler (0.24.8)
• The Teal++ CLI, compiler, and GameKit runtime
• Docs

wget https://github.com/Sheldevv/tealpp/releases/download/v1.0/tealpp-1.0-x86_64.AppImage
chmod +x tealpp-1.0-x86_64.AppImage
./tealpp-1.0-x86_64.AppImage love my_game.tpp

No apt. No luarocks. No git clone. No PATH edits. It works on a bare Bazzite, Ubuntu, Fedora, Arch, or Debian install.

Windows users have install.ps1 (PowerShell, one command) or can grab the source and use the AppImage-equivalent Windows .exe produced by tpp package --target windows.

Zero-boilerplate games

Two lines of setup. Everything else is your code.

import gamekit as GameKit

GameKit.app({ title = "My Game", width = 960, height = 640 })

function update(dt: number)
end

function draw()
    GameKit.graphics.circle("fill", 480, 320, 48, "#15f5ff")
end

GameKit.app opens the window, wires LÖVE's lifecycle, dispatches your callbacks, initializes GameKit modules in the right order, and cleans up on exit.

GameKit is a real framework now

Nine modules, all typed, all tested:

Module	What it does
GameKit.app	Zero-boilerplate lifecycle. Dispatches load, update, draw, keypressed, keyreleased, mousepressed, mousereleased, mousemoved, wheelmoved, textinput, resize, focus, quit. Guards against dispatching to Lua builtins. Runs pcall around every callback with traceback reporting.
GameKit.graphics	Hex-color-friendly wrapper over love.graphics. Shapes, lines, text, images, fonts, transforms.
GameKit.assets	Image, font, sound, and music loading with caching. Missing files log a warning and return nil so games degrade gracefully instead of crashing on startup.
GameKit.audio	play, playMusic, stopAll, master volume, fadeIn, fadeOut.
GameKit.errors	traceback, guard, fail, assert. Uniform error reporting across callbacks.
GameKit.Input	Action bindings ("jump" → space, mouse:1). down/pressed/released. Mouse position and buttons.
GameKit.Timer	after, every, cancel, update. Catch-up protection for long pauses.
GameKit.Scene	switch, current, update, draw, reset.
GameKit.GUI + GameKit.LoveGUI	Labels, buttons, checkboxes, radios, text inputs, sliders, dropdowns, progress bars. Containers, scrolling, tooltips, keyboard focus, runtime themes.
GameKit.Camera	World/screen coordinate conversion, rotation, cursor-centered zoom, LÖVE transform helpers.
GameKit.Window	Window size, fullscreen, borderless, VSync, minimum size, resize callbacks.
GameKit.Dock	Dockable panel manager for editors and tools.

GUI auto-wires. Write GameKit.app({ gui = ui }) and your UI gets mouse input, keyboard focus, wheel scrolling, text input, focus loss handling, and rendering — with no manual attachment.

Packaging pipeline

tpp bundle my_game.tpp                                   # → my_game.love + launcher
tpp package my_game.tpp --target linux                   # → my_game-linux.tar.gz
tpp package my_game.tpp --target linux --love-bin love   # → ships LÖVE too
tpp package my_game.tpp --target windows --love-bin ~/love-win64  # → fused .exe + DLLs
tpp package my_game.tpp --target macos --love-bin ~/love.app      # → unsigned .app

.love files are portable across Linux, macOS, and Windows. Users need only LÖVE installed. If you bundle the runtime (--love-bin), they need nothing.

The pipeline is documented in PACKAGING.md, including macOS codesigning and notarization.

Type-checked throughout

Every GameKit module ships with Teal declarations in gamekit.d.tl. tl check passes with 0 errors on every shipped example: hello, gui, showcase, neon_survivor.

You write .tpp files, and the compiler — using Teal under the hood — catches type errors before the game runs, without giving up Lua's flexibility.

---

Shipped examples

Path	What it is
examples/hello/main.tpp	10 lines. Window + circle.
examples/gui/main.tpp	Zero-wiring GUI demo with buttons, checkbox, live counter, and animated canvas.
examples/showcase/main.tpp	Movement (WASD), action-bound input, timers, GUI, audio playback, sprite rendering, mouse position tracking.
examples/neon_survivor/main.tpp	Full arcade survival game. Auto-fire targeting, waves, particles, difficulty dropdown, autofire toggle, manual-fire override.
examples/tealpp/main.tpp	Starter template.
examples/love/	Direct LÖVE demos (no .tpp compile step) for testing GameKit standalone.

All examples compile clean with tl check and run on LÖVE 11.x.

---

Install

Linux — one file

wget https://github.com/Sheldevv/tealpp/releases/download/v1.0/tealpp-1.0-x86_64.AppImage
chmod +x tealpp-1.0-x86_64.AppImage
./tealpp-1.0-x86_64.AppImage love my_game.tpp

Requires LÖVE installed separately (unless you bundle it in your game's build). Everything else — Lua, tl, the compiler, GameKit — is in the AppImage.

Linux / macOS — from source

git clone https://github.com/Sheldevv/tealpp.git
cd tealpp
./install.sh

Installs to ~/.local/tpp and puts tpp in ~/.local/bin. Requires lua and git. Warns on missing tl, zip, and love with install hints.

Windows

Set-ExecutionPolicy -Scope Process Bypass -Force
.\install.ps1

Installs to %LOCALAPPDATA%\tpp, adds tpp.cmd to %LOCALAPPDATA%\Microsoft\WindowsApps (already on PATH). Requires git and lua. Warns on missing tl, zip, love.

Windows — from a .tpp source without installing Teal++

Install the AppImage's Windows equivalent (see PACKAGING.md), or run tpp package --target windows on any Linux/macOS machine to produce a Windows-ready .exe that a user double-clicks.

---

Compatibility

Breaking changes

None. This is 1.0 of a project that has been developed iteratively through this session, but no released version exists before v1.0. All internal APIs are v1.0 APIs.

Known limitations

• GameKit.app({...}) config is a plain table, not a typed record. Teal's optional-field syntax in local record fails to parse on some Teal versions. Runtime validation covers defaults; compile-time checking of config keys is not available. This is a Teal compiler constraint, not a Teal++ choice.
• tpp package --target windows and --target macos require the target runtime. No cross-compilation. Run from Linux with the Windows LÖVE zip to produce a Windows .exe; run on macOS with love.app to produce a .app. PACKAGING.md documents this.
• macOS .app bundles are unsigned. The pipeline produces the .app; codesigning and notarization are user steps documented in PACKAGING.md.
• tpp bundle and tpp package require POSIX tools. zip, tar, cp, chmod, cat for fusion. Windows native support requires WSL or Git Bash. This doesn't affect shipped games — only the packaging step on Windows.
• No love.joystick*, love.gamepad*, or love.touch* dispatch. Keyboard and mouse are fully wired. Controller and touch support is future work.
• GameKit.assets does not pre-validate file format. A corrupt PNG logs a load error and returns nil, but won't tell you why it's corrupt.
• No save-file system. Games write their own; GameKit provides no serialization layer.

Compiler quirks documented

If you use Teal++ and hit these, they're known:

1. Optional fields in records. field?: type and field: type? both fail inside local record. Only function parameter optionality (param?: type in function types) works. Use any for config-style tables.
2. integer vs number. local n = 0 infers integer. Assigning n = n + dt (number) errors. Use 0.0 for the initializer.
3. Union narrowing after nil guard. local x: T | nil = f(); if not x then return end; x.field sometimes fails to narrow. Cast explicitly: local y = x as T; y.field.
4. Staged GameKit copies. tpp love examples/x/main.tpp copies gamekit/ into examples/x/ only if it isn't already there. After editing gamekit/, run rm -rf examples/*/gamekit examples/*/gamekit.d.tl before rebuilding.

---

Docs

File	For
README.md	Overview and CLI reference
GETTING-STARTED.md	Tutorial: hello world → animated game → GUI → assets → audio
PACKAGING.md	Linux, Windows, macOS packaging; codesigning; troubleshooting
GAMEKIT-README.md	GameKit module reference
gamekit.d.tl	Every public API signature
examples/*/main.tpp	Runnable examples, from 10 lines to a full game

---

Test suite

tpp test

Runs 60 assertions across six test files, plus a packaging smoke test:

• 6 Teal++ program/import checks
• 9 GameKit core tests (scene, input, timer)
• 26 GUI tests (widgets, layout, focus, themes, popups, scrolling)
• 7 Window management tests
• 6 Dock panel tests
• 5 Camera math tests
• 12 GameKit.app tests (lifecycle, dispatch, error isolation, GUI auto-attach, wheelmoved, textinput, raw-love access)
• 1 packaging smoke test (`bund...