@maccesar/titools 4.15.0 → 4.16.0

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

@@ -0,0 +1,340 @@
+# Adventure, presentation, and effects recipes
+
+Production-oriented patterns distilled from the upstream non-action demos at `ti.game@d587081`. Use [examples.md](examples.md) to locate the full runnable demo and [api.md](api.md) for exact defaults and payloads.
+
+<!-- TOC-START -->
+## Contents
+
+- [Cards and board games](#cards-and-board-games)
+- [Point & click adventure](#point--click-adventure)
+- [Particles](#particles)
+- [Ropes and chains](#ropes-and-chains)
+- [Camera work](#camera-work)
+- [Visual effects](#visual-effects)
+
+<!-- TOC-END -->
+
+## Cards and board games
+
+No physics at all — sprite taps, native tweens, glow and idle wobble.
+
+**Dealing** staggers one tween per card with `delay`, and flips the art on arrival:
+
+```javascript
+cards.forEach((card, index) => {
+	card.state = 'dealing';
+	card.sprite.idleAnimation = false;      // still cards land exactly on target
+	card.sprite.frame = BACK_FRAME;
+	card.sprite.x = DECK_X;
+	card.sprite.y = DECK_Y;
+	card.sprite.zIndex = 30 + index;        // above the deck while flying
+	card.sprite.animate({
+		x: card.home.x,
+		y: card.home.y,
+		rotation: card.home.rotation,
+		duration: 380,
+		delay: index * 140,                 // one card after another
+		easing: Game.EASE_IN_OUT
+	});
+});
+
+sprite.addEventListener('complete', () => {
+	if (card.state === 'dealing') {
+		card.state = 'hand';
+		sprite.frame = card.face;           // flip face up on arrival
+		sprite.zIndex = card.index;
+		sprite.idleAnimation = true;        // wobble only once it has settled
+	}
+});
+```
+
+**Selection** lifts the card and fades a glow in — `glowOpacity` is tweenable, so the halo appears with the movement instead of popping:
+
+```javascript
+sprite.addEventListener('tap', () => {
+	if (card.selected) {
+		card.selected = false;
+		sprite.animate({ x: home.x, y: home.y, rotation: home.rotation, scale: 1, glowOpacity: 0, duration: 150, easing: Game.EASE_OUT });
+	} else if (selectedCards().length < MAX_SELECTED) {
+		card.selected = true;
+		sprite.glowColor = '#ffc94d';
+		sprite.glowBlur = CARD_W * 0.14;
+		sprite.glowOpacity = 0;
+		sprite.animate({ y: home.y - LIFT, scale: 1.12, glowOpacity: 1, duration: 150, easing: Game.EASE_OUT });
+	}
+});
+```
+
+**Drag & drop with snapping** (puzzle pieces, board tiles). The drag itself is native; you only decide where it lands:
+
+```javascript
+const piece = Game.createSprite({ sheet: sheet, frame: index, x: homeX, y: homeY, width: PIECE, height: PIECE, draggable: true, zIndex: 10 });
+
+piece.addEventListener('press', () => {
+	piece.zIndex = 100;                     // draw above everything while held
+	piece.animate({ scale: 1.15, duration: 120, easing: Game.EASE_OUT });
+});
+
+piece.addEventListener('release', () => {
+	piece.animate({ scale: 1, duration: 120, easing: Game.EASE_OUT });
+});
+
+piece.addEventListener('dragend', (e) => {
+	let best = null;
+	let bestDistance = SNAP_DISTANCE;
+	cells.forEach((cell) => {
+		if (cell.piece) {
+			return;
+		}
+		const d = Math.sqrt(Math.pow(e.x - cell.x, 2) + Math.pow(e.y - cell.y, 2));
+		if (d < bestDistance) {
+			bestDistance = d;
+			best = cell;
+		}
+	});
+	piece.zIndex = 10;
+	if (best) {
+		best.piece = piece;
+		piece.animate({ x: best.x, y: best.y, duration: 150, easing: Game.EASE_OUT });
+	} else {
+		piece.animate({ x: homeX, y: homeY, duration: 400, easing: Game.EASE_IN_OUT });
+	}
+});
+```
+
+Because every handler is per sprite, this is multi-touch for free: each finger grabs its own piece.
+
+## Point & click adventure
+
+Tap-to-walk routes around the scenery with `findPath` and walks the waypoints natively:
+
+```javascript
+const WALK_BOUNDS = {                                     // the floor, in sprite-CENTER coordinates
+	minX: W * 0.06, maxX: W * 0.94,
+	minY: WALK_TOP - PLAYER_H / 2, maxY: H * 0.95 - PLAYER_H / 2
+};
+
+function walkTo(x, y) {
+	const targetX = Math.min(Math.max(x, WALK_BOUNDS.minX), WALK_BOUNDS.maxX);
+	const targetY = Math.min(Math.max(y - PLAYER_H / 2, WALK_BOUNDS.minY), WALK_BOUNDS.maxY);
+	const path = gameView.findPath({ x: player.x, y: player.y }, { x: targetX, y: targetY }, {
+		cellSize: Math.round(W * 0.04),
+		groups: ['obstacle'],
+		clearance: PLAYER_W * 0.35,                       // keep half a body off the trunk
+		bounds: WALK_BOUNDS
+	});
+	if (!path || path.length < 2) {
+		return;                                           // tapped outside the floor
+	}
+	player.scaleX = path[1].x < player.x ? -1 : 1;        // face the first leg
+	player.play('walk');
+	player.followPath(path, { speed: WALK_SPEED });       // constant px/s, cancels the previous route
+}
+
+player.addEventListener('pathcomplete', () => player.play('idle'));
+```
+
+The walkable floor is still a clamp, not geometry — but it is now expressed as the `bounds` rect the search runs in. Obstacles are separate: `pointclick.js` adds an invisible box over the oak's *trunk* only (`opacity: 0`, `touchEnabled: false`, `collisionGroup: 'obstacle'`), so the player circles the trunk and still walks behind the canopy with `ySort`. See [Pathfinding around obstacles](patterns.md#pathfinding-around-obstacles--mazejs-pointclickjs) for the options.
+
+With nothing in the scene to route around, `findPath` returns `[start, goal]` and `followPath` walks the straight line — the same result as the distance-sized `animate()` tween this demo used before, with one less speed calculation to get wrong.
+
+**Hotspots and the tap conflict.** The GameView fires `tap` for *every* touch, including ones a sprite already handled, so a naive walk handler also walks when you click the bird. Hit-test the interactive sprites in JS and bail out:
+
+```javascript
+function over(sprite, x, y) {
+	return sprite.visible !== false
+		&& Math.abs(x - sprite.x) <= sprite.width / 2 + PAD
+		&& Math.abs(y - sprite.y) <= sprite.height / 2 + PAD;
+}
+
+gameView.addEventListener('tap', (e) => {
+	if (over(bird, e.x, e.y) || over(handIcon, e.x, e.y) || over(talkIcon, e.x, e.y)) {
+		return;
+	}
+	hideIcons();
+	walkTo(e.x, e.y);
+});
+```
+
+A verb coin is two icon sprites with `visible` toggled and `idleAnimation: true` for a bit of life while open.
+
+## Particles
+
+Three modes, all native. Tint white art at runtime so one 16×16 texture covers every effect in the game.
+
+**Continuous fountain**:
+
+```javascript
+const fountain = Game.createEmitter({
+	sheet: sparkSheet, frame: 1,
+	x: W / 2, y: H - UNIT * 0.05,
+	rate: 90,
+	lifetime: 1600,
+	speed: H * 0.75,          // launch up...
+	angle: 0,                 // 0 = up, clockwise degrees
+	spread: 25,
+	gravity: H * 0.45,        // ...and fall back
+	size: UNIT * 0.03,
+	startScale: 1, endScale: 0.4,
+	startOpacity: 1, endOpacity: 0,
+	tint: '#ffcc44',
+	maxParticles: 400
+});
+gameView.add(fountain);
+```
+
+**Burst on demand** — `rate: 0`, position it and call `emit(n)`:
+
+```javascript
+const firework = Game.createEmitter({
+	sheet: sparkSheet, frame: 1,
+	rate: 0,
+	lifetime: 900,
+	speed: UNIT * 0.6,
+	spread: 360,
+	gravity: H * 0.25,
+	startScale: 1, endScale: 0.3,
+	maxParticles: 500
+});
+gameView.add(firework);
+
+gameView.addEventListener('tap', (e) => {
+	firework.x = e.x;
+	firework.y = e.y;
+	firework.tint = COLORS[colorIndex++ % COLORS.length];
+	firework.emit(45);
+});
+```
+
+**Trail following a sprite** — `target` keeps up even mid-drag, with no bridge traffic:
+
+```javascript
+const dust = Game.createEmitter({
+	sheet: sparkSheet, frame: 0,
+	target: player,
+	offsetX: -PLAYER * 0.32,      // behind the rear wheels
+	offsetY: PLAYER * 0.42,
+	rate: 22,
+	lifetime: 450,
+	speed: W * 0.08,
+	angle: -35,                   // up and back
+	spread: 50,
+	startOpacity: 0.45, endOpacity: 0,
+	tint: '#8a8580',
+	zIndex: 9                     // behind the player
+});
+gameView.add(dust);
+
+dust.emitting = false;            // the one property JS toggles at runtime
+```
+
+Add `blend: 'add'` for fire, magic and sparks — overlaps bloom instead of covering.
+
+## Ropes and chains
+
+```javascript
+// hangs from a draggable ball
+const ball = Game.createSprite({ sheet: ballSheet, x: W / 2, y: H * 0.22, width: BALL, height: BALL, zIndex: 10, draggable: true, hitboxShape: 'circle' });
+gameView.add(ball);
+
+gameView.add(Game.createRope({
+	sheet: ropeSheet,
+	segments: 14,
+	segmentLength: H * 0.04,
+	thickness: W * 0.03,
+	gravity: H * 1.6,
+	damping: 0.985,
+	iterations: 3,
+	head: ball,                   // pinned to the sprite — drag it and the rope follows
+	zIndex: 5
+}));
+
+// fixed anchor + a weight on a tether: drag it too far and it is pulled back
+gameView.add(Game.createRope({
+	sheet: ropeSheet,
+	segments: 10,
+	segmentLength: SEG_LEN,
+	gravity: H * 1.6,
+	x: W * 0.15, y: H * 0.1,      // fixed head anchor
+	tail: weight,
+	maxLength: 10 * SEG_LEN,      // wrecking balls, leashes, yo-yos
+	zIndex: 5
+}));
+```
+
+With sprites on both ends plus `maxLength`, dragging either one tows the other once the rope goes taut — carts, chained crates, a grappling hook whose tip you read from `rope.endX` / `rope.endY`.
+
+## Camera work
+
+```javascript
+gameView.follow(player, {
+	leftMargin: 0.4, rightMargin: 0.6,       // horizontal follow is off without these
+	topMargin: 0.4, bottomMargin: 0.6,
+	smoothing: 0.12,                         // 0 snaps; higher eases
+	maxY: WORLD_H                            // default 0 clamps to the top of the world
+});
+gameView.cameraBounds = { minX: 0, minY: 0, maxX: WORLD_W, maxY: WORLD_H };
+```
+
+Sprites live in world coordinates and touch input is mapped back to world space automatically, zoom included — taps and drags keep working while scrolled. Overlaid Titanium controls are screen-fixed and unaffected.
+
+```javascript
+gameView.cameraScale = Math.min(2.5, Math.max(0.5, gameView.cameraScale * 1.25));   // zoom
+gameView.shake({ strength: W * 0.02, duration: 500 });                              // impact
+gameView.cameraEffect = 'tint';                                                     // night vision
+gameView.cameraTint = '#4f8';
+gameView.cameraEffectIntensity = 0.7;
+gameView.cameraEffect = 'glitch';                                                   // broken signal
+gameView.cameraEffect = 'none';                                                     // skips the pass entirely
+```
+
+For a big ground plane, one `tileRepeat` sprite covering the whole world beats a grid of tile sprites — the texture keeps its native density and the scene stays one draw call.
+
+## Visual effects
+
+**Blend modes** — four, on sprites and emitters alike. `blend.js` shows all of them side by side over a bright meadow strip:
+
+| Mode | Does | Use for |
+| --- | --- | --- |
+| `'normal'` | Covers what is behind it | Everything else |
+| `'add'` | Sums toward white | Glows, fire, lasers, light shafts, sparks |
+| `'multiply'` | Darkens the backdrop | Contact shadows under sprites, stains, grime, smoke that dims |
+| `'screen'` | Lightens without blowing out | Fog, haze, god rays, soft light |
+
+Group same-blend sprites on their own `zIndex` band: every mode change in draw order costs a batch flush, so alternating them sprite by sprite degrades toward one draw call each. Unknown strings fall back to `'normal'` in silence and the names are case-sensitive — `blend: 'Add'` renders as normal with no warning.
+
+**`flash(color, duration)`** — a solid-color silhouette that fades out natively. This is the damage flash a multiplicative `tintColor` cannot produce (white tint = no change). Retrigger it on a timer for invincibility blinking.
+
+**`flipX` / `flipY` from movement** — mirror the drawn frame without touching physics:
+
+```javascript
+// tween patrol: flip on each turn-around
+function patrol() {
+	const goingRight = bird.x < W / 2;
+	bird.flipX = !goingRight;
+	bird.animate({ x: goingRight ? W - MARGIN : MARGIN, duration: 3000, easing: Game.EASE_IN_OUT });
+}
+bird.addEventListener('complete', patrol);
+
+// velocity runner: a slow watchdog turns it around, never moves it
+timer = setInterval(() => {
+	[dog, player].forEach((runner) => {
+		if (runner.velocityX > 0 && runner.x > W - MARGIN) {
+			runner.velocityX = -runner.velocityX;
+		} else if (runner.velocityX < 0 && runner.x < MARGIN) {
+			runner.velocityX = -runner.velocityX;
+		}
+		runner.flipX = runner.velocityX < 0;
+	});
+}, 150);
+
+// VVVVVV-style gravity inversion
+gameView.addEventListener('tap', () => {
+	player.gravity = -player.gravity;
+	player.flipY = player.gravity < 0;
+});
+```
+
+**`timeScale`** — one property slows or freezes physics, sheet animations, tweens, particles, the camera and the game-clock timers together, while rendering and touch keep running. `0.5` for slow motion, `0` for a pause that still draws, short bursts of `0` for hit-stop. `timescale.js` makes the timer half visible: a clock on `gameView.every(1000, ...)` freezes with the scene while a `setInterval` clock beside it keeps ticking.
+
+**`idleAnimation`** — a per-sprite organic sway that composes with tweens and drags. Cheap life for cards, icons, floating pickups and menu art. Disable it before a tween that must land precisely.

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

@@ -1,70 +1,49 @@
-# What does not exist yet — and what to do instead
+# Missing, partial, and out-of-scope features
 
-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-27** (`ee69056`, manifest `0.5.0`), 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.
+Verified against `ti.game@d587081` (2026-08-28), especially upstream `TODO.md` and both native implementations. Planned is not shipped; partial means the exact boundary below matters.
 
 ## Not available today
 
-| You might reach for | Status | What to do now |
+| Tempting API or capability | Current status | Safe approach |
 | --- | --- | --- |
-| 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. `findPath` already rasterizes those per-tile sprites, so a tile maze pathfinds today — the planned collision layer is meant to feed the same grid |
-| `sprite.parent` and full transform inheritance — a child that scales and flips with its parent | Partly shipped, the rest still planned (priority 7) | **Position, rotation and opacity are done**: `attachTo(target, { offsetX, offsetY, rotate })` pins a sprite to another natively, chains included, and a fade on the owner cascades down, so turrets, hats, name tags and health bars need no JS. What is *not* inherited is `scale`, `visible`, `flipX`/`flipY` and `tintColor`, and there is no `parent` property, no hit-test or `ySort` integration. Set those on each part yourself, on the coarse tick that changes them |
-| `gameView.panTo(x, y, { duration, easing })` for a cutscene camera move | Planned (priority 1) | `follow()` an invisible sprite and tween that sprite, then `follow()` the player again |
-| Ping-pong animation playback, a per-sprite animation speed multiplier, a random start offset | Planned (priority 9) | Author the ping-pong into the sheet as a longer animation. Desync a field of torches by giving each one its own `idleAnimation` timing, or start them from staggered timers |
-| 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 |
-| Slopes in platformer terrain | Partly shipped, the platformer feel still planned (priority 3) | **The geometry is done**: a tilted `hitboxShape: 'rotatedRect'` solid resolves along its real face, carries a rider and lets a crate or a ball slide down it. What is missing is the *feel* on top of it — walking up a slope without the step-up stutter, friction that acts **along the contact only** (`linearDamping` bleeds speed in every direction, right for a pool table and wrong for a hill), and terrain built from more than one flat ramp. Stepped rectangles are no longer the workaround for a single ramp; they still are for a curve |
-| 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 |
-| `playbackRate`, pitch jitter, stereo pan, `fadeTo()` on sounds | Planned (priority 8) | Only `volume`, `loop`, `play`, `pause`, `stop` exist. Ship a few pre-pitched variants of a sample and alternate between them |
-| An fps / draw-call / sprite-count overlay | Planned (developer experience) | `debug: true` draws collision shapes only. There is no stats overlay and no `performance` event — measure with platform tooling |
-| TypeScript definitions (`ti.game.d.ts`) | Planned (developer experience) | None yet |
-| Aseprite JSON import | Planned (developer experience) | TexturePacker JSON (hash or array) is the only atlas format |
-| A `stop()` for the whole scene | Not planned — already covered | `gameView.timeScale = 0` freezes everything the engine ticks while rendering and touch keep running. `gameView.pause()` stops the render loop entirely |
-| Tweening `width`, `height` | Not planned | `animate()` only handles `x`, `y`, `scale`, `scaleX`, `scaleY`, `rotation`, `opacity`, `glowOpacity`, plus `frame` at the end. Everything else is an instant write — scale instead of sizing |
-| Tweening `tintColor`, or `repeat`/`yoyo` on `animate()` | Planned (priority 9) | Re-launch the tween from its `complete` handler for a blink or a ping-pong, and step a tint by writing `tintColor` on a game-clock timer |
-| Standard Titanium touch events on the GameView | By design | The view fires its own `press`, `tap`, `release` with scene coordinates. Sprites fire the richer set. Overlaid Titanium views keep their normal events |
-| A per-frame event to hook your own logic into | By design, never | The whole architecture exists to keep JS out of the frame loop. Use `collision`, `land`, `complete`, `animationcomplete`, or a coarse timer for decisions |
-
-## Deliberately out of scope
-
-The module's own `TODO.md` rules these out, each being a project the size of everything built so far:
-
-- **2D lighting and shadows.** If it ever comes up: a screen-dim overlay plus additive light sprites (`blend: 'add'`) gets 90% of the look for 1% of the cost, and `blend: 'multiply'` now does contact shadows under sprites.
-- **Skeletal animation (Spine).** Frame animations from sheets only.
-- **Full rigid-body physics (Box2D class).** What exists — velocity, gravity on both axes, solids with penetration resolution, two-sided restitution, circle, rect and turned-rect hitboxes, `linearDamping`, the car model, thrust, and since 2026-08-27 a bilateral circle-on-circle response that splits the separation and exchanges the closing velocity — covers the target genres. What that last one is **not** is a solver: it assumes equal masses, runs one pass per frame with no iteration, and carries no friction or spin, so a tall stack settles rather than balancing. Joints, torque, compound bodies and real stacking still do not exist, and a game that needs them needs a physics engine, not this.
-- **Render-to-texture.** The only offscreen pass is the fullscreen `cameraEffect`.
-
-## Already shipped (do not "work around" these)
-
-Recent additions that are easy to miss and easy to reimplement badly in JS:
-
-- Camera: horizontal and vertical dead-zone `follow`, `cameraBounds`, `smoothing`, `cameraScale` zoom, native `shake`.
-- `tintColor`, `flash(color, duration)`, `blend: 'add'`, `tileRepeat` with `repeat: true` sheets.
-- `hitboxShape: 'circle'` with contact-normal resolution against solids, `oneWay` platforms, moving solids that carry their riders (`carryRiders` to opt out).
-- `createEmitter` particles, `createRope` Verlet ropes with `maxLength` tethers.
-- `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.
-- **`followPath(points, opts)` and `play(name, { then })`** (2026-08-19): patrol routes, bullet arcs and animation chains run natively. Do not chain `animate()` legs from `complete`, and do not re-`play()` from an `animationcomplete` handler.
-- **`gameView.raycast(x0, y0, x1, y1, groups)`** (2026-08-19): nearest hit as `{ x, y, distance, group, sprite, normal }`, or `null`. Line of sight, ledge probes and hitscan no longer need an invisible probe sprite — but it is a discrete query, not something to poll every frame.
-- **Game-clock timers** (2026-08-19): `gameView.after(ms, cb)` / `every(ms, cb)` / `cancelTimer(id)` obey `timeScale` and pause with the render loop. Spawn waves and AI ticks belong here, not in `setTimeout`.
-- **`scrollFactor`** (2026-08-19): per-sprite parallax against camera travel. A background layer is one property, not a hand-scrolled pair of copies.
-- **`blend: 'multiply'` and `'screen'`** (2026-08-19) join `'normal'` and `'add'`, on sprites and emitters alike.
-- **`gameView.findPath(from, to, options)`** (2026-08-20): grid A* around the sprites carrying a `collisionGroup`, returning waypoints ready for `followPath` — the Godot `AStar2D` / GameMaker `mp_grid` equivalent. Tap-to-walk and chasing AI route around obstacles natively now; hand-authored waypoint arrays and straight-line walking are the old workaround. Discrete like `raycast`: taps and AI timers, not per frame.
-- **Text word wrap** (2026-08-23): `maxWidth` on a text sprite breaks lines on word boundaries and re-wraps whenever `text` changes, so a dialog box is one long string instead of hand-broken `\n` lines. The width is in font-space px, before `scale`. Do not write a JS line-breaker any more.
-- **`hitboxScaleX` / `hitboxScaleY`** (2026-08-23): per-axis corrections multiplied on top of `hitboxScale`, for art that fills its frame by a different fraction on each axis. The old workaround — settling for one compromise scale, or padding the frame so a single number fits — is obsolete.
-- **`spriteSheet.unload()` / `font.unload()`** (2026-08-23): frees a GL texture on the next frame instead of holding it until the context dies. Level streaming no longer needs a fresh window to reclaim GPU memory. Permanent — it is not a cache eviction.
-- **LiveView reloads retire the previous generation** (2026-08-23): stale render loops, the old `SoundPool`, `MediaPlayer`s and audio proxies are shut down by the module itself. Do not write your own reload guard, and do not read a scene stuttering after several reloads as an engine limit — it dates the build.
-- **`sprite.attachTo(target, { offsetX, offsetY, rotate })` / `detach()`** (2026-08-26): a sprite pinned to another sprite, resolved natively after physics and before collisions. Name tags, health bars, shadows, turrets and hitboxes that must sit on a moving body stop needing a per-frame JS copy of `x`/`y` — which is what everyone wrote before, one bridge round trip per tag per tick, always a frame late. Chains, `rotate: true` for an offset that swings with the target, automatic conversion between world and `screenFixed` space, and recursive removal so a tag never outlives its owner. Later the same day the target's opacity started multiplying into attached sprites, so fading an owner fades its tags without touching their own `opacity`. It is not full parenting: position, rotation and opacity are inherited, `scale`, `visible`, the flips and `tintColor` are not.
-- **Names and percentages on the numeric properties** (2026-08-26): every ratio the engine exposes also accepts `'55%'`, and the anchors accept `'left'`, `'bottom-right'`, `'center'`. Purely additive — numbers are untouched — and it retires the habit of a comment explaining what `anchorY: 1` plus `hitboxScaleY: 0.55` was supposed to mean. Only ratios: coordinates, sizes, degrees, speeds and the car model's `grip`/`drag` stay numeric.
-- **Shape-aware solids and circle-body physics** (2026-08-27, the `0.5.0` bump): the solid's own shape finally takes part in the resolution. `hitboxShape: 'rotatedRect'` keeps a rect turned with its sprite for solids, overlap events, `raycast`, the swept pass and the debug overlay; a circular solid deflects along the centre-to-centre normal instead of showing faces and corners it does not have; `solidMode: 'contain'` holds matched circles inside a circular boundary analytically, with no ring of wall sprites to squeeze between; `solidMode: 'push'` makes a pair of circles bodies that split the separation and trade the closing velocity; `gravityX` is a second constant acceleration on X; `linearDamping` is the rolling friction ordinary sprites never had, `drag` having only ever worked inside `carMode`; and `restitution` is read off **both** sides of a contact so a floor can supply the bounce. Every one of them defaults to today's behaviour, so nothing that exists moves differently. The workarounds this retires are the expensive ones: a ring of wall segments around a drum, a JS loop separating balls by hand, `velocityX -= k` on a timer for wind, and stepped rectangles for a single ramp.
-
-
-## Checking the current state
-
-This file describes upstream `main` at `ee69056` on 2026-08-27 — a moving target: the fourteen dated entries in "Already shipped" below all landed between 2026-08-18 and 2026-08-27, and the manifest tracks almost none of it precisely (`0.3.0` → `0.4.0` on 2026-08-20, after nine of them; word wrap, the per-axis hitbox, `unload()` and the LiveView lifecycle landed on 2026-08-23, then `attachTo`, its inherited opacity and the named values all on 2026-08-26, with the number unchanged, before `0.5.0` on 2026-08-27 finally carried a feature set of its own). `attachTo` was the first entry to move *out* of the "not available" table rather than simply appearing in the shipped list — and it moved twice in one day, since opacity inheritance landed hours after the feature. Slopes moved the next day, and moved **partly**: the geometry shipped and the platformer feel did not, which is the shape most of this table will take from here on. A planned item can land partly done and then grow: read what a row does not cover before treating it as solved, and check the date before treating it as final. 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.
+| `gameView.panTo(x, y, options)` | Planned | Tween an invisible sprite, follow it for the cutscene, then follow the player again |
+| Full `sprite.parent` transform inheritance | Partial | `attachTo()` supplies position, optional rotation, and inherited opacity. Scale, visibility, flips, tint, hit-test hierarchy, y-sort hierarchy, and a `parent` property do not exist |
+| Native joystick/d-pad binding | Planned | Use overlaid Titanium controls that write native motion/input properties on `touchstart`/`touchend`; sibling views support simultaneous touches |
+| Gamepad support | Planned | Touch input only unless the app adds its own native integration |
+| Complete platformer slopes | Partial | `rotatedRect` geometry, normals, rider carrying, and sliding work. Smooth uphill walking, contact-only surface friction, and connected terrain are not implemented |
+| Tile animation | Planned TileLayer follow-up | Change ids deliberately or use sprites for the animated cells; there is no per-id native frame cycle |
+| `raycast()` against TileLayer cells | Planned TileLayer follow-up | Use sprite colliders for ray-visible obstacles or grid/cell queries appropriate to the game |
+| Tile trigger events (`collision`/`collisionend` for water/lava) | Planned TileLayer follow-up | Use sparse invisible trigger sprites or map the mover/world point to cells on a coarse decision/event path |
+| One-call Tiled loader for tilesets and multiple layers | Planned TileLayer follow-up | Parse the exported JSON in app code and create one TileLayer per layer/tileset |
+| Per-frame animation events | Planned | Split an action into short non-looping animations and react to `animationcomplete`, or use an engine timer aligned to a deliberate cadence |
+| Ping-pong, repeat/yoyo, random animation offset, per-sprite animation speed | Planned | Author ping-pong frames or re-launch a tween from `complete`; avoid a JS per-frame loop |
+| `playbackRate`, pitch jitter, stereo pan, `fadeTo()` | Planned | Current sound API is `volume`, `loop`, `play`, `pause`, `stop`; use prepared variants or a game-clock volume cadence when necessary |
+| TypeScript declarations | Planned | No upstream `ti.game.d.ts` exists |
+| Aseprite JSON import | Planned | SpriteSheet atlases support TexturePacker JSON hash/array formats |
+| Tweening `width`, `height`, or `tintColor` | Not implemented | Tween scale/opacity/glowOpacity; other properties are instant writes |
+| A GameView-level `stop()` | Already covered differently | `timeScale = 0` freezes engine ticks while rendering/touch continue; `pause()` stops the render loop |
+| Standard Titanium touch events on GameView | By design | Use GameView `press`/`tap`/`release`, sprite events, or Titanium views over the canvas |
+| A per-frame JS event | Deliberately absent | React to discrete events and use native movement; coarse `every()` calls are for decisions, not motion |
+
+## Already shipped — do not recreate in JS
+
+- Native `TileLayer`: visible-cell drawing, strings/flat/nested data, Tiled GID offset, solid/one-way cells, live edits, cell lookup, parallax, tint/opacity, and `findPath` participation.
+- Debug object form, screen-space performance HUD, optional bitmap `hudFont`, and the opt-in `performance` event.
+- Camera follow on both axes, bounds, smoothing, zoom, shake, fullscreen tint/glitch, and per-object `scrollFactor`.
+- Text/Font sprites, word wrap, `screenFixed`, attachment, named anchors, percentage ratios, and explicit sheet/font `unload()`.
+- Sprite paths, animation chaining, raycasts, A*, game-clock timers, collision exit, swept movers, and four blend modes.
+- Shape-aware solids: circle and rotated-rect geometry, one-way platforms, carried riders, containment, bilateral circle push, two-sided restitution, `gravityX`, and `linearDamping`.
+- Native particles, ropes, effect/music sound backends, car physics, thrust, drag/pinch/rotate, and multi-touch sprites.
+
+## Deliberately out of scope upstream
+
+- Full 2D lighting/shadows.
+- Skeletal animation such as Spine.
+- Box2D-class rigid-body physics: masses, joints, torque, compound bodies, frictional contacts, spin, iterative stacking.
+- General render-to-texture. The internal fullscreen camera effect is not a public render-target API.
+
+## Checking a moving target
+
+The manifest remains `0.5.0` across shape-aware solids, the HUD, and TileLayer, so the version cannot prove a feature exists. Prefer the build commit/date and safe feature probes such as `typeof Game.createTileLayer === 'function'`. Read a property before writing it; Kroll can preserve unknown writes on a proxy.
+
+Before claiming an item is still absent, re-check upstream `TODO.md`, `README.md`, both platform proxies, and the examples. Source code wins over prose when they disagree.

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

@@ -0,0 +1,125 @@
+# Native tile maps
+
+Verified against `ti.game@d587081`: upstream `README.md` § Tile maps, `example/tilemap.js`, both `TileLayerProxy` implementations, both native `TileLayer` engines, scene collision, and `Pathfinder`.
+
+Use `Game.createTileLayer()` for a large or mostly static grid. The engine stores the whole map but renders only cells inside the camera, batches the layer through one sheet, checks only collision cells under a mover, and feeds solid cells into `findPath`. A small map whose tiles need independent sprite behavior can still use sprites; `topdown.js` is a 16×12 example of that older pattern.
+
+## Create a layer
+
+```javascript
+const tileSheet = Game.createSpriteSheet({
+	image: 'assets/tiles.png',
+	frameWidth: 16,
+	frameHeight: 16,
+	smoothing: false
+});
+
+const ground = Game.createTileLayer({
+	sheet: tileSheet,
+	tileWidth: 32,
+	tileHeight: 32,
+	data: [
+		'WWWWWW',
+		'W....W',
+		'W.FP.W',
+		'WWWWWW'
+	],
+	legend: { W: 3, '.': 0, F: 1, P: 2 },
+	collisionGroup: 'water',
+	solid: ['W'],
+	oneWay: [],
+	zIndex: 0
+});
+
+gameView.add(ground);
+```
+
+`data` accepts nested numeric rows, strings decoded through `legend`, or a flat row-major array accompanied by `cols` and optionally `rows`. Uneven nested rows are padded with empty cells. Negative/unlisted values are empty.
+
+For Tiled JSON, pass the layer data with `cols: map.width`, `rows: map.height`, and the tileset's `firstgid` as `firstGid`. GID 0 becomes empty when `firstGid > 0`, and the three flip bits are stripped. The current renderer does not reproduce Tiled's flip transforms; it resolves the underlying frame id.
+
+## Portable property timing
+
+The upstream README says every property is live, but the native bindings differ. Use the portable contract below:
+
+| Timing | Properties |
+| --- | --- |
+| Creation-time for cross-platform code | `legend`, `firstGid`, `cols`, `rows` |
+| Live on Android and iOS | `data`, `solid`, `oneWay`, `sheet`, `tileWidth`, `tileHeight`, `x`, `y`, `zIndex`, `visible`, `opacity`, `scrollFactor`, `tintColor`, `collisionGroup`, `restitution`, `debug` |
+| Read-only | `width`, `height`; `cols` and `rows` reflect the current parsed grid |
+
+iOS rebuilds the grid when `legend`, `firstGid`, `cols`, or `rows` is assigned later. Android exposes no setters for those four. Supplying them in the factory keeps both platforms aligned.
+
+`opacity`, `scrollFactor`, and `restitution` accept ratio numbers or percentage strings. `tileWidth`/`tileHeight`, coordinates, and dimensions do not.
+
+## Collision cells
+
+Give the layer a `collisionGroup`; movers list that group in `solidWith`:
+
+```javascript
+const player = Game.createSprite({
+	sheet: playerSheet,
+	solidWith: ['water'],
+	hitboxScale: '65%'
+});
+```
+
+- `solid` ids block from every side.
+- `oneWay` ids catch a mover falling onto the top and do not block sideways or upward movement.
+- Rect, circle, and swept movers are supported.
+- Layer `restitution` mixes with the mover like restitution on a solid sprite.
+- A successful top landing sets `onGround` and fires `land`. A tile cell is not a sprite, so the event has no `other` object.
+- Adjacent solid cells suppress their shared internal faces, avoiding seams while sliding along a floor.
+
+Tile cells participate in **solid resolution**, not overlap events. `collidesWith` does not produce `collision`/`collisionend` for trigger tiles yet. `raycast()` also does not inspect tile cells. See [roadmap.md](roadmap.md) before designing those behaviors.
+
+## Read and edit cells
+
+| Method | Result |
+| --- | --- |
+| `getTile(col, row)` | Frame id, or `-1` when empty/outside |
+| `setTile(col, row, id)` | Replaces the art; solid/one-way flags are recalculated from the id lists |
+| `isBlocked(col, row)` | Whether the cell is fully solid; one-way cells return `false` |
+| `setBlocked(col, row, bool)` | Overrides the cell as fully solid or non-solid without changing its art |
+| `tileAt(x, y)` | World point → `{ col, row, tile, solid, x, y }`, or `null` outside |
+| `cellAt(col, row)` | Cell → the same structure; `x`/`y` are the cell center |
+
+`setBlocked()` is a cell-level override. Replacing `data`, `solid`, or `oneWay` rebuilds flags and should be treated as ending those overrides.
+
+## Tap-to-walk across a large map
+
+`findPath()` includes fully solid cells when the layer's `collisionGroup` appears in `groups`. One-way cells remain walkable in the path grid.
+
+```javascript
+function walkTo(player, destination, tileLayer, gameView) {
+	const start = { x: player.x, y: player.y };
+	const reach = tileLayer.tileWidth * 20;
+	const path = gameView.findPath(start, destination, {
+		cellSize: tileLayer.tileWidth,
+		groups: [tileLayer.collisionGroup],
+		clearance: player.width * 0.3,
+		bounds: {
+			minX: Math.max(tileLayer.x, start.x - reach),
+			minY: Math.max(tileLayer.y, start.y - reach),
+			maxX: Math.min(tileLayer.x + tileLayer.width, start.x + reach),
+			maxY: Math.min(tileLayer.y + tileLayer.height, start.y + reach)
+		}
+	});
+
+	if (path && path.length >= 2) {
+		player.followPath(path, { speed: tileLayer.tileWidth * 4 });
+	}
+}
+```
+
+Bound the per-query A* search to the useful neighborhood. The layer can be enormous without rendering cost, but `findPath()` still builds a grid for the requested bounds on the calling thread.
+
+## Layering and performance
+
+- Stack separate layers for ground, decoration, and foreground. Layers draw below sprites at the same `zIndex`.
+- Share one sheet when layers use the same tileset.
+- Use `scrollFactor` for parallax layers; collision remains in world coordinates, just as with sprites.
+- Use `visible: false` to exclude the layer from drawing and collision.
+- Toggle `layer.debug` for one layer or `gameView.debug = { hitbox: true }` for every layer's solid cells.
+- Use the performance HUD while scrolling: map dimensions should not change visible-cell draw cost.
+