@maccesar/titools 4.7.0 → 4.8.0

package/README.md

@@ -177,7 +177,7 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
 | ti-expert    | Architecture and implementation     | Starting point for most tasks           |
 | purgetss     | Utility-first styling               | UI styling and animations               |
 | ti-ui        | UI/UX patterns                      | Complex layouts, ListViews, platform UI |
-| ti-game      | 2D games with the `ti.game` module  | Sprites, physics, collisions, particles, camera |
+| ti-game      | 2D games with the `ti.game` module  | Sprites, physics, collisions, text HUDs, particles, camera |
 | ti-api       | Complete Titanium API reference     | Looking up properties, methods, events  |
 | ti-guides    | SDK fundamentals                    | tiapp.xml, Hyperloop, distribution, JDK/Xcode compatibility, release notes |
 | ti-howtos    | Native feature integration          | Location, push, media, platform APIs    |
@@ -186,7 +186,7 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
 
 Notes:
 - The first four (`ti-expert`, `purgetss`, `ti-ui`, `ti-game`) are opinionated workflow skills reflecting TiTools' Titanium conventions.
-- `ti-game` documents the `ti.game` native module (2D sprite engine on OpenGL ES 2.0, Android and iOS). Its API reference was verified against the module source; it applies to Alloy and Classic projects alike and does not depend on PurgeTSS.
+- `ti-game` documents the `ti.game` native module (2D sprite engine on OpenGL ES 2.0, Android and iOS). Its API reference was verified against the module source and tracks upstream `main` (the module ships features ahead of its manifest version); it applies to Alloy and Classic projects alike and does not depend on PurgeTSS.
 - The latter five are documentation-mirror skills sourced from the official Titanium SDK docs (`tidev/titanium-docs`) and audited against them via the internal `titools-skill-auditor`.
 - `purgetss` reference files are audited against the official PurgeTSS documentation, but its workflow conventions are opinionated.
 
@@ -435,7 +435,8 @@ When it activates:
 - `tiapp.xml` declares `ti.game`, or any file calls `require('ti.game')`
 - Sprites, sprite sheets, TexturePacker atlases, frame animations, native tweens
 - Physics: gravity and velocity, solid platforms, one-way floors, bouncing, the arcade car model, Newtonian thrust
-- Collision groups, invisible trigger zones, hitbox tuning
+- Collision groups, invisible trigger zones, enter/exit events, swept AABB for fast bullets, hitbox tuning
+- Bitmap-font text sprites and screen-fixed HUDs inside the scene
 - Particle emitters, Verlet ropes, camera follow/zoom/shake/effects, low-latency sound
 - Drag & drop, pinch, rotate, multitouch controls
 
@@ -446,6 +447,7 @@ Example prompts:
 "Add a camera that follows the player with a dead zone."
 "How do I make a top-down racer that drifts?"
 "Why does my game stutter when I move sprites from setInterval?"
+"Add a score HUD that stays put while the camera follows the player."
 ```
 
 Key rules:
@@ -454,7 +456,7 @@ Key rules:
 - `solidWith` blocks, `collidesWith` reports — they are independent
 - A sprite with size but no sheet is an invisible trigger (scores, goals, walls)
 - Add a whole level with one `gameView.add([...])` call
-- There is no text in the engine: HUDs are `Ti.UI.Label` overlays
+- HUDs are `Game.createText` sprites with `screenFixed: true`, not `Ti.UI.Label` overlays
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "description": "Titanium SDK skills and agents for AI coding assistants (Claude Code, Gemini CLI, Codex CLI)",
   "main": "lib/index.js",
   "type": "module",

package/skills/ti-game/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: ti-game
-description: "Use when building or reviewing 2D games with the ti.game module for Titanium SDK (Android and iOS) — sprites, sprite sheets, frame animations, tweens, physics (gravity, solid platforms, carMode drifting, thrust), collision groups, particles, Verlet ropes, camera follow/zoom/shake, low-latency sound, drag & drop, multitouch. AUTO-DETECT: if tiapp.xml declares ti.game or any file calls require('ti.game'), invoke BEFORE writing ANY game code. Also trigger on: game, juego, sprite, spritesheet, platformer, endless runner, top-down, shooter, racer, flappy, breakout, rhythm game, card game, puzzle, collision, hitbox, parallax, particles, game loop, 60 fps, GameView. ti.game is NOT Phaser, Godot or Box2D: you never write a game loop, never move a sprite from setInterval, and several familiar features (bitmap text, tilemap layer, sprite parenting, raycast) do not exist yet — check references/roadmap.md before inventing an API."
+description: "Use when building or reviewing 2D games with the ti.game module for Titanium SDK (Android and iOS) — sprites, sprite sheets, frame animations, tweens, physics (gravity, solid platforms, carMode drifting, thrust), collision groups, trigger zones, swept AABB, bitmap-font text and HUDs, particles, Verlet ropes, camera follow/zoom/shake, low-latency sound, drag & drop, multitouch. AUTO-DETECT: if tiapp.xml declares ti.game or any file calls require('ti.game'), invoke BEFORE writing ANY game code. Also trigger on: game, juego, sprite, spritesheet, platformer, endless runner, top-down, shooter, racer, flappy, breakout, rhythm game, card game, puzzle, collision, hitbox, parallax, particles, HUD, score, game loop, 60 fps, GameView. ti.game is NOT Phaser, Godot or Box2D: you never write a game loop, never move a sprite from setInterval, and several familiar features (tilemap layer, sprite parenting, raycast, joystick) do not exist yet — check references/roadmap.md before inventing an API."
 argument-hint: "[genre or feature]"
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash(node *)
 ---
 
 # ti.game — 2D game engine for Titanium SDK
 
-`ti.game` is a native OpenGL ES 2.0 sprite engine exposed to JavaScript, written and maintained by **Michael Gangolf (m1ga)** — upstream is https://github.com/m1ga/ti.game. This skill was written against version 0.3.0 as it stands in the `macCesar/ti.game` contribution fork; when upstream and the fork disagree, upstream wins. Same JS API on Android and iOS — the iOS side is a class-per-class Obj-C twin of the Android engine.
+`ti.game` is a native OpenGL ES 2.0 sprite engine exposed to JavaScript, written and maintained by **Michael Gangolf (m1ga)** — upstream is https://github.com/m1ga/ti.game. This skill tracks upstream `main` as of **2026-08-18** — the manifest still reads `0.3.0`, but the text engine, `screenFixed`, `swept` collisions and `collisionend` landed after it, so a version number alone will not tell you what a checkout has. When upstream and any fork disagree, upstream wins. Same JS API on Android and iOS — the iOS side is a class-per-class Obj-C twin of the Android engine.
 
 Works in **both Classic and Alloy** projects. Nothing here depends on PurgeTSS.
 
@@ -31,6 +31,9 @@ The practical consequence, and the single biggest mistake to avoid:
 | Drag a sprite with the finger | `touchmove` handler | `draggable: true` |
 | Scrolling background | timer repositioning copies | `wrapX` / `wrapShift` + `velocityX` |
 | Camera that follows the player | timer writing `cameraX` | `gameView.follow(sprite, options)` |
+| A score, a title, a label | `Ti.UI.Label` overlays | `Game.createText({ text, screenFixed: true })` |
+| A bullet fast enough to skip past a thin wall | shrinking the time step | `swept: true` on the bullet |
+| To know the player *left* a zone | polling on a timer | the `collisionend` event |
 | Smoke, sparks, explosions | pooled sprites in JS | `Game.createEmitter(...)` |
 | A swinging chain or cape | verlet solver in JS | `Game.createRope(...)` |
 | Slow motion or a pause that still draws | pausing your own timers | `gameView.timeScale = 0.5` / `0` |
@@ -117,10 +120,14 @@ Gravity is per sprite, not global — set it on each body that should fall. A sp
 ## Block versus react: `solidWith` and `collidesWith` are independent
 
 - `solidWith: ['ground']` **blocks** movement against sprites tagged `collisionGroup: 'ground'`. The engine pushes the sprite out along the axis of least penetration, sets read-only `onGround` and fires `land`.
-- `collidesWith: ['coin', 'enemy']` **reports** overlap. Fires `collision` once per overlap-enter (payload `group`, `other`, `x`, `y`), re-arming after separation. Nothing is blocked.
+- `collidesWith: ['coin', 'enemy']` **reports** overlap. Fires `collision` once per overlap-enter and `collisionend` once on separation (both carry `group`, `other`, `x`, `y`). Nothing is blocked.
 
 A sprite can use both — a player that stands on platforms (`solidWith`) and dies on spikes (`collidesWith`).
 
+The enter/exit pair is the trigger lifecycle other engines call `OnTriggerEnter`/`Exit`: water that tints the hero while he is in it, a pressure plate holding a door open exactly while something rests on it. Removing or hiding the partner mid-contact also counts as separation, so a despawned object still closes its door. There is deliberately **no** per-frame "stay" event — keep that state in JS.
+
+A fast mover can slip through a thin target between frames: it never overlaps on any single frame, so the discrete test misses. `swept: true` on the *mover* tests its movement as a path — `collision` fires for whatever the path crossed, and `solidWith` walls stop it at the impact point instead of letting it teleport through.
+
 **A sprite with `width`/`height` but no `sheet` renders nothing and works as an invisible trigger.** Score zones, goals, checkpoints, ceilings, kill floors and walls are all built this way in the official demos. This is the idiomatic way to add logic to a scene without art.
 
 Tune fairness with `hitboxScale` (art rarely fills its frame; slightly small hitboxes feel better) and `hitboxShape: 'circle'` for balls and rocks — circles also resolve against solids along the contact normal, so they bounce off corners diagonally instead of like a box. Turn on `debug: true` per sprite, or on the GameView for everything, to see green collision AABBs, blue touch bounds and the orange anchor dot.
@@ -128,6 +135,7 @@ Tune fairness with `hitboxScale` (art rarely fills its frame; slightly small hit
 ## Performance rules that actually matter
 
 - **One texture = one draw call.** The batcher accumulates up to 1000 quads and flushes on texture switch. A scene whose sprites all share one sheet renders in a single draw call regardless of sprite count. Pack art into as few sheets as possible; reuse one white particle texture and tint it at runtime.
+- **Know what else breaks the batch**, since none of it is visible on screen: every `'normal'` ↔ `'add'` transition in draw order flushes (group additive sprites into their own `zIndex` band so it happens twice a frame, not constantly); each glowing sprite costs 2 extra draw calls per frame, plus 2 more while a `flash()` runs; ropes, skid marks and debug overlays always draw with normal blending, so interleaving them with additive content flushes too.
 - **Bulk-add a level.** `gameView.add([spriteA, spriteB, emitter, rope])` crosses the bridge once and commits under one scene lock. Collect a level's objects in an array and add them in one call; `add(object)` still works for single objects.
 - **Keep collision group lists targeted.** Cost is O(colliders × candidates) per frame. A bullet checking `['asteroid']` tests 5 sprites, not the whole scene.
 - **Pool, don't create.** Bullets, notes, obstacles and enemies are created once (usually 3–10 of them), then recycled by setting `visible = false` and zeroing velocity. Creating sprites mid-game costs a bridge hop and a scene lock.
@@ -135,9 +143,19 @@ Tune fairness with `hitboxScale` (art rarely fills its frame; slightly small hit
 - **`maxFps: 60`** on the GameView keeps 120 Hz ProMotion displays from doubling render work. `0` (default) follows the display refresh rate.
 - **Judge performance on device.** The iOS Simulator's OpenGL translation layer is disproportionately slow and renders at a 1x drawable; real devices keep native screen scale and run far smoother.
 
-## There is no text in the engine
+## Text is a sprite
+
+Text draws **inside** the scene: `Game.createText({ text: 'SCORE 0' })` returns a sprite made of glyph quads, so it z-sorts, tweens, tints, flashes, glows, wobbles on `idleAnimation` and takes `tap` events like any other sprite — a text button needs no overlay view. With no `font` it uses a pixel font embedded in the module (nothing to ship); `Game.createFont({...})` loads a BMFont/AngelCode atlas or a monospace grid image. There is no font size — scale the sprite, with integer values for crisp pixels.
+
+```javascript
+const score = Game.createText({ text: 'SCORE 0', screenFixed: true, x: W / 2, y: H * 0.08, scale: 3, zIndex: 100 });
+gameView.add(score);
+score.text = 'SCORE 10';   // re-lays out natively
+```
+
+`screenFixed: true` works on **any** sprite: `x`/`y` become surface coordinates and camera position, zoom and shake are ignored, while touch still maps back. That is the HUD pattern — the score stays put while the camera follows the player. Without it, text is world-space and scrolls past like scenery (signposts, floating damage numbers).
 
-The engine draws sprites, particles and ropes — **not text**. HUDs, scores and labels are ordinary `Ti.UI.Label` views overlaid on the window, on top of the GameView. That is how every official demo does it. Consequences worth knowing before designing a HUD: overlaid Titanium views are screen-fixed, so they do not scroll with the camera, do not z-sort against sprites and cannot be tweened by the engine. Bitmap-font text sprites are planned but do not exist — see [roadmap.md](references/roadmap.md).
+Overlaid `Ti.UI.Label` views still work and are still right for anything the engine cannot draw: native inputs, system fonts, accented text the built-in font lacks, scrollable menus. Just do not reach for them for a score any more.
 
 Standard Titanium touch events do not reach the GameView, but ordinary Titanium buttons and views layered on top work normally, and sibling views receive simultaneous pointers — which is how the demos build multitouch d-pads (hold ▶ and press jump at the same time). One caveat from the demos: Android's `touchFeedback` ripple cannot animate over this canvas and spams `RippleDrawable` errors, so on-screen buttons set their own `backgroundColor` on `touchstart`/`touchend`.
 
@@ -175,5 +193,6 @@ Read the one that matches the task instead of guessing — the API surface below
 5. Is `hitboxScale` set on sprites whose art does not fill the frame?
 6. Do triggers (scores, goals, kill zones) use sheet-less sprites instead of visible art?
 7. Is every `createSound`, `setInterval` and `setTimeout` stopped when the window closes?
-8. Is the HUD a `Ti.UI.Label` overlay, not an imagined engine text API?
-9. Are you using an API that actually exists? Anything involving text, tilemaps, sprite parenting, raycasting, joysticks or `blend: 'multiply'` — check [roadmap.md](references/roadmap.md) first.
+8. Is the HUD `Game.createText` with `screenFixed: true`, rather than a stack of overlaid labels?
+9. Does anything travel far enough per frame to tunnel? Give it `swept: true`.
+10. Are you using an API that actually exists? Anything involving tilemaps, sprite parenting, raycasting, joysticks or `blend: 'multiply'` — check [roadmap.md](references/roadmap.md) first.

package/skills/ti-game/references/api.md

@@ -1,6 +1,6 @@
 # ti.game API reference
 
-Complete JS surface of `ti.game` 0.3.0, verified against the module source (`android/src/ti/game/*.java` and `engine/*.java`, mirrored by `ios/Classes/TG*`). Defaults come from the engine fields, not from prose.
+Complete JS surface of `ti.game` as of upstream `main` on 2026-08-18, verified against the module source (`android/src/ti/game/*.java` and `engine/*.java`, mirrored by `ios/Classes/TG*`). Defaults come from the engine fields, not from prose. The manifest still reads `0.3.0`; the text engine (`createFont`/`createText`), `screenFixed`, `swept` and `collisionend` landed after it and are not in any numbered release yet.
 
 Every property listed is **live**: reading returns the current native value, even mid-drag or mid-tween. Every property can also be passed to its `create*` factory. All durations crossing the JS boundary are **milliseconds** (the engine converts to seconds internally).
 
@@ -10,6 +10,8 @@ Every property listed is **live**: reading returns the current native value, eve
 - [GameView](#gameview)
 - [SpriteSheet](#spritesheet)
 - [Sprite](#sprite)
+- [Font](#font)
+- [Text](#text)
 - [Sound](#sound)
 - [Emitter](#emitter)
 - [Rope](#rope)
@@ -27,6 +29,8 @@ const Game = require('ti.game');
 | `Game.createGameView(options)` | GameView — the canvas, a Titanium view |
 | `Game.createSpriteSheet(options)` | SpriteSheet — a texture cut into frames |
 | `Game.createSprite(options)` | Sprite |
+| `Game.createFont(options)` | Font — a bitmap font for text sprites |
+| `Game.createText(options)` | Text — a sprite that draws a string |
 | `Game.createSound(options)` | Sound |
 | `Game.createEmitter(options)` | Emitter — particle system |
 | `Game.createRope(options)` | Rope — Verlet chain |
@@ -112,6 +116,7 @@ Textures upload to the GPU lazily on first use, from the render thread, and are
 | `zIndex` | `0` | Draw order |
 | `ySort` | `false` | Within the same `zIndex`, sort by the sprite's **bottom edge** — top-down depth (walk behind a tree, in front of it below) |
 | `flipX`, `flipY` | `false` | Mirror the drawn frame only. Position, anchor, physics and hit testing are untouched |
+| `screenFixed` | `false` | `x`/`y` become **surface** coordinates and the sprite ignores camera position, zoom and shake — HUDs, on-screen buttons, overlays. Touch is mapped back automatically, so `tap` still works. Works on any sprite, not only text |
 | `pixelSnap` | `false` | Rounds only the rendered anchor to a framebuffer pixel after camera position and zoom. Physics and live `x`/`y` stay subpixel floats. Combine with `smoothing: false` when a moving pixel-art sprite must keep a stable texel phase |
 
 ### Sheet and animation
@@ -145,7 +150,7 @@ Hit-testing runs against the transformed shape (rotation and scale included), to
 | --- | --- | --- |
 | `velocityX`, `velocityY` | `0` | px/s |
 | `gravity` | `0` | px/s², added to `velocityY`. Per sprite — there is no global gravity |
-| `maxSpeed` | `500` | px/s cap |
+| `maxSpeed` | `500` | px/s cap applied **only** to `thrust` acceleration and the `carMode` model. Writing `velocityX`/`velocityY` directly is never clamped |
 | `angularVelocity` | `0` | deg/s |
 | `thrust` | `0` | px/s² along the current heading (Newtonian flight) |
 | `wrapAround` | `false` | Re-enter from the opposite screen edge (Asteroids) |
@@ -169,6 +174,7 @@ Hit-testing runs against the transformed shape (rotation and scale included), to
 | `collidesWith` | — | Array of groups this sprite reports overlaps with |
 | `hitboxScale` | `1` | Shrinks the collision box around the anchor |
 | `hitboxShape` | `'rect'` | `'circle'` — radius = half the smaller drawn side × `hitboxScale`. Circles resolve against solids along the contact normal (corner bounces) and get a round touch area |
+| `swept` | `false` | Test this sprite's movement as a **path** (swept AABB), not just at the end position, so a fast mover cannot tunnel between frames. Applies to both `collidesWith` events and `solidWith` blocking (the sprite is clamped to the impact point, then resolved by the normal static pass). Circle hitboxes sweep as their bounding box. Set it on the *mover* — the bullet, not the wall |
 | `debug` | `false` | Draw this sprite's shapes: green = collision AABB, blue = touch bounds, orange dot = anchor |
 
 ### Car (`carMode`)
@@ -206,7 +212,7 @@ Every sprite gets its own phase, and the wobble unwinds exactly when disabled. T
 | --- | --- | --- |
 | `tintColor` | — | Multiplies the frame's colors (team colors, day/night, damage states). `null` or `'#fff'` = unchanged. Multiplicative, so it can only darken |
 | `glowColor` | — | Tinted, blurred silhouette drawn behind the sprite by a shader pass |
-| `glowBlur` | `0` | Blur radius in px; `0` = off |
+| `glowBlur` | `0` | Blur radius in px; `0` = off. An active glow switches to the silhouette shader and back: **2 extra draw calls per glowing sprite per frame** (2 more while a `flash()` runs), even on a shared texture. Fine for a few highlights, not for every coin in the level |
 | `glowOpacity` | `1` | Halo strength 0..1 — tweenable via `animate`, so a glow can fade in without touching the blur |
 | `blend` | `'normal'` | `'add'` brightens the backdrop instead of covering it (glows, fire, lasers). Costs one batch flush per mode change — group additive sprites by `zIndex` |
 
@@ -237,8 +243,69 @@ Every sprite gets its own phase, and the wobble unwinds exactly when disabled. T
 | `animationcomplete` | `animation` | A non-looping sheet animation finished |
 | `complete` | final transform values | A tween finished |
 | `collision` | `group`, `other`, `x`, `y` | Overlap with a `collidesWith` group began |
+| `collisionend` | `group`, `other`, `x`, `y` | That overlap ended: the shapes separated, **or** the partner was removed from the scene, hidden (`visible = false`) or stopped matching the group filter |
 | `land` | `x`, `y`, `other`, `group` | Landed on top of a `solidWith` solid. `other` is the solid — read it to react to what you landed on (trampolines, hazards) |
 
+## Font
+
+A glyph atlas for text sprites. Create it once, outside `resize`, like a SpriteSheet — it holds a GL texture.
+
+```javascript
+// 1. Built-in: nothing to ship. A 9x15 pixel font embedded in the module.
+//    You do not even need a Font object — createText without `font` uses it.
+const builtin = Game.createFont({});
+
+// 2. BMFont / AngelCode: .fnt text format or its JSON export, kerning included.
+//    Produced by BMFont, Hiero, fontbm or the module's tools/genfont.py.
+const hud = Game.createFont({ font: 'assets/hud.fnt' });
+
+// 3. Monospace grid image: cells row-major, ASCII 32..126 by default.
+const mono = Game.createFont({ image: 'assets/mono.png', charWidth: 9, charHeight: 15 });
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `font` | — | Path to a `.fnt` descriptor (AngelCode text or JSON). The page image is loaded from **next to the descriptor** unless `image` overrides it |
+| `image` | — | Grid mode: the glyph sheet. Also overrides a BMFont page path |
+| `charWidth`, `charHeight` | — | **Required** in grid mode. Missing or ≤ 0 silently falls back to the built-in font |
+| `characters` | ASCII 32..126 | Grid mode: which characters the cells map to, row-major |
+| `smoothing` | `true` | Filters the glyph texture like a sheet. The built-in font is always crisp |
+| `lineHeight` | — | Read-only: the font's natural line height in px |
+
+A descriptor that fails to parse falls back to the built-in font and logs the error — the text still renders, in the wrong face, which is the symptom to recognize.
+
+## Text
+
+`Game.createText(options)` returns a **Sprite**. Everything in the Sprite section applies — `zIndex`, `ySort`, `animate()`, `flash()`, `tintColor`, glow, `idleAnimation`, `screenFixed`, touch events, `collidesWith`. Add it to the view like any sprite: `gameView.add(label)`.
+
+```javascript
+const score = Game.createText({
+	text: 'SCORE 0',
+	x: 16,
+	y: 40,
+	anchorX: 0,          // left-aligned to a margin
+	anchorY: 0,
+	scale: 3,            // bitmap fonts size by scale, not by fontSize
+	screenFixed: true,   // ignore the camera
+	zIndex: 100
+});
+gameView.add(score);
+score.text = 'SCORE 10';   // re-lays out natively on the next frame
+```
+
+| Property | Default | Notes |
+| --- | --- | --- |
+| `text` | `''` | The string. `\n` breaks lines. Writing it re-lays out natively |
+| `font` | built-in | A Font object. Omitted or `null` = the embedded pixel font, which the scene assigns per GameView |
+| `align` | `'left'` | `'center'` / `'right'` — how multiple lines align against each other. Unknown values fall back to `'left'` |
+| `letterSpacing` | `0` | Extra px between glyphs; negative tightens |
+| `lineSpacing` | `1` | Multiplier on the font's line height |
+| `width`, `height` | laid-out size | **Derived, not settable** — the glyph layout drives the size, and with it the anchor, hit test, AABB and `ySort` bottom edge |
+
+There is no font size: scale the sprite. With the built-in pixel font, use **integer** `scale` values (`Math.max(1, Math.round(W / 240))` is the demos' idiom) so texels stay square.
+
+Every glyph is a quad in the same batch, so one label costs one draw call — a screen of labels sharing a font costs one too.
+
 ## Sound
 
 ```javascript
@@ -315,12 +382,14 @@ The tether yields at the end no finger owns: with a fixed head anchor the tail s
 Only these events exist. Nothing fires per frame, and events are only fired if a listener is registered.
 
 - **GameView**: `press`, `tap`, `release`, `resize`
-- **Sprite**: `press`, `release`, `tap`, `dragstart`, `drag`, `dragend`, `pinch`, `rotate`, `animationcomplete`, `complete`, `collision`, `land`
-- **SpriteSheet, Sound, Emitter, Rope**: none
+- **Sprite** (and therefore **Text**): `press`, `release`, `tap`, `dragstart`, `drag`, `dragend`, `pinch`, `rotate`, `animationcomplete`, `complete`, `collision`, `collisionend`, `land`
+- **SpriteSheet, Font, Sound, Emitter, Rope**: none
+
+There is `collision` (enter) and `collisionend` (exit), but deliberately **no** per-frame "stay" event — that would be bridge traffic every frame. Hold the in-between state in JS: you heard the enter, you will hear the end.
 
 ## Gotchas the property tables do not show
 
-- **`maxSpeed` defaults to 500 px/s and silently caps anything fast.** A bullet given `velocityX = 1400` travels at 500 unless you raise its own `maxSpeed`. The symptom is a projectile that looks sluggish on a large surface and fine on a small one, with nothing in the code hinting at a cap.
+- **`maxSpeed` caps `thrust` and `carMode` only — not plain velocity.** The clamp runs inside the thrust integration and inside the car model, so a sprite given `velocityX = 3000` travels at 3000 no matter what `maxSpeed` says. A ship accelerating on `thrust`, on the other hand, stops gaining speed at 500 px/s unless you raise its own `maxSpeed`, which is the cap people actually hit.
 - **`sprite.animation` survives `stop()`.** Comparing it to decide whether to restart an animation gives a false negative. The top-down demo tracks a `walking` boolean itself.
 - **`follow()` resets its options.** See the GameView section.
 - **`animate()` ignores unknown keys.** Tweening `width`, `height` or `tintColor` silently does nothing — those are instant writes only.
@@ -328,6 +397,12 @@ Only these events exist. Nothing fires per frame, and events are only fired if a
 - **`scaleX: -1` versus `flipX: true`.** Negative scale flips the physics and hit-test shape with the art; `flipX` mirrors only the drawing. Use `flipX` unless you specifically want the former.
 - **Tween positions are absolute.** A sprite with `idleAnimation` on will land off-target; disable the wobble before the tween and re-enable it on `complete`.
 - **`music` is chosen at creation.** Creating an effect sound and flipping `music` later does not switch backends.
-- **`collision` fires once per overlap-enter**, re-arming only after the shapes separate. A sprite resting inside a trigger does not re-fire.
+- **`collision` fires once per overlap-enter**, re-arming only after the shapes separate. A sprite resting inside a trigger does not re-fire — `collisionend` tells you when it left.
+- **Pooling a sprite with `visible = false` fires `collisionend`** on whoever was touching it. That is usually what you want (a plate whose ball was despawned closes its door), but a handler that assumes separation means "the player walked away" will misfire.
+- **The built-in pixel font only covers ASCII 32..126.** Em dashes, accents and `ñ` render as blanks or garbage — the module's own demos rewrote `—` as `-` for this reason. Ship a BMFont atlas (`tools/genfont.py` rasterizes any TTF) when the game needs accented Spanish text.
+- **`swept` belongs on the fast mover, not on the target.** A stationary thin wall with `swept: true` changes nothing; the bullet is the sprite whose path needs testing.
+- **A swept bullet can enter and leave in consecutive frames.** If it crosses a thin target entirely, you get `collision` and then `collisionend` almost immediately — react on the enter.
+- **Text `width`/`height` are read-only in practice.** They report the laid-out block; to make text bigger use `scale`.
 - **`hitboxShape: 'circle'` also changes the touch area**, not just collisions.
 - **`blend: 'add'` costs a batch flush per mode change.** Group additive sprites on their own `zIndex` band.
+- **`glowColor` alone draws nothing.** The glow pass only runs when `glowBlur > 0` *and* `glowOpacity > 0`; both default in a way that makes `glowColor` on its own a no-op (`glowBlur` is `0`). Always set the blur radius with the color.

package/skills/ti-game/references/project-setup.md

@@ -9,6 +9,7 @@ Installing the module, wiring it into Classic and Alloy projects, organizing art
 - [Alloy projects](#alloy-projects)
 - [Where art and sound live](#where-art-and-sound-live)
 - [Sprite sheets and atlases](#sprite-sheets-and-atlases)
+- [Fonts](#fonts)
 - [Lifecycle and cleanup](#lifecycle-and-cleanup)
 - [Debugging and tuning](#debugging-and-tuning)
 - [Platform differences](#platform-differences)
@@ -40,6 +41,8 @@ Then declare it in `tiapp.xml`. The iOS platform key is `iphone`, not `ios`:
 
 Pinning `version` is worth the extra attribute: with two module versions installed side by side, an unpinned entry silently picks the highest one.
 
+The version number lies right now: the manifest has read `0.3.0` through several feature landings. A zip built before 2026-08-18 has no `createText`, no `createFont`, no `screenFixed`, no `swept` and no `collisionend` while still calling itself 0.3.0. If a call that this skill documents is `undefined` at runtime, rebuild the module from upstream `main` rather than hunting for a typo.
+
 Building the module from source:
 
 ```bash
@@ -50,7 +53,7 @@ ti build -p ios --build-only        # macOS only → ios/dist/ti.game-iphone-<ve
 
 ## Classic projects
 
-`require('ti.game')` anywhere and add the GameView to a window. The 18 demos in the module's `example/` folder are Classic, each one a CommonJS module exporting a start function:
+`require('ti.game')` anywhere and add the GameView to a window. The 21 demos in the module's `example/` folder are Classic, each one a CommonJS module exporting a start function:
 
 ```javascript
 // Resources/flappy.js
@@ -85,7 +88,6 @@ The standard Alloy element for a native module view. `method` names the factory
 <Alloy>
 	<Window id="index" navBarHidden="true" exitOnClose="true" onOpen="onOpen" onClose="onClose">
 		<Module id="gameView" module="ti.game" method="createGameView" backgroundColor="#8ed8f8" />
-		<Label id="scoreLabel" />
 		<Button id="jumpButton" title="JUMP" onTouchstart="jump" />
 	</Window>
 </Alloy>
@@ -112,6 +114,8 @@ function onResize(e) {
 }
 ```
 
+Only views that must be native — buttons, menus, dialogs — belong in the XML. The HUD does not: scores and labels are `Game.createText` sprites created in the controller and added to the game view, so they batch with the scene and can tween and flash.
+
 Style the view in TSS like any other component (`'#gameView': { width: Ti.UI.FILL, height: Ti.UI.FILL }`). The `<Module>` element itself is documented Alloy behavior; the pattern below is the one verified in a shipped ti.game app.
 
 ### B: an empty container in XML, the GameView created in JS
@@ -219,6 +223,28 @@ Practical rules:
 
 `frameCount` is `0` until a grid sheet's texture has loaded, so do not compute animation ranges from it at creation time.
 
+## Fonts
+
+Nothing to ship for the default look: `Game.createText({ text: 'SCORE 0' })` uses a 9×15 pixel font embedded in the module, on both platforms.
+
+A custom face is an asset like any other, created once outside `resize`:
+
+```javascript
+// BMFont / AngelCode descriptor + its page image, side by side in assets/
+const hud = Game.createFont({ font: 'fonts/hud.fnt' });        // hud.png resolved next to it
+
+// or a monospace grid image
+const mono = Game.createFont({ image: 'fonts/mono.png', charWidth: 9, charHeight: 15 });
+```
+
+| File | Referenced as (Alloy) |
+| --- | --- |
+| `app/assets/fonts/hud.fnt` + `app/assets/fonts/hud.png` | `'fonts/hud.fnt'` |
+
+These are **bitmap** fonts — do not put them in `app/assets/fonts/` expecting Titanium's native font handling, and do not use a `.ttf` here. To go from a TTF to either format, the module ships `tools/genfont.py`, which rasterizes it into a grid or BMFont atlas.
+
+The built-in font covers ASCII 32..126 only. Any game whose text includes `ñ`, accents or `¿` needs a generated font — or a `Ti.UI.Label` overlay for that specific string.
+
 ## Lifecycle and cleanup
 
 The engine handles what it owns: the render loop pauses and resumes with the activity or app, music pauses and resumes with it, and textures survive an EGL context loss. **Everything you created in JS is yours to stop.**

package/skills/ti-game/references/recipes.md

@@ -1,13 +1,13 @@
 # ti.game recipes by genre
 
-Working patterns distilled from the 18 official demos in `example/` and from a shipped Alloy game (Titanium Lander). Each recipe shows the part that is specific to the genre; the shared scaffolding is in [The scaffolding](#the-scaffolding) and is not repeated.
+Working patterns distilled from the 21 official demos in `example/` and from a shipped Alloy game (Titanium Lander). Each recipe shows the part that is specific to the genre; the shared scaffolding is in [The scaffolding](#the-scaffolding) and is not repeated.
 
-Every snippet uses only API that exists in 0.3.0. Check [roadmap.md](roadmap.md) before reaching for anything not shown here.
+Every snippet uses only API that exists in upstream `main` as of 2026-08-18. Check [roadmap.md](roadmap.md) before reaching for anything not shown here.
 
 ## Contents
 
 - [The scaffolding](#the-scaffolding)
-- [Cross-cutting patterns](#cross-cutting-patterns) — pooling, parallax, multitouch controls, HUD, invisible triggers, hit-stop
+- [Cross-cutting patterns](#cross-cutting-patterns) — pooling, parallax, multitouch controls, HUD text, invisible triggers, enter/exit zones, hit-stop
 - [Tap-to-flap](#tap-to-flap) (`flappy.js`)
 - [Platformer](#platformer) (`platformer.js`)
 - [Top-down / Zelda](#top-down--zelda) (`topdown.js`)
@@ -91,7 +91,7 @@ for (let i = 0; i < 10; i++) {
 		height: 16,
 		visible: false,
 		wrapAround: true,
-		hitboxScale: 1.4,              // generous — bolts are small and fast
+		swept: true,                   // path-tested: a fast bolt cannot skip past a rock
 		collidesWith: ['asteroid']
 	});
 	const state = { sprite: sprite, active: false, generation: 0 };
@@ -135,6 +135,10 @@ function fire(x, y, vx, vy) {
 
 The `generation` counter matters: without it, a timeout fired for an old shot deactivates the *new* bullet occupying that slot.
 
+`swept: true` (compared side by side in `swept.js`) is what keeps a fast bolt from crossing a rock between two frames without ever overlapping it. The asteroids demo predates it and inflates the hitbox instead (`hitboxScale: 1.4`) — that works, at the price of counting near misses as hits. Prefer `swept`, and reserve `hitboxScale` for fairness tuning.
+
+Recycling a sprite with `visible = false` fires `collisionend` on anything it was touching. Handlers that treat separation as "the player walked away" need to tolerate a despawn.
+
 ### Seamless parallax
 
 Two screen-wide copies per layer, scrolled by native velocity. `wrapX`/`wrapShift` teleport a copy that left the screen back behind its sibling. No JS runs in the loop.
@@ -220,24 +224,37 @@ bindHold(leftButton, () => {
 
 The guard in the release handler is what keeps two opposite buttons from fighting: releasing left only zeroes steering if left is still the active direction.
 
-### HUD
+### HUD — `text.js`, `flappy.js`
 
-There is no text in the engine. Overlay `Ti.UI.Label` views on the window, above the GameView.
+Text sprites with `screenFixed: true`. They live in the scene — one batch, no overlay views — but ignore the camera, so a score stays in the corner while the world scrolls under it.
 
 ```javascript
-const scoreLabel = Ti.UI.createLabel({
-	text: '0',
-	color: '#fff',
-	font: { fontSize: 28, fontWeight: 'bold' },
-	shadowColor: '#000',
-	shadowOffset: { x: 0, y: 2 },
-	top: 40
-});
-win.add(gameView);
-win.add(scoreLabel);      // added after the game view, so it draws on top
+// Created outside resize (no size known yet), positioned once it is
+const scoreLabel = Game.createText({ text: '0', screenFixed: true, zIndex: 100 });
+const statusLabel = Game.createText({ text: 'Tap to start!', screenFixed: true, zIndex: 100 });
+
+function buildLevel(W, H) {
+	const TEXT_SCALE = Math.max(1, Math.round(W / 240));   // integer: crisp pixels
+	Object.assign(scoreLabel, { scale: TEXT_SCALE, x: W / 2, y: H * 0.08 });
+	Object.assign(statusLabel, { scale: TEXT_SCALE, x: W / 2, y: H * 0.45 });
+	gameView.add([scoreLabel, statusLabel]);
+	// ...
+}
+
+function score() {
+	points += 1;
+	scoreLabel.text = points + ' / ' + GATE_COUNT;
+	scoreLabel.flash('#4dff88', 250);                      // text flashes like any sprite
+}
 ```
 
-The shadow is not decoration — it keeps the label readable over any background the scene happens to scroll underneath.
+Scaling from `W` is what replaces `fontSize`: a bitmap font has one native size, and an integer multiplier is the only way to keep texels square. `Math.max(1, ...)` guards the smallest screens.
+
+Because a label is a sprite, the HUD gets the whole toolbox for free — `animate()` to pop a score on change, `tintColor` per state, `glowColor` on a title, `idleAnimation` for a gentle wobble, and `tap` handlers so a `[ RESET ]` label works as a button with no Titanium view behind it.
+
+Drop `screenFixed` and the same label becomes world furniture: signposts, floating damage numbers, a name over an NPC — it scrolls with everything else.
+
+Overlaid `Ti.UI.Label` views remain the answer for text the engine's font cannot draw (accents, system fonts, right-to-left) and for real UI: menus, dialogs, text inputs.
 
 ### Invisible triggers
 
@@ -269,6 +286,37 @@ car.addEventListener('collision', (e) => {
 });
 ```
 
+### Zones you can be inside of (enter / exit) — `zones.js`
+
+`collision` and `collisionend` are the two halves of a trigger: entering water, standing on a pressure plate, holding a capture point. Nothing fires while you stay inside — the state lives in JS between the two events, and that is deliberate, since a per-frame "stay" would be bridge traffic every frame.
+
+```javascript
+const pool = Game.createSprite({
+	x: W * 0.32, y: H * 0.3, width: W * 0.44, height: H * 0.18,
+	sheet: waterSheet, tintColor: '#3d6fd4', opacity: 0.35,
+	touchEnabled: false,          // drags pass through to whatever is inside
+	collisionGroup: 'water'
+});
+
+hero.collidesWith = ['water'];
+hero.addEventListener('collision', (e) => {
+	if (e.group === 'water') {
+		hero.tintColor = '#7fb2ff';
+		swimming = true;
+	}
+});
+hero.addEventListener('collisionend', (e) => {
+	if (e.group === 'water') {
+		hero.tintColor = null;
+		swimming = false;
+	}
+});
+```
+
+The listener goes on the sprite that declares `collidesWith`. For a pressure plate holding a door open exactly while a crate rests on it, that is the **plate** (`collidesWith: ['crate']`), not the crate — then `collision` opens the door and `collisionend` closes it, with no polling anywhere.
+
+Removing the partner from the scene, hiding it (`visible = false`) or changing its `collisionGroup` mid-contact all count as separation, so the exit still fires and the door cannot stick open when an object despawns.
+
 ### Hit-stop on impact
 
 Freezing the scene for a few frames makes an impact read before the explosion starts. `timeScale = 0` stops the engine from advancing while it keeps drawing and accepting touches — no render loop to restart, no state to save. (Pattern from Titanium Lander: 140 ms on a crash, 90 ms when a shield absorbs a hit.)

package/skills/ti-game/references/roadmap.md

@@ -1,6 +1,6 @@
 # What does not exist yet — and what to do instead
 
-The most expensive mistake with `ti.game` is writing code against a feature that sounds like it should be there because Phaser, Godot or Cocos has it. This file is the guard rail: everything below is **absent from 0.3.0**, with the workaround that is idiomatic today.
+The most expensive mistake with `ti.game` is writing code against a feature that sounds like it should be there because Phaser, Godot or Cocos has it. This file is the guard rail: everything below is **absent from upstream `main` as of 2026-08-18**, with the workaround that is idiomatic today.
 
 Planned items come from the module's `TODO.md`. Planned is not shipped — when a game needs one of these, use the workaround and keep the code isolated enough to swap later.
 
@@ -8,14 +8,12 @@ Planned items come from the module's `TODO.md`. Planned is not shipped — when
 
 | You might reach for | Status | What to do now |
 | --- | --- | --- |
-| `Game.createText()`, bitmap fonts, text sprites | Planned (priority 5) | Overlay `Ti.UI.Label` views on the window, above the GameView. Costs: labels are screen-fixed, so they do not scroll with the camera, do not z-sort against sprites and cannot be tweened by the engine |
 | A tilemap layer, Tiled JSON import, collision layer | Planned (priority 4) | One sprite per tile. Fine at 12×15, dead at 200×200. For large ground planes use a single `tileRepeat` sprite instead of a grid, and add sparse invisible solids for collision |
 | `sprite.parent`, attaching a turret to a tank, a hat to a hero, multi-part bosses | Planned (priority 7), the biggest structural item | Move the parts together from JS on the same coarse tick, or bake the combination into sheet frames. There is no transform inheritance |
 | `gameView.raycast(...)`, line-of-sight, ground probes | Planned (priority 3) | Compare positions in JS on a decision timer, or place an invisible trigger sprite where the probe would land and listen for `collision` |
 | Native virtual joystick or d-pad bound to a sprite | Planned (priority 6) | Overlaid Titanium views, one per button, writing `velocityX`/`steering`/`throttle` on `touchstart`/`touchend`. Sibling views get simultaneous pointers, so multitouch works |
 | Gamepad support | Planned (priority 6) | Nothing native. Touch controls only |
 | `blend: 'multiply'` or `'screen'` | Planned (priority 2) | Only `'normal'` and `'add'` exist. For darkening, use `tintColor` (multiplicative) on the sprite itself |
-| Swept AABB so fast bullets stop tunneling | Planned (priority 3) | Cap bullet speed, or enlarge the hitbox along the travel axis with `hitboxScale` — the asteroids demo uses `hitboxScale: 1.4` on its bolts for exactly this |
 | Slopes in platformer terrain | Planned (priority 3), conditional | Build slopes as stepped rectangles, or keep terrain flat |
 | Per-frame animation events (footstep on frame 3) | Planned (priority 9) | Use `animationcomplete` on a short non-looping animation, or a timer aligned to the animation's fps |
 | `play('attack', { then: 'idle' })` chaining | Planned (priority 9) | Handle `animationcomplete` and call `play()` from it |
@@ -49,7 +47,11 @@ Recent additions that are easy to miss and easy to reimplement badly in JS:
 - `createSound` with separate low-latency effect and streaming music backends.
 - `timeScale`, `maxFps`, `flipX`/`flipY`, `pixelSnap`, `idleAnimation`, `ySort`, `glowColor`/`glowBlur`/`glowOpacity`.
 - `gameView.add([array])` committing a whole level in one bridge crossing.
+- **Text is in the engine now** (2026-08-18): `createText` glyph sprites with an embedded pixel font, `createFont` for BMFont/AngelCode or monospace grid atlases, `align`/`letterSpacing`/`lineSpacing`, and `tools/genfont.py` to rasterize a TTF. Text objects are sprites — they tween, tint, flash, glow, z-sort and take taps. Do **not** fall back to `Ti.UI.Label` overlays for scores.
+- **`screenFixed`** on any sprite: surface coordinates, camera position/zoom/shake ignored, touch mapped back. HUDs no longer need overlay views.
+- **`swept: true`** per sprite: the frame's movement is path-tested (Minkowski + slab) for both collision events and solid blocking. Fast bullets stop tunneling; `hitboxScale` tricks along the travel axis are obsolete.
+- **`collisionend`**: the exit half of the trigger lifecycle, including when the partner is removed, hidden or re-tagged mid-contact.
 
 ## Checking the current state
 
-This file describes 0.3.0. Before relying on any "planned" item being still absent — or on a workaround still being necessary — read `TODO.md` and `README.md` at https://github.com/m1ga/ti.game, the module's upstream repo. `README.md` there is the canonical API documentation; the `documentation/` folder only points at it. The priorities quoted above are the maintainer's, not a roadmap this skill decides.
+This file describes upstream `main` on 2026-08-18 — a moving target: four items on this list shipped within two days of the skill being written, and the manifest version (`0.3.0`) did not change with them. Before relying on any "planned" item being still absent — or on a workaround still being necessary — read `TODO.md` and `README.md` at https://github.com/m1ga/ti.game, the module's upstream repo. `README.md` there is the canonical API documentation; the `documentation/` folder only points at it. The priorities quoted above are the maintainer's, not a roadmap this skill decides.