@maccesar/titools 4.14.0 → 4.16.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, raycasts, pathfinding, text HUDs, sprite attachment, particles, camera |
+| ti-game      | 2D games with the `ti.game` module  | Sprites, physics, tile layers, collisions, pathfinding, text/performance 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    |
@@ -443,6 +443,8 @@ When it activates:
 - Named anchors and percentage strings (`anchor: 'bottom'`, `hitboxScaleY: '55%'`) wherever the engine takes a ratio
 - Particle emitters, Verlet ropes, camera follow/zoom/shake/effects, `scrollFactor` parallax, low-latency sound
 - Game-clock timers that obey pause and slow motion, texture `unload()` for level streaming, and what LiveView reloads clean up on their own
+- Native `TileLayer` maps with visible-cell rendering, Tiled GIDs, solid/one-way cells, live edits and A* integration
+- Collision-shape overlays plus the expandable performance HUD and opt-in `performance` telemetry event
 - Drag & drop, pinch, rotate, multitouch controls
 
 Example prompts:
@@ -455,6 +457,8 @@ Example prompts:
 "Add a score HUD that stays put while the camera follows the player."
 "Make the guard walk a patrol route and turn around before the ledge."
 "Tap to walk, but the player should go around the tree instead of through it."
+"Render a 200x200 Tiled map without creating one sprite per tile."
+"Show FPS, p95 frame time, draw calls and texture switches while I tune this scene."
 ```
 
 Key rules:
@@ -463,7 +467,9 @@ 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
+- Use `Game.createTileLayer()` for large/static grids; keep sprites for interactive cells and actors
 - HUDs are `Game.createText` sprites with `screenFixed: true`, not `Ti.UI.Label` overlays
+- `debug: true` means collision shapes; use `debug: { hud: true }` or `performance` for telemetry
 - Timers that drive game logic belong on the game clock (`gameView.every`), so a paused game stops spawning
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "4.14.0",
+  "version": "4.16.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,50 +1,60 @@
 ---
 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, animations, tweens, physics (gravity, solids, carMode drifting, thrust), collision groups, trigger zones, swept AABB, raycast, paths, bitmap text, particles, ropes, camera follow/zoom/shake, parallax, sound, drag & drop, multitouch, attached labels, bars and turrets. 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, spritesheet, platformer, endless runner, top-down, shooter, racer, flappy, breakout, rhythm, cards, puzzle, hitbox, attachTo, line of sight, pathfinding, maze, patrol, 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, parent/child transforms, joystick, gamepads) do not exist yet — check references/roadmap.md before inventing an API."
-argument-hint: "[genre or feature]"
+description: "Use when a Titanium app declares ti.game in tiapp.xml, imports require('ti.game'), or needs a 2D game built or reviewed with that native engine: sprites, native movement, collisions, tile layers, camera, HUD, audio, particles, or touch. Covers Alloy and Classic on Android/iOS. Do not use for unrelated game engines or ordinary Titanium UI."
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash(node *)
 ---
 
-# ti.game — 2D game engine for Titanium SDK
+# ti.game — native 2D games 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 tracks upstream `main` as of **2026-08-26**, manifest **`0.4.0`** — that bump is the first in a long run of feature landings (the text engine, `screenFixed`, `swept` collisions, `collisionend`, `followPath`, animation chaining, `raycast`, `findPath`, game-clock timers, `scrollFactor` parallax and the `multiply`/`screen` blend modes all shipped while it still said `0.3.0`), so anything still calling itself 0.3.0 has none of them. The number lags the code in the other direction too: per-axis hitboxes (`hitboxScaleX`/`hitboxScaleY`), text word wrap (`maxWidth`), `unload()` on sheets and fonts and the LiveView renderer lifecycle (2026-08-23), then sprite attachment (`attachTo`/`detach`), inherited opacity on attachments and named/percentage values (2026-08-26, `83b7863`), all landed with the manifest still at `0.4.0`, so date the build rather than trusting the version. 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.
+`ti.game` is Michael Gangolf's OpenGL ES 2.0 sprite engine for Titanium. JavaScript describes the scene and reacts to discrete events; Android and iOS run rendering, animation, physics, collision, gestures, audio, particles, ropes, tile layers, camera work, and telemetry natively.
 
-Works in **both Classic and Alloy** projects. Nothing here depends on PurgeTSS.
+This skill is verified against upstream `main` at **`d587081` (2026-08-28)**. Both manifests still say **`0.5.0`**, although important features landed after that version was introduced. Treat the commit or build date as the capability marker; feature-detect an installed build when the exact artifact is unknown.
 
-## The one rule everything follows
+The skill applies to **Classic and Alloy** projects. Nothing here requires PurgeTSS.
 
-**JS describes the scene and reacts to events. The engine runs every frame.**
+## Required workflow
 
-The Kroll bridge (JS ↔ native) is far too slow for per-frame work, so the API is a *scene description*: setting `sprite.x`, `sprite.velocityY` or `car.throttle` writes a volatile field the render thread reads on the next tick. Events flow back only when something discrete happens — `tap`, `collision`, `land`, `complete`. Nothing fires per frame by design.
+Open the references relevant to the task before proposing code. Do not answer from familiarity with Phaser, Godot, Box2D, or an older `ti.game` build.
 
-The practical consequence, and the single biggest mistake to avoid:
+| Task | Read first |
+| --- | --- |
+| Exact methods, properties, defaults, event payloads, percentages | [references/api.md](references/api.md) |
+| Install, Classic/Alloy structure, assets, cleanup, lifecycle | [references/project-setup.md](references/project-setup.md) |
+| Choose a runnable upstream example | [references/examples.md](references/examples.md) |
+| Reusable level, pooling, HUD, collision, path, timer patterns | [references/patterns.md](references/patterns.md) |
+| Platformer, racer, shooter, runner, rhythm, ball-game recipes | [references/recipes-action.md](references/recipes-action.md) |
+| Cards, point-and-click, particles, ropes, camera, effects | [references/recipes-adventure-effects.md](references/recipes-adventure-effects.md) |
+| Large maps, Tiled data, tile collision, live edits, pathfinding | [references/tilemaps.md](references/tilemaps.md) |
+| Hitbox overlays, performance HUD, telemetry, tuning | [references/debugging-performance.md](references/debugging-performance.md) |
+| Missing, partial, and deliberately out-of-scope features | [references/roadmap.md](references/roadmap.md) |
+
+In the response, cite factual guidance with `[source: references/<file>.md]`. If a relevant reference cannot be consulted, prefix the claim with `FROM_MEMORY (unverified):` instead of silently filling the gap.
+
+The module's demos are integration evidence, not production templates. Preserve the API combination they prove, but remove launcher plumbing, repeated navigation controls, and avoidable global state when adapting them.
+
+## The engine rule
 
-> If you are about to move a sprite from a `setInterval` or a `requestAnimationFrame`, stop and find the native property that does it. Coarse timers for *decisions* (an AI picking a direction every 80–150 ms, an autofire cadence, a spawn schedule) are fine and the official demos use them. Timers for *motion* are not.
+**JS describes and reacts. The engine runs every frame.**
 
-| You want | Do NOT write | Use |
-| --- | --- | --- |
-| A sprite that falls | `setInterval(() => s.y += 5)` | `s.gravity = 2000` |
-| A sprite that moves at constant speed | timer updating `x` | `s.velocityX = 300` |
-| Move from A to B over time | manual easing loop | `s.animate({ x, y, duration, easing })` |
-| A car that drives and drifts | your own physics | `carMode: true` + `throttle`/`steering` |
-| A ship with inertia | vector math per frame | `thrust` + `angularVelocity` |
-| Drag a sprite with the finger | `touchmove` handler | `draggable: true` |
-| Scrolling background under a fixed camera | timer repositioning copies | `wrapX` / `wrapShift` + `velocityX` |
-| Parallax layers under a moving camera | hand-scrolled layers | `scrollFactor` on each layer |
-| 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 name tag, health bar or turret that rides a sprite | a timer copying `owner.x`/`y` onto it | `tag.attachTo(owner, { offsetY: -40 })` |
-| A dialog box that fits the screen | breaking the lines with `\n` after measuring in JS | `maxWidth` on the text sprite |
-| 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 |
-| An enemy on a fixed patrol route | chained `animate()` legs | `sprite.followPath(points, { loop })` |
-| Play an attack, then go back to idle | an `animationcomplete` handler | `play('attack', { then: 'idle' })` |
-| Line of sight, a ledge probe, a hitscan shot | an invisible probe sprite | `gameView.raycast(x0, y0, x1, y1, ['group'])` |
-| Walking around obstacles to a tapped point | your own A* in JS, or a straight line through the wall | `gameView.findPath(from, to, opts)` → `sprite.followPath(path)` |
-| A spawn wave or an AI tick that respects pause | `setInterval` | `gameView.every(ms, cb)` |
-| 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` |
+Do not move sprites from `setInterval`, `requestAnimationFrame`, or a JS loop. Property writes cross the Kroll bridge; native properties and methods keep frame-by-frame work on the render thread. Coarse timers are appropriate for decisions such as enemy targeting or spawn cadence, preferably through `gameView.after()` / `every()` when they must obey pause and `timeScale`.
+
+| Intent | Native mechanism |
+| --- | --- |
+| Fall or move continuously | `gravity`, `gravityX`, `velocityX`, `velocityY` |
+| Move to a point | `animate()` or `followPath()` |
+| Drive or fly | `carMode` + `throttle`/`steering`, or `thrust` + `angularVelocity` |
+| Drag, pinch, rotate | `draggable`, `pinchable`, `rotatable` |
+| Follow the player | `gameView.follow()` |
+| Walk around obstacles | `findPath()` → `followPath()` |
+| Test line of sight or hitscan | `raycast()` |
+| Fast projectile collision | `swept: true` on the mover |
+| Repeat a large map efficiently | `Game.createTileLayer()` |
+| Attach a label, health bar, or turret | `attachTo()` |
+| Score or in-game label | `Game.createText()`; usually `screenFixed: true` for a HUD |
+| Smoke, sparks, explosions | `Game.createEmitter()` |
+| Chain, tether, cape | `Game.createRope()` |
+| Pause or slow the scene while still drawing | `gameView.timeScale` |
+| Measure FPS, frame time, and draw calls | `debug: { hud: true }` or the `performance` event |
 
 ## Minimal scene
 
@@ -53,34 +63,31 @@ const Game = require('ti.game');
 
 const win = Ti.UI.createWindow({
 	backgroundColor: '#000',
-	navBarHidden: true,                           // iOS: no nav bar
-	theme: 'Theme.Titanium.DayNight.NoTitleBar'   // Android: no title bar
+	navBarHidden: true,
+	theme: 'Theme.Titanium.DayNight.NoTitleBar'
+});
+const gameView = Game.createGameView({
+	backgroundColor: '#8ed8f8',
+	maxFps: 60
 });
-const gameView = Game.createGameView({ backgroundColor: '#8ed8f8' });
-
 const sheet = Game.createSpriteSheet({
 	image: 'assets/hero.png',
 	frameWidth: 32,
 	frameHeight: 48,
-	smoothing: false            // nearest-neighbor — crisp pixel art
+	smoothing: false
 });
 
 let initialized = false;
-gameView.addEventListener('resize', (e) => {
+gameView.addEventListener('resize', ({ width, height }) => {
 	if (initialized) {
 		return;
 	}
 	initialized = true;
-	buildLevel(e.width, e.height);
-});
 
-function buildLevel(W, H) {
 	const hero = Game.createSprite({
-		sheet: sheet,
-		x: W / 2,
-		y: H / 2,
-		width: 96,
-		height: 144,
+		sheet,
+		x: width / 2,
+		y: height / 2,
 		animations: {
 			idle: { frames: [0], fps: 1, loop: true },
 			walk: { frames: [1, 2], fps: 6, loop: true }
@@ -88,147 +95,40 @@ function buildLevel(W, H) {
 	});
 	hero.play('idle');
 	gameView.add(hero);
-}
+});
 
 win.add(gameView);
 win.open();
 ```
 
-### Build the level on `resize`, never from `displayCaps`
-
-`Ti.Platform.displayCaps` includes the system bars and reports **points** on iOS, while the scene lives in surface **pixels**. Sizing a level from it puts bottom-anchored sprites below the visible area. The GameView fires `resize` with the real surface size — that is the coordinate space. The guard flag matters: `resize` fires again on rotation and on some lifecycle transitions, and rebuilding the level there would duplicate every sprite.
-
-When you genuinely need dp→scene units (to keep a floor above 80dp on-screen buttons), measure the surface rather than trusting the density factor, because the iOS Simulator renders at 1x while still reporting the device scale:
-
-```javascript
-const density = Ti.Platform.osname === 'android'
-	? Ti.Platform.displayCaps.logicalDensityFactor
-	: H / Ti.Platform.displayCaps.platformHeight;
-const buttonZone = Math.round(130 * density);
-const groundTop = H - buttonZone;
-```
-
-### Coordinates
-
-Top-left origin, y-down, surface pixels. Touch coordinates map 1:1. `(x, y)` is the sprite's **anchor** (default `0.5/0.5` = center, so `y` is the middle of the sprite, not its top). Rotation in degrees, positive clockwise. All JS durations are milliseconds.
-
-## Pick a movement model
-
-| Model | Properties | Fits |
-| --- | --- | --- |
-| Plain velocity | `velocityX/Y` (px/s), `gravity` (px/s²) | Flappy, projectiles, falling objects, notes |
-| Platformer | velocity + `solidWith`, read-only `onGround`, `land` event | Mario-style run & jump |
-| Bouncing body | `restitution` (0..1) on top of `solidWith` | Balls, pinball, breakout |
-| Car | `carMode: true`, `throttle`, `steering` (-1..1) | Top-down racer with emergent drift |
-| Newtonian flight | `thrust` (px/s² along heading), `angularVelocity` (deg/s), `maxSpeed` | Asteroids, lunar lander |
-| Tween | `animate({ x, y, duration, easing })` | Point-and-click walking, UI cards, patrols |
-
-Gravity is per sprite, not global — set it on each body that should fall. A sprite with no `gravity` and no velocity simply stays put.
-
-## 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 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.
-
-When the question is not "did we touch?" but "what is over there?", the answer is `gameView.raycast(x0, y0, x1, y1, ['group'])` — line of sight, a ledge probe ahead of a walker's feet, a hitscan shot. It returns `null` or the nearest hit (`{ x, y, distance, group, sprite, normal }`), needs nothing but a `collisionGroup` on the targets, and replaces the old trick of parking an invisible probe sprite where the ray would land. It is a discrete query: call it from a decision timer or a tap handler, never every frame.
-
-And when the question is "how do I get over there?", `gameView.findPath(from, to, { cellSize, groups, clearance, bounds })` runs grid A* around the same tagged sprites and hands back waypoints for `followPath` — tap-to-walk that rounds a tree, a hound re-routing to the player on an 800 ms timer. Also discrete: the walk itself runs natively between queries, so pathfind on taps and AI ticks, never per frame. Pass `clearance` of about half the walker's width, since the route is a line for the sprite's **center**.
-
-**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), `hitboxScaleX`/`hitboxScaleY` when the drawing fills its frame by a different fraction on each axis (a 20×44 hero in a 32×48 frame wants `0.62` wide and `0.92` tall — the two multiply `hitboxScale` rather than replace it), 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.
-
-The hitbox shrinks **around the anchor**, which is why the anchor is half of that tuning and why both now have readable forms: `anchor: 'bottom'` with `hitboxScaleY: '55%'` is the same sprite as `anchorY: 1` with `hitboxScaleY: 0.55`, and says what it is doing. Every ratio the engine exposes takes a percentage string, and the anchors take names (`'left'`, `'bottom-right'`, `'center'`); numbers keep working untouched. [api.md](references/api.md) lists exactly which properties are ratios — coordinates, sizes, degrees and speeds are not, and neither is the car model's `grip`/`drag`.
-
-## 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 blend-mode transition in draw order flushes — there are four (`'normal'`, `'add'`, `'multiply'`, `'screen'`), so group same-blend sprites into their own `zIndex` band and the frame switches a handful of times instead of 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 non-normal 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.
-- **Read properties in handlers, not in loops.** `ball.x` is a synchronous snapshot of the live native value — perfect inside a `collision` handler or an 80 ms AI tick, wasteful in a tight loop.
-- **`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.
-
-## 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
-```
-
-One long string wraps itself: `maxWidth` breaks lines on word boundaries and re-wraps every time `text` changes, so a dialog box needs no hand-broken `\n`. It is measured in font-space px, *before* `scale` — divide the screen width you want by the scale you are drawing at.
+## Non-negotiable invariants
 
-`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).
+- Build surface-dependent content from the GameView's guarded `resize` event. `Ti.Platform.displayCaps` is not the scene surface and can include system bars or different units.
+- Coordinates use a top-left origin, y increases downward, and `(x, y)` is the sprite anchor. Durations crossing the JS boundary are milliseconds.
+- `solidWith` blocks; `collidesWith` reports `collision`/`collisionend`. They are independent. A sized sprite without a sheet is a valid invisible solid or trigger.
+- Put the hitbox shape on the object whose geometry matters. A round peg needs `hitboxShape: 'circle'`; a ramp needs `'rotatedRect'`.
+- A `TileLayer` replaces one-sprite-per-tile maps when the map is large. Its visible-cell renderer, cell collision, live edits, and pathfinding integration are native.
+- Collect initial sprites, emitters, ropes, and tile layers and add them in one `gameView.add([...])` call.
+- Use `Game.createText()` for scene text. Use Titanium views only for UI the engine cannot draw, such as native input controls or system-font interfaces.
+- Stop app-owned JS timers, looping sounds, and listeners on close/controller cleanup. `removeAllSprites()` clears Sprite/Text objects only; explicitly remove tracked emitters, ropes, and tile layers. `SpriteSheet.unload()` and `Font.unload()` are permanent level-streaming operations, not cache eviction.
+- Check [references/roadmap.md](references/roadmap.md) before naming an API that merely exists in another engine.
 
-A label that belongs *on* a moving sprite is neither: `tag.attachTo(hero, { offsetY: -40 })` pins it natively, resolved every frame after physics and before collisions, so it never lags by a frame and needs no JS. It works on any sprite, not just text — health bars, shadows, an invisible hitbox on a body, and with `rotate: true` a turret whose offset swings with the tank. Removing the owner removes what is attached to it, and fading the owner fades them with it: position, rotation and opacity are inherited. Scale, visibility and tint are not — set those per sprite.
+## Source priority
 
-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.
+When sources disagree, use this order:
 
-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`.
+1. Android and iOS native proxy/engine code for actual behavior and parity.
+2. `example/*.js` for combinations exercised by the module, not code-quality conventions.
+3. Upstream `README.md` and `TUTORIAL.md` for intended public usage.
+4. Upstream `TODO.md` for what remains partial or absent.
 
-## Clean up what you created
+Known upstream prose drift at the pinned commit: the README says 26 demos although there are 33; its camera row names the wrong HUD corner; and it says every `TileLayer` property is live although Android treats `legend`, `firstGid`, `cols`, and `rows` as creation-time configuration. The references already normalize those differences.
 
-The render loop follows the activity lifecycle automatically, but **your JS timers and sounds do not**. Every demo that starts an interval or plays looping music stops it on window close. In Alloy, wire this into the controller's `cleanup()`.
+## Before returning code
 
-Two things the engine now cleans up on its own, so do not hand-roll them: a **LiveView reload** retires the previous runtime's render loops, `SoundPool`, `MediaPlayer`s and audio proxies, so reloads stop stacking game loops; and releasing a sheet or font frees its GL texture. What you *can* now do explicitly is `spriteSheet.unload()` / `font.unload()` when streaming levels — permanent, so only after nothing draws from them.
-
-Game-clock timers (`gameView.after` / `every`) are the exception that proves the rule: they run on the engine's clock, so they freeze at `timeScale: 0` and pause with the render loop instead of firing into a dead scene. That is why spawn waves and AI ticks belong there. A `setInterval` keeps running through a pause, which is right for a real-time countdown and wrong for everything else.
-
-```javascript
-win.addEventListener('close', () => {
-	clearInterval(aiTimer);
-	clearTimeout(spawnTimer);
-	music.stop();          // a looping track outlives the window otherwise
-	gameView.pause();
-	gameView.removeAllSprites();
-});
-```
-
-## Reference files
-
-Read the one that matches the task instead of guessing — the API surface below was verified against the module source, not reconstructed from memory.
-
-| Need | Reference |
-| --- | --- |
-| Exact properties, methods, events, defaults for every object | [api.md](references/api.md) |
-| Working code per genre: flappy, platformer, top-down, racer, asteroids, endless runner, rhythm, cards, point & click, particles, ropes, camera — plus patrol paths, raycast probes, pathfinding, parallax and game-clock timers | [recipes.md](references/recipes.md) |
-| Install the module, tiapp.xml, Alloy vs Classic wiring, assets, sprite sheets, atlases, lifecycle, testing | [project-setup.md](references/project-setup.md) |
-| What does NOT exist yet, what is coming, and how to work around it today | [roadmap.md](references/roadmap.md) |
-
-When this skill runs out — a brand-new feature, a demo's exact code, a build question — read upstream itself at https://github.com/m1ga/ti.game. Each file there is authoritative for something different:
-
-| Upstream file | What it is authoritative for |
-| --- | --- |
-| `README.md` | The module's own API documentation, and the demo index. Canonical, but it has lagged the code: verify a defaulted value against the source before relying on it |
-| `example/` | 26 runnable demos, one per feature area — the reference implementations this skill's recipes are distilled from |
-| `TODO.md` | What the maintainer has planned, with priorities. The source of [roadmap.md](references/roadmap.md) |
-| `tutorial.md` | A step-by-step first scene (sprite, animation, tap-to-move). For a human learning the module, not for looking things up |
-| `ios/README.md` | The iOS port's threading, coordinates and touch constants. Mostly for module developers; the app-facing facts are already here |
-| `AGENTS.md` | Rules for changing the module itself — irrelevant to building a game with it |
-| `android/src/ti/game/`, `ios/Classes/` | The truth. Defaults, clamping and edge cases in this skill were read here, not from prose |
-
-## Before writing game code, check these
-
-1. Is the level built inside a guarded `resize` handler, using `e.width`/`e.height`?
-2. Does any timer move a sprite? Replace it with velocity, gravity, a tween, `carMode` or `thrust`.
-3. Are all the level's objects added in one `gameView.add([...])` call?
-4. Does every moving body have the right model — `solidWith` to be blocked, `collidesWith` to be notified?
-5. Is `hitboxScale` set on sprites whose art does not fill the frame — with `hitboxScaleX`/`hitboxScaleY` when the fit differs per axis, and the `anchor` the box shrinks around named rather than left as a bare `1`?
-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 `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. Does a timer drive game logic (spawn waves, AI ticks, respawns)? Move it to `gameView.every`/`after` so it obeys pause and slow motion.
-11. Does anything ride on top of a moving sprite — a name tag, a health bar, a turret, a hitbox? `attachTo` pins it natively; a timer copying coordinates is the old workaround.
-12. Are you using an API that actually exists? Anything involving tilemaps, full parent/child transforms, joysticks, gamepads or slopes — check [roadmap.md](references/roadmap.md) first.
+- Confirm the installed module build exposes every API used; the manifest version alone is insufficient.
+- Keep per-frame work native and JS event-driven.
+- Prefer a demo-backed combination, then refactor it into focused, maintainable code.
+- Preserve Android/iOS parity; do not rely on an Android-only permissive argument shape.
+- State partial engine behavior honestly, especially slopes, tile triggers/raycast, parenting, audio polish, and input devices.
+- Cite the references that support the result.