@maccesar/titools 4.6.1 → 4.7.0

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

@@ -0,0 +1,333 @@
+# 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.
+
+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).
+
+## Contents
+
+- [Module](#module)
+- [GameView](#gameview)
+- [SpriteSheet](#spritesheet)
+- [Sprite](#sprite)
+- [Sound](#sound)
+- [Emitter](#emitter)
+- [Rope](#rope)
+- [Events at a glance](#events-at-a-glance)
+- [Gotchas the property tables do not show](#gotchas-the-property-tables-do-not-show)
+
+## Module
+
+```javascript
+const Game = require('ti.game');
+```
+
+| Factory | Returns |
+| --- | --- |
+| `Game.createGameView(options)` | GameView — the canvas, a Titanium view |
+| `Game.createSpriteSheet(options)` | SpriteSheet — a texture cut into frames |
+| `Game.createSprite(options)` | Sprite |
+| `Game.createSound(options)` | Sound |
+| `Game.createEmitter(options)` | Emitter — particle system |
+| `Game.createRope(options)` | Rope — Verlet chain |
+
+Easing constants (for `sprite.animate({ easing })`): `Game.EASE_LINEAR`, `Game.EASE_IN`, `Game.EASE_OUT`, `Game.EASE_IN_OUT`, `Game.EASE_BOUNCE`, `Game.EASE_ELASTIC`.
+
+## GameView
+
+A normal Titanium view — add it to a window or any container, size it with the usual Titanium properties.
+
+| Member | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `add(object)` / `add([objects])` | method | — | Accepts Sprite, Emitter or Rope. An array crosses the bridge once and is committed under a single native scene lock — build a level into an array and add it in one call |
+| `remove(object)` | method | — | Remove one object from the scene |
+| `removeAllSprites()` | method | — | Clear the whole scene |
+| `pause()` / `resume()` | method | — | Render loop control. The activity/app lifecycle already pauses and resumes automatically |
+| `backgroundColor` | string | — | GL clear color |
+| `maxFps` | int | `0` | Frame cap. `60` stops 120 Hz ProMotion displays from doubling render work; `0` = display refresh rate |
+| `timeScale` | float | `1` | Global multiplier for everything the engine ticks: physics, sheet animations, tweens, particles, camera. `0.5` = slow motion, `0` freezes the scene while rendering and touch keep running (pause menus, hit-stop) |
+| `surfaceWidth` / `surfaceHeight` | int | — | Read-only surface size in pixels |
+| `cameraX` / `cameraY` | float | `0` | World-space offset of the view |
+| `cameraScale` | float | `1` | Zoom, anchored on the view center |
+| `cameraBounds` | dict / null | `null` | `{ minX, minY, maxX, maxY }` world rect the visible area is clamped into |
+| `follow(sprite, options)` | method | — | Native dead-zone follow, see below |
+| `stopFollow()` | method | — | Stop following; the camera stays where it is |
+| `shake({ strength, duration })` | method | `12` px, `400` ms | Detuned-sine rumble on the projection only — follow, bounds and touch mapping are unaffected |
+| `cameraEffect` | string | `'none'` | Fullscreen shader pass: `'none'`, `'tint'`, `'glitch'`. With `'none'` the extra pass is skipped entirely |
+| `cameraTint` | string | — | Color for the `'tint'` effect, e.g. `'#4f8'` (night vision, poison, flashback) |
+| `cameraEffectIntensity` | float | `1` | 0..1 — tint mix or glitch amount |
+| `debug` | bool | `false` | Draw collision shapes for every sprite in the scene |
+
+Events: `press`, `tap`, `release` — fired for **every** touch anywhere on the view, with payload `x`, `y` in scene coordinates (tap-anywhere controls, flappy-style). And `resize` with payload `width`, `height` — the real surface size in pixels.
+
+### `follow(sprite, options)`
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `topMargin` | `0.33` | Vertical dead-zone top edge, as a fraction of visible height |
+| `bottomMargin` | `0.7` | Vertical dead-zone bottom edge |
+| `leftMargin` | `0.35` when horizontal follow is enabled | Horizontal dead-zone left edge |
+| `rightMargin` | `0.65` | Horizontal dead-zone right edge |
+| `smoothing` | `0` | 0..1. `0` snaps; otherwise the camera eases by that fraction of the remaining distance per 1/60 s |
+| `maxY` | `0` | The camera's `cameraY` never goes past this. Default `0` suits a platformer whose start view is the bottom of the level — for a free-roaming world pass the world height |
+
+Vertical follow is always on. **Horizontal follow is off until you pass `leftMargin` or `rightMargin`.**
+
+Each call **resets every option to its default** before applying what you passed. Calling `follow(sprite)` with no options after configuring it wipes the configuration.
+
+## SpriteSheet
+
+Create one sheet per texture and share it across every sprite that uses it — sprites sharing a sheet batch into a single draw call.
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `image` | — | Path to the texture, relative to the resources root (`'assets/hero.png'`) |
+| `frameWidth` / `frameHeight` | — | Grid mode: cell size in source pixels. Frames are numbered left-to-right, top-to-bottom, starting at 0 |
+| `atlas` | — | TexturePacker JSON (hash or array format) instead of a grid |
+| `smoothing` | `true` | `false` = GL_NEAREST, the pixel-art setting |
+| `repeat` | `false` | GL_REPEAT wrap, required by sprites using `tileRepeat`. Needs power-of-two texture dimensions |
+
+| Member | Notes |
+| --- | --- |
+| `frameCount` | Number of frames. `0` until the texture has loaded, for grid sheets |
+| `frameNames` | Sorted frame names — atlas sheets only |
+| `frameIndex(name)` | Index for an atlas frame name, `-1` if unknown |
+
+Textures upload to the GPU lazily on first use, from the render thread, and are re-created automatically after an EGL context loss.
+
+## Sprite
+
+### Transform
+
+| Property | Default | Notes |
+| --- | --- | --- |
+| `x`, `y` | `0` | Position of the **anchor**, not the top-left corner |
+| `width`, `height` | frame size | `0` means "use the sheet frame size" |
+| `scale` | `1` | Write-only convenience that sets both axes |
+| `scaleX`, `scaleY` | `1` | Negative values flip *and* affect physics/hit testing — prefer `flipX`/`flipY` for pure mirroring |
+| `rotation` | `0` | Degrees, clockwise |
+| `anchorX`, `anchorY` | `0.5` | `0/0` = top-left, `0.5/0.5` = center, `0.5/1` = bottom-center (useful for feet) |
+| `opacity` | `1` | |
+| `visible` | `true` | `false` = no render **and no collision** — the pooling idiom |
+| `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 |
+| `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
+
+| Property | Default | Notes |
+| --- | --- | --- |
+| `sheet` | — | The SpriteSheet |
+| `frame` | `0` | Current frame index; writing it stops nothing, it just shows that frame |
+| `animations` | — | Named definitions: `{ walk: { frames: [1, 2], fps: 6, loop: true } }` |
+| `animation` | — | Read-only name of the current animation. **Keeps its value after `stop()`** — track "is walking" yourself if you need it |
+| `tileRepeat` | `false` | `true` / `'x'` / `'y'` — tile the frame at native size instead of stretching. Needs `repeat: true` on the sheet and a frame spanning the whole texture |
+
+An animation definition takes `frames` (array of indices), `fps`, `loop`, and an optional `frame` — the sheet frame to show once a non-looping animation finishes (default: hold the last animation frame).
+
+Methods: `play(name)` starts an animation, `stop()` halts it on the current frame.
+
+### Touch
+
+| Property | Default | Notes |
+| --- | --- | --- |
+| `draggable` | `false` | Native drag & drop — the sprite moves on the UI thread, JS only hears milestones |
+| `pinchable` | `false` | Two-finger scale |
+| `rotatable` | `false` | Two-finger rotate |
+| `touchEnabled` | `true` | `false` = touches pass through to sprites underneath |
+
+Hit-testing runs against the transformed shape (rotation and scale included), topmost first, and is multi-touch: each finger runs its own gesture and a sprite belongs to at most one finger. A second finger landing on empty space — or on the sprite already held — pinches/rotates that sprite instead, per its flags.
+
+### Physics
+
+| Property | Default | Notes |
+| --- | --- | --- |
+| `velocityX`, `velocityY` | `0` | px/s |
+| `gravity` | `0` | px/s², added to `velocityY`. Per sprite — there is no global gravity |
+| `maxSpeed` | `500` | px/s cap |
+| `angularVelocity` | `0` | deg/s |
+| `thrust` | `0` | px/s² along the current heading (Newtonian flight) |
+| `wrapAround` | `false` | Re-enter from the opposite screen edge (Asteroids) |
+| `wrapX`, `wrapShift` | `0` | Scroll looping: at `x < wrapX`, add `wrapShift`. Two screen-wide copies with `{ wrapX: -W/2, wrapShift: 2*W }` and a negative `velocityX` make a seamless parallax layer with no JS in the loop |
+
+### Solids
+
+| Property | Default | Notes |
+| --- | --- | --- |
+| `solidWith` | — | Array of group names that block this sprite. The engine pushes it out along the axis of least penetration |
+| `onGround` | `false` | Read-only. Gate jumps on it |
+| `restitution` | `0` | 0..1 bounce factor against solids |
+| `oneWay` | `false` | On the **solid**: pass-through except for landings on its top edge — classic platformer floors |
+| `carryRiders` | `true` | On the **solid**: a moving solid carries whoever stands on it (velocity, tweens, idle wobble — wrap teleports excluded). Set `false` for world-scroll terrain that moves while the player is meant to stay put |
+
+### Collision
+
+| Property | Default | Notes |
+| --- | --- | --- |
+| `collisionGroup` | — | The tag *this* sprite carries |
+| `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 |
+| `debug` | `false` | Draw this sprite's shapes: green = collision AABB, blue = touch bounds, orange dot = anchor |
+
+### Car (`carMode`)
+
+| Property | Default | Notes |
+| --- | --- | --- |
+| `carMode` | `false` | Enables the arcade car model |
+| `throttle` | `0` | `-1` (brake/reverse) .. `1` (gas) |
+| `steering` | `0` | `-1` (left) .. `1` (right) |
+| `enginePower` | `600` | Forward acceleration, px/s² |
+| `maxSpeed` | `500` | px/s; reverse caps at 40% |
+| `turnRate` | `200` | deg/s at full steering and speed |
+| `grip` | `4` | Lateral friction, 1/s. **Lower = more drift** |
+| `drag` | `0.6` | Longitudinal friction, 1/s |
+| `skidMarks` | `false` | Fading rubber trails while drifting |
+| `skidThreshold` | `0` | Lateral px/s that counts as drifting |
+| `drifting` | `false` | Read-only — handy for triggering tire sounds |
+
+Drift is emergent, not a mode: lateral grip is finite, so hard cornering at speed keeps sideways momentum.
+
+### Idle wobble
+
+| Property | Default | Notes |
+| --- | --- | --- |
+| `idleAnimation` | `false` | Gentle organic sway around the base transform |
+| `idleRotation` | `3` | Degrees |
+| `idleMovement` | `4` | px |
+| `idleSpeed` | `1` | Frequency multiplier |
+
+Every sprite gets its own phase, and the wobble unwinds exactly when disabled. Turn it **off before tweening a sprite to a position where alignment matters** — tweens write absolute values, so a wobbling sprite lands with a leftover offset.
+
+### Color
+
+| Property | Default | Notes |
+| --- | --- | --- |
+| `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 |
+| `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` |
+
+### Methods
+
+| Method | Notes |
+| --- | --- |
+| `play(name)` | Start a named animation |
+| `stop()` | Stop the animation on the current frame |
+| `animate(options)` | Native tween, fires `complete` |
+| `clearTweens()` | Cancel tweens in progress — call before starting a replacement tween |
+| `flash(color, duration)` | Fills the sprite's silhouette with `color` (default white) and fades it out over `duration` ms (default 150). The classic damage/invincibility flash that a multiplicative `tintColor` cannot do |
+
+`animate()` accepts exactly these keys — anything else is silently ignored: `x`, `y`, `scale`, `scaleX`, `scaleY`, `rotation`, `opacity`, `glowOpacity`, `duration` (ms), `delay` (ms), `easing`, `frame` (the sheet frame to set once the tween finishes). Chain moves by re-calling `animate` from the `complete` handler — that is how patrols and ping-pong motions are built.
+
+### Sprite events
+
+| Event | Payload | Fires |
+| --- | --- | --- |
+| `press` | `x`, `y`, `touchX`, `touchY` | Finger down on the sprite |
+| `release` | `x`, `y` | Finger up or cancel after a press (after `tap`/`dragend`) |
+| `tap` | `x`, `y`, `touchX`, `touchY` | Quick touch without movement |
+| `dragstart` | `x`, `y` | Drag exceeded touch slop |
+| `drag` | `x`, `y` | Throttled to ~10 Hz while dragging |
+| `dragend` | `x`, `y` | Finger lifted; the sprite has already moved natively |
+| `pinch` | `scaleX`, `scaleY` | While two-finger scaling |
+| `rotate` | `rotation` | While two-finger rotating |
+| `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 |
+| `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) |
+
+## Sound
+
+```javascript
+const jump = Game.createSound({ url: 'assets/jump.wav', volume: 0.8 });
+jump.play();   // fire-and-forget; rapid plays overlap
+
+const music = Game.createSound({ url: 'assets/theme.mp3', music: true, loop: true });
+music.play();
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `url` | required | App resource or file path |
+| `volume` | `1` | 0..1, live |
+| `loop` | `false` | Live |
+| `music` | `false` | Chooses the backend — **set at creation, not changeable later** |
+
+Effect mode (the default) is built for low latency: a shared `SoundPool` on Android, a small pool of preloaded players on iOS. Call `play()` from any handler and repeated plays overlap instead of cutting each other off. `music: true` picks the streaming backend (`MediaPlayer` / `AVAudioPlayer`) for longer tracks; music pauses when the app backgrounds and resumes with it.
+
+Methods: `play()`, `pause()` (resumes where it stopped), `stop()` (rewinds to the beginning). Formats: WAV, MP3, OGG on Android; WAV, MP3, M4A on iOS.
+
+## Emitter
+
+Add and remove like a sprite: `gameView.add(emitter)` / `remove(emitter)`. Spawning, integration, fading and drawing all run in the native loop — JS only writes configuration and calls `emit()`.
+
+| Property | Default | Notes |
+| --- | --- | --- |
+| `sheet`, `frame` | — | All particles share one frame, so an emitter renders as a single batch run |
+| `x`, `y` | `0` | Ignored while `target` is set |
+| `target` | — | Sprite to follow. Set to `null` to detach |
+| `offsetX`, `offsetY` | `0` | Offset from the target (rear wheels, exhaust) |
+| `zIndex` | `0` | Emitters draw above sprites of the same z |
+| `rate` | `0` | Particles per second while `emitting`. Leave at `0` for burst-only emitters |
+| `emitting` | `true` | Toggle the continuous stream |
+| `lifetime` | `800` | ms |
+| `speed` | `100` | px/s, randomized between 50% and 100% so bursts do not form perfect rings |
+| `angle` | `0` | Base direction: `0` = up, clockwise degrees |
+| `spread` | `360` | Cone width in degrees |
+| `gravity` | `0` | px/s² applied to particle velocity |
+| `size` | `0` | Base particle width in px; `0` = frame size |
+| `startScale` / `endScale` | `1` / `1` | Interpolated over `lifetime` |
+| `startOpacity` / `endOpacity` | `1` / `0` | Interpolated over `lifetime` |
+| `tint` | white | Tint white particle art at runtime — one tiny texture covers every color in the game |
+| `blend` | `'normal'` | `'add'` for fire, sparks and magic |
+| `maxParticles` | `200` | Pool size, hard cap 1000 |
+
+Methods: `emit(n)` fires a one-shot burst on top of `rate`; `clear()` kills all live particles.
+
+## Rope
+
+A native Verlet chain: integration and distance constraints run in the game loop, segments render as quads oriented along the rope (one sheet frame, one batch run).
+
+| Property | Default | Notes |
+| --- | --- | --- |
+| `sheet`, `frame` | — | One frame, textured along each link |
+| `segments` | `10` | Number of links |
+| `segmentLength` | `30` | px |
+| `thickness` | `10` | Drawn width in px |
+| `gravity` | `1500` | px/s² |
+| `damping` | `0.98` | Velocity kept per step |
+| `iterations` | `3` | Constraint passes per frame — higher is stiffer and costlier |
+| `head` | — | Sprite the head is pinned to. Without it, the head anchors at `x`/`y` |
+| `tail` | — | Sprite pinned to the other end (hanging weights, bridges) |
+| `x`, `y` | `0` | Fixed head anchor when no `head` sprite is set |
+| `maxLength` | `0` | `0` = off. With a `tail`, turns the rope into a tether: when head→tail distance exceeds it, the sprites are pulled back onto the limit each frame and their outward velocity is cancelled — a falling weight snaps taut and swings like a pendulum instead of stretching |
+| `zIndex` | `0` | |
+| `visible` | `true` | |
+| `endX`, `endY` | — | Read-only live position of the loose end (grappling-hook tips) |
+
+The tether yields at the end no finger owns: with a fixed head anchor the tail sprite is simply leashed, but with sprites on both ends you can drag either one and the other is towed once the rope goes taut.
+
+## Events at a glance
+
+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
+
+## 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.
+- **`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.
+- **`visible: false` removes a sprite from collision too.** That is why pooled bullets and rocks use it instead of removing them from the scene.
+- **`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.
+- **`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.

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

@@ -0,0 +1,280 @@
+# Setting up a ti.game project
+
+Installing the module, wiring it into Classic and Alloy projects, organizing art and sound, and the lifecycle work the engine does not do for you.
+
+## Contents
+
+- [Install the module](#install-the-module)
+- [Classic projects](#classic-projects)
+- [Alloy projects](#alloy-projects)
+- [Where art and sound live](#where-art-and-sound-live)
+- [Sprite sheets and atlases](#sprite-sheets-and-atlases)
+- [Lifecycle and cleanup](#lifecycle-and-cleanup)
+- [Debugging and tuning](#debugging-and-tuning)
+- [Platform differences](#platform-differences)
+
+## Install the module
+
+There is no registry and no `ti module install` command — Titanium modules are zips you drop into a project. Grab the platform zips from the module's `dist/` folders (or build them yourself) and put them where the CLI looks:
+
+**Project-local** (recommended — the version travels with the repo):
+
+```
+modules/
+├── android/ti.game/0.3.0/
+└── iphone/ti.game/0.3.0/
+```
+
+Unzipping the module zip at the project root creates exactly that layout.
+
+**Global** (shared across projects): `~/Library/Application Support/Titanium/modules/<platform>/ti.game/<version>/`.
+
+Then declare it in `tiapp.xml`. The iOS platform key is `iphone`, not `ios`:
+
+```xml
+<modules>
+  <module platform="android" version="0.3.0">ti.game</module>
+  <module platform="iphone" version="0.3.0">ti.game</module>
+</modules>
+```
+
+Pinning `version` is worth the extra attribute: with two module versions installed side by side, an unpinned entry silently picks the highest one.
+
+Building the module from source:
+
+```bash
+cd android
+ti build -p android --build-only    # → android/dist/ti.game-android-<version>.zip
+ti build -p ios --build-only        # macOS only → ios/dist/ti.game-iphone-<version>.zip
+```
+
+## 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:
+
+```javascript
+// Resources/flappy.js
+const Game = require('ti.game');
+
+module.exports = function () {
+	const win = Ti.UI.createWindow({ backgroundColor: '#000', theme: 'Theme.Titanium.DayNight.NoTitleBar' });
+	const gameView = Game.createGameView({ backgroundColor: '#8ed8f8' });
+	// ... build the game
+	win.add(gameView);
+	win.open();
+};
+```
+
+```javascript
+// Resources/app.js
+require('/flappy')();
+```
+
+One module per screen or per game mode keeps things separable, and a window per mode means closing it tears the scene down.
+
+## Alloy projects
+
+Two ways to get a GameView on screen. Both work; pick by whether the scene is permanent or comes and goes.
+
+### A: declare it in XML (`<Module>`)
+
+The standard Alloy element for a native module view. `method` names the factory to call and every attribute is passed as a creation property.
+
+```xml
+<!-- app/views/index.xml -->
+<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>
+```
+
+```javascript
+// app/controllers/index.js
+const Game = require('ti.game');
+
+const heroSheet = Game.createSpriteSheet({ image: 'hero.png', frameWidth: 64, frameHeight: 64 });
+
+let initialized = false;
+
+function onOpen() {
+	$.gameView.addEventListener('resize', onResize);
+}
+
+function onResize(e) {
+	if (initialized) {
+		return;
+	}
+	initialized = true;
+	buildLevel(e.width, e.height);
+}
+```
+
+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
+
+Preferred when the game is created and destroyed repeatedly — switching between a menu and a run, changing levels, or restarting cleanly. The XML holds a plain container and the game code owns everything inside it.
+
+```xml
+<Alloy>
+	<Window id="index" navBarHidden="true" exitOnClose="true" onOpen="onOpen" onClose="onClose">
+		<View id="menuState" />
+		<View id="gameContainer" visible="false" />
+	</Window>
+</Alloy>
+```
+
+```javascript
+// app/controllers/index.js
+const LanderGame = require('/game/LanderGame');
+
+let game = null;
+
+function startCampaign() {
+	destroyGame();
+	game = new LanderGame({ container: $.gameContainer, onExit: showMenu });
+	$.menuState.visible = false;
+	$.gameContainer.visible = true;
+}
+
+function destroyGame() {
+	if (!game) {
+		return;
+	}
+	game.destroy();
+	game = null;
+}
+
+function onClose() {
+	destroyGame();
+	$.destroy();
+}
+
+$.cleanup = onClose;
+```
+
+### Structure for anything bigger than a demo
+
+Alloy Tier 2 applies unchanged: a slim controller that owns navigation and menu state, with the game itself in `app/lib/`. A shipped layout that works:
+
+```
+app/lib/game/
+├── LanderGame.js        session orchestration and the whole JS↔native boundary
+├── TerrainGenerator.js  deterministic level geometry
+├── WorldCatalog.js      immutable world/level data
+├── AudioManager.js      owns every createSound handle
+├── GamePreferences.js   Ti.App.Properties persistence
+└── LeaderboardStore.js  scores
+```
+
+Catalogs, generators and stores are plain modules with no Titanium UI in them, so they are unit-testable in plain Node. The one class that touches sprites is the boundary — keep it explicit and keep the rest pure.
+
+Alloy specifics worth remembering: `OS_IOS`/`OS_ANDROID` are compile-time constants (the dead branch is stripped, so an iOS-only API inside `if (OS_IOS)` never reaches an Android build), `Alloy.CFG` reads `config.json`, and `$.destroy()` releases Alloy's own bindings but knows nothing about your timers, sounds or sprites — see the cleanup section below.
+
+## Where art and sound live
+
+**Alloy**: everything under `app/assets/` is copied to the resources root, so the path in code drops the `app/assets/` prefix.
+
+| File | Referenced as |
+| --- | --- |
+| `app/assets/lander.png` | `'lander.png'` |
+| `app/assets/game/stars_far.png` | `'game/stars_far.png'` |
+| `app/assets/sounds/jump.wav` | `'sounds/jump.wav'` |
+
+**Classic**: paths are relative to `Resources/`, so `Resources/assets/hero.png` is `'assets/hero.png'`.
+
+Do not use `@2x`/`@3x` density suffixes for game art. The scene is measured in surface pixels and you size every sprite yourself from the `resize` dimensions — density variants would fight that. Ship one texture at a resolution high enough for the largest target and let the engine scale it.
+
+## Sprite sheets and atlases
+
+**Grid** — frames numbered left-to-right, top-to-bottom from 0:
+
+```javascript
+const sheet = Game.createSpriteSheet({
+	image: 'hero.png',
+	frameWidth: 64,
+	frameHeight: 64,
+	smoothing: false        // pixel art
+});
+```
+
+**TexturePacker atlas** — hash or array JSON format:
+
+```javascript
+const sheet = Game.createSpriteSheet({ image: 'hero.png', atlas: 'hero.json' });
+const runFrame = sheet.frameIndex('run_01');    // -1 if unknown
+```
+
+Atlases are the better default for hand-authored art with varied frame sizes; grids are simpler for uniform pixel art.
+
+Practical rules:
+
+- **One sheet per scene if you can manage it.** Sprites sharing a texture batch into a single draw call. The endless-runner demo even draws its crash burst from the *player's* sheet to keep the whole scene on one texture.
+- **`smoothing: false` for pixel art.** Combine with `pixelSnap: true` on moving sprites when the texel phase must stay stable.
+- **`repeat: true` for tiling.** Required by sprites using `tileRepeat`, and it needs power-of-two texture dimensions on ES 2.0 — a 512×64 street strip tiles, a 500×60 one does not.
+- **White art plus `tint`** covers every color variant of a particle or effect with one small texture.
+
+`frameCount` is `0` until a grid sheet's texture has loaded, so do not compute animation ranges from it at creation time.
+
+## 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.**
+
+A leaked `setInterval` keeps running after the window closes, keeps reading sprite properties from a dead scene and keeps the whole closure alive. A looping `createSound` keeps playing over the next screen.
+
+```javascript
+function cleanup() {
+	clearInterval(aiTimer);
+	clearTimeout(spawnTimer);
+	clearHitStop();                    // restore timeScale — a frozen scene must not persist
+	music.stop();
+	thrustSound.stop();                // looping effects too
+	listeners.forEach(({ target, eventName, handler }) => {
+		target.removeEventListener(eventName, handler);
+	});
+	gameView.pause();
+	gameView.removeAllSprites();
+}
+
+// Classic
+win.addEventListener('close', cleanup);
+
+// Alloy
+$.cleanup = cleanup;
+```
+
+Tracking listeners as you add them makes the teardown mechanical instead of a memory exercise:
+
+```javascript
+const listeners = [];
+
+function listen(target, eventName, handler) {
+	target.addEventListener(eventName, handler);
+	listeners.push({ target, eventName, handler });
+}
+```
+
+For restart-without-teardown (a retry button), `removeAllSprites()` plus rebuilding is simplest, but pooling and repositioning is cheaper: reset positions, zero velocities, `clearTweens()`, and re-`play()` the animations.
+
+## Debugging and tuning
+
+- **`debug: true` on the GameView** draws collision shapes for the whole scene; on a single sprite, only that one. Green = collision AABB with `hitboxScale` applied, blue = sprite/touch bounds, orange dot = anchor. This is the fastest way to explain a hit that should not have registered.
+- **Physics that feels wrong is usually a units problem.** Speeds are px/s and accelerations px/s², both in surface pixels — which is why the demos express them as fractions of `W` and `H`. A gravity of `20` is imperceptible; `H * 2.2` is a snappy platformer.
+- **Sprite is invisible?** Check in order: was it added to the GameView, does it have a sheet, is `width`/`height` non-zero, is it inside the surface bounds, and is its `zIndex` below a background sprite.
+- **Collision never fires?** `collisionGroup` goes on the *target*, `collidesWith` on the *mover*. Both need to be set, and `visible: false` disables collision entirely.
+- **Never scrolls / never follows?** `follow()` only does horizontal tracking when `leftMargin` or `rightMargin` is passed, and `maxY` defaults to `0`.
+- Testing: game logic that lives in plain modules (catalogs, generators, scoring, persistence) tests in Node with the built-in `node:test` runner. The scene layer needs a device — there is no headless renderer.
+
+## Platform differences
+
+The JS API is identical on Android and iOS. What differs is around it:
+
+- **`Ti.UI.createNotification` (Android Toast) does not exist on iOS.** The demos branch on `Ti.Platform.osname` and fall back to `Ti.UI.createAlertDialog`.
+- **The iOS Simulator renders at a 1x logical drawable** (its translated OpenGL path is disproportionately expensive at 3x Retina) and is noticeably slower than any real device. Real iPhone and iPad builds keep the device's native screen scale. Judge performance on device.
+- **`logicalDensityFactor` lies in the iOS Simulator** — it reports the device scale while the surface renders at 1x. Derive dp→scene units from the surface instead: `H / Ti.Platform.displayCaps.platformHeight`.
+- **Android's `touchFeedback` ripple** cannot animate over the GL canvas and logs `RippleDrawable` errors; give on-screen buttons manual `backgroundColor` feedback on `touchstart`/`touchend`.
+- **Sound formats**: WAV, MP3 and OGG on Android; WAV, MP3 and M4A on iOS. WAV for effects, MP3 for music covers both.
+- **`theme: 'Theme.Titanium.DayNight.NoTitleBar'`** on the window is the Android idiom for a fullscreen game surface; on iOS use `navBarHidden`/`statusBarHidden` (or the Alloy XML equivalents).