@maccesar/titools 4.6.1 → 4.7.0

package/README.md

@@ -6,7 +6,7 @@
 
 </div>
 
-TiTools is a Titanium SDK toolkit for AI coding assistants. It ships 8 skills — 3 opinionated (`ti-expert`, `purgetss`, `ti-ui`) plus 5 documentation-mirror skills (`ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`) — a research agent, and reference files covering Titanium architecture, API reference, native how-tos, Alloy MVC, PurgeTSS styling, and UI/UX patterns.
+TiTools is a Titanium SDK toolkit for AI coding assistants. It ships 9 skills — 4 opinionated (`ti-expert`, `purgetss`, `ti-ui`, `ti-game`) plus 5 documentation-mirror skills (`ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`) — a research agent, and reference files covering Titanium architecture, API reference, native how-tos, Alloy MVC, PurgeTSS styling, UI/UX patterns, and 2D game development with the `ti.game` module.
 
 The reference files are maintained against official documentation whenever an official source exists, so the assistant can retrieve current framework behavior instead of guessing from generic training data.
 
@@ -36,9 +36,9 @@ The fastest way to get started with Claude Code. One command to add the marketpl
 ```
 
 What you get:
-- All 3 TiTools skills (`ti-expert`, `purgetss`, `ti-ui`)
+- All 9 TiTools skills (`ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`)
 - ti-pro research agent
-- Session hook that auto-detects Titanium projects (`tiapp.xml`, Alloy, PurgeTSS)
+- Session hook that auto-detects Titanium projects (`tiapp.xml`, Alloy, PurgeTSS, `ti.game`)
 - Slash commands: `/ti-check`, `/ti-new-screen`, `/ti-audit`
 - Auto-updates via marketplace (opt-in — see note below)
 
@@ -70,7 +70,7 @@ claude   # or gemini, or codex
 ```
 
 What gets installed:
-- The 8 TiTools skills to `~/.agents/skills/`
+- The 9 TiTools skills to `~/.agents/skills/`
 - ti-pro agent for Claude Code
 - Platform symlinks for Claude Code (Gemini CLI and Codex CLI auto-discover from `~/.agents/skills/` — no symlinks needed)
 - Knowledge index in your project's `AGENTS.md`/`CLAUDE.md`/`GEMINI.md`
@@ -91,7 +91,7 @@ Why NPM?
 | **Knowledge Index** | Not included                               | Included (`titools sync`) |
 | **Auto-updates**    | Marketplace (opt-in, enable in `/plugin`)  | SessionStart hook (daily) |
 | **Slash commands**  | `/ti-check`, `/ti-new-screen`, `/ti-audit` | Same three (`~/.claude/commands/`) |
-| **Session hook**    | Auto-detects Titanium projects             | Auto-update only          |
+| **Session hook**    | Auto-detects Titanium projects (Alloy/Classic, PurgeTSS, `ti.game`) | Auto-update only          |
 
 Having both installed is fine: the CLI detects an enabled marketplace plugin and skips its own skill symlinks and command copies, so nothing shows up twice. `titools doctor` reports which channel is serving Claude Code.
 
@@ -177,6 +177,7 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
 | ti-expert    | Architecture and implementation     | Starting point for most tasks           |
 | purgetss     | Utility-first styling               | UI styling and animations               |
 | ti-ui        | UI/UX patterns                      | Complex layouts, ListViews, platform UI |
+| ti-game      | 2D games with the `ti.game` module  | Sprites, physics, collisions, particles, camera |
 | ti-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    |
@@ -184,7 +185,8 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
 | alloy-howtos | Alloy CLI, configuration, debugging | alloy.jmk, config.json, custom XML tags |
 
 Notes:
-- The first three (`ti-expert`, `purgetss`, `ti-ui`) are opinionated workflow skills reflecting TiTools' Titanium conventions.
+- The first four (`ti-expert`, `purgetss`, `ti-ui`, `ti-game`) are opinionated workflow skills reflecting TiTools' Titanium conventions.
+- `ti-game` documents the `ti.game` native module (2D sprite engine on OpenGL ES 2.0, Android and iOS). Its API reference was verified against the module source; it applies to Alloy and Classic projects alike and does not depend on PurgeTSS.
 - The latter five are documentation-mirror skills sourced from the official Titanium SDK docs (`tidev/titanium-docs`) and audited against them via the internal `titools-skill-auditor`.
 - `purgetss` reference files are audited against the official PurgeTSS documentation, but its workflow conventions are opinionated.
 
@@ -254,9 +256,11 @@ These commands automatically invoke the relevant skills:
 The plugin includes a session start hook that auto-detects Titanium projects. When you open Claude Code in a directory with `tiapp.xml`, it automatically reports:
 
 ```
-Titanium Alloy + PurgeTSS project detected. TiTools skills are available and MUST be used...
+Titanium Alloy + PurgeTSS + ti.game project detected. TiTools skills are available and MUST be used...
 ```
 
+It reports Alloy vs Classic, whether PurgeTSS is configured, and whether the project declares the `ti.game` module — a game project also gets a line pointing at the `ti-game` skill.
+
 This ensures Claude knows it's a Titanium project from the first prompt, preventing it from writing generic code.
 
 ---
@@ -285,6 +289,7 @@ All skills include automatic project detection to ensure compatibility:
 | purgetss  | PurgeTSS installation | Checks for `purgetss/` folder, `config.cjs`, `utilities.tss`  |
 | ti-expert | Alloy vs Classic      | Checks for `app/` (Alloy) vs `Resources/` (Classic) structure |
 | ti-ui     | Titanium projects     | Checks for `tiapp.xml` (both Alloy and Classic)               |
+| ti-game   | ti.game module        | Checks for `<module>ti.game</module>` in `tiapp.xml` or `require('ti.game')` |
 
 Why this matters:
 - PurgeTSS suggestions are only provided if PurgeTSS is installed
@@ -422,6 +427,37 @@ Key rules:
 
 ---
 
+### ti-game
+
+2D game development with the `ti.game` native module — a sprite engine rendered with OpenGL ES 2.0, same JS API on Android and iOS. Works in Alloy and Classic projects.
+
+When it activates:
+- `tiapp.xml` declares `ti.game`, or any file calls `require('ti.game')`
+- Sprites, sprite sheets, TexturePacker atlases, frame animations, native tweens
+- Physics: gravity and velocity, solid platforms, one-way floors, bouncing, the arcade car model, Newtonian thrust
+- Collision groups, invisible trigger zones, hitbox tuning
+- Particle emitters, Verlet ropes, camera follow/zoom/shake/effects, low-latency sound
+- Drag & drop, pinch, rotate, multitouch controls
+
+Example prompts:
+```
+"Build a flappy-bird style game with ti.game."
+"My sprites won't collide — collisionGroup is set on both."
+"Add a camera that follows the player with a dead zone."
+"How do I make a top-down racer that drifts?"
+"Why does my game stutter when I move sprites from setInterval?"
+```
+
+Key rules:
+- JS describes the scene and reacts to events; the engine runs every frame. Never move a sprite from a timer — use velocity, gravity, a tween, `carMode` or `thrust`
+- Build the level inside a guarded `resize` handler, never from `Ti.Platform.displayCaps`
+- `solidWith` blocks, `collidesWith` reports — they are independent
+- A sprite with size but no sheet is an invisible trigger (scores, goals, walls)
+- Add a whole level with one `gameView.add([...])` call
+- There is no text in the engine: HUDs are `Ti.UI.Label` overlays
+
+---
+
 ## Usage examples and best practices
 
 ### Example prompts
@@ -517,7 +553,7 @@ Behavior depends on where you run it:
 | With `--local` flag        | Installs skills locally to `./.agents/skills/` in the current project |
 
 What it does:
-- Installs the 8 TiTools skills (global or local depending on context)
+- Installs the 9 TiTools skills (global or local depending on context)
 - Installs ti-pro agent for Claude Code
 - Installs the `/ti-check`, `/ti-new-screen` and `/ti-audit` slash commands into `~/.claude/commands/`
 - Detects installed AI platforms and lets you choose which to link (only Claude Code needs platform symlinks; Gemini CLI and Codex CLI auto-discover from `~/.agents/skills/`)

package/commands/ti-audit.md

@@ -9,5 +9,6 @@ Audit the current Titanium project by invoking the relevant TiTools skills:
 2. Invoke `ti-ui` — check for UI anti-patterns (Ti.UI.SIZE in ListViews, WebView inside TableView, missing accessibility)
 3. If PurgeTSS project, invoke `purgetss` — check for custom TSS that should be utility classes, unsupported classes, padding on Views
 4. Invoke `alloy-guides` — check for proper Alloy patterns (model usage, widget structure)
+5. If the project declares `ti.game`, invoke `ti-game` — check for sprites moved from timers instead of native properties, levels sized from `Ti.Platform.displayCaps` instead of the `resize` event, sprites added one by one instead of in one array, and timers or sounds left running when the window closes
 
 Report findings grouped by severity: critical, warning, info.

package/commands/ti-check.md

@@ -8,8 +8,9 @@ Check the current Titanium project and report:
 1. Read `tiapp.xml` — report SDK version, app ID, deployment targets
 2. Check if Alloy project (app/views + app/controllers exist)
 3. Check if PurgeTSS is configured (purgetss/config.cjs exists)
-4. Check for common issues:
+4. Check whether the `ti.game` module is declared in `tiapp.xml` — report its version and whether the module is actually present under `modules/<platform>/ti.game/<version>/` or installed globally
+5. Check for common issues:
    - Missing icon files (DefaultIcon.png)
    - Empty modules section in tiapp.xml
    - Outdated SDK version
-5. Report a summary of findings
+6. Report a summary of findings

package/lib/config.js

@@ -33,6 +33,7 @@ export const SKILLS = [
   'ti-expert',
   'purgetss',
   'ti-ui',
+  'ti-game',
   'ti-api',
   'ti-guides',
   'ti-howtos',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "4.6.1",
+  "version": "4.7.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

@@ -0,0 +1,179 @@
+---
+name: ti-game
+description: "Use when building or reviewing 2D games with the ti.game module for Titanium SDK (Android and iOS) — sprites, sprite sheets, frame animations, tweens, physics (gravity, solid platforms, carMode drifting, thrust), collision groups, particles, Verlet ropes, camera follow/zoom/shake, low-latency sound, drag & drop, multitouch. AUTO-DETECT: if tiapp.xml declares ti.game or any file calls require('ti.game'), invoke BEFORE writing ANY game code. Also trigger on: game, juego, sprite, spritesheet, platformer, endless runner, top-down, shooter, racer, flappy, breakout, rhythm game, card game, puzzle, collision, hitbox, parallax, particles, game loop, 60 fps, GameView. ti.game is NOT Phaser, Godot or Box2D: you never write a game loop, never move a sprite from setInterval, and several familiar features (bitmap text, tilemap layer, sprite parenting, raycast) do not exist yet — check references/roadmap.md before inventing an API."
+argument-hint: "[genre or feature]"
+allowed-tools: Read, Grep, Glob, Edit, Write, Bash(node *)
+---
+
+# ti.game — 2D game engine for Titanium SDK
+
+`ti.game` is a native OpenGL ES 2.0 sprite engine exposed to JavaScript, written and maintained by **Michael Gangolf (m1ga)** — upstream is https://github.com/m1ga/ti.game. This skill was written against version 0.3.0 as it stands in the `macCesar/ti.game` contribution fork; when upstream and the fork disagree, upstream wins. Same JS API on Android and iOS — the iOS side is a class-per-class Obj-C twin of the Android engine.
+
+Works in **both Classic and Alloy** projects. Nothing here depends on PurgeTSS.
+
+## The one rule everything follows
+
+**JS describes the scene and reacts to events. The engine runs every frame.**
+
+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.
+
+The practical consequence, and the single biggest mistake to avoid:
+
+> 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.
+
+| 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 | timer repositioning copies | `wrapX` / `wrapShift` + `velocityX` |
+| Camera that follows the player | timer writing `cameraX` | `gameView.follow(sprite, options)` |
+| 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` |
+
+## Minimal scene
+
+```javascript
+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
+});
+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
+});
+
+let initialized = false;
+gameView.addEventListener('resize', (e) => {
+	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,
+		animations: {
+			idle: { frames: [0], fps: 1, loop: true },
+			walk: { frames: [1, 2], fps: 6, loop: true }
+		}
+	});
+	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 (payload `group`, `other`, `x`, `y`), re-arming after separation. Nothing is blocked.
+
+A sprite can use both — a player that stands on platforms (`solidWith`) and dies on spikes (`collidesWith`).
+
+**A sprite with `width`/`height` but no `sheet` renders nothing and works as an invisible trigger.** Score zones, goals, checkpoints, ceilings, kill floors and walls are all built this way in the official demos. This is the idiomatic way to add logic to a scene without art.
+
+Tune fairness with `hitboxScale` (art rarely fills its frame; slightly small hitboxes feel better) and `hitboxShape: 'circle'` for balls and rocks — circles also resolve against solids along the contact normal, so they bounce off corners diagonally instead of like a box. Turn on `debug: true` per sprite, or on the GameView for everything, to see green collision AABBs, blue touch bounds and the orange anchor dot.
+
+## 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.
+- **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.
+
+## There is no text in the engine
+
+The engine draws sprites, particles and ropes — **not text**. HUDs, scores and labels are ordinary `Ti.UI.Label` views overlaid on the window, on top of the GameView. That is how every official demo does it. Consequences worth knowing before designing a HUD: overlaid Titanium views are screen-fixed, so they do not scroll with the camera, do not z-sort against sprites and cannot be tweened by the engine. Bitmap-font text sprites are planned but do not exist — see [roadmap.md](references/roadmap.md).
+
+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`.
+
+## Clean up what you created
+
+The render loop follows the activity lifecycle automatically, but **your 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()`.
+
+```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 | [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) |
+
+## 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?
+6. Do triggers (scores, goals, kill zones) use sheet-less sprites instead of visible art?
+7. Is every `createSound`, `setInterval` and `setTimeout` stopped when the window closes?
+8. Is the HUD a `Ti.UI.Label` overlay, not an imagined engine text API?
+9. Are you using an API that actually exists? Anything involving text, tilemaps, sprite parenting, raycasting, joysticks or `blend: 'multiply'` — check [roadmap.md](references/roadmap.md) first.