@maccesar/titools 4.15.0 → 4.16.0

package/skills/ti-game/references/debugging-performance.md

@@ -0,0 +1,103 @@
+# Debugging and performance telemetry
+
+Verified against `ti.game@d587081`: both `GameViewProxy` implementations, `DebugHud`, `FrameStats`, both scene renderers, `example/camera.js`, `example/particles.js`, and `example/tilemap.js`.
+
+## The two debug aids
+
+`GameView.debug` accepts a legacy boolean or an object:
+
+```javascript
+const gameView = Game.createGameView({
+	debug: {
+		hitbox: true,
+		hud: 'topRight'
+	}
+});
+```
+
+| Form | Meaning |
+| --- | --- |
+| `debug: true` | Global collision shapes only; shorthand for `{ hitbox: true }` |
+| `{ hitbox: true }` | Global sprite and tile-cell collision visualization |
+| `{ hud: true }` | Performance HUD in `topLeft` |
+| `{ hud: 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight' }` | HUD in an explicit corner |
+| `{ hud: true, hudFont: font }` | HUD drawn with a `Game.createFont()` bitmap font |
+
+Writing the object replaces both modes: omit `hitbox` and it becomes false; omit `hud` and the HUD turns off. Reading `gameView.debug` returns `{ hitbox: boolean, hud: false | corner }`; `hudFont` is configuration, not part of the readback. Sprite-level `sprite.debug` remains a boolean.
+
+The HUD is screen-space and is drawn after the camera effect. Camera scroll, zoom, shake, and glitch do not move or distort it. It starts compact (`FPS`, `MS`, `DC`); tapping it expands/collapses the panel, and the panel consumes its own touches.
+
+## Hitbox colors and tuning
+
+- Green: collision shape after `hitboxScale`, `hitboxScaleX`, and `hitboxScaleY`.
+- Blue: full sprite/touch bounds.
+- Orange: anchor.
+- Tile debug: outlines fully solid cells in view.
+
+Tune geometry in this order:
+
+1. Put the correct shape on both mover and solid (`rect`, `circle`, or `rotatedRect`).
+2. Set the anchor to the semantic contact point, often `anchor: 'bottom'` for feet.
+3. Apply the global hitbox scale.
+4. Correct one axis only when the frame padding differs by axis.
+
+The scale properties affect collision, not the touch rectangle. `hitboxShape: 'circle'` does change the touch shape.
+
+## Performance HUD fields
+
+| HUD | Event key | Meaning |
+| --- | --- | --- |
+| `FPS` | `fps` | Frames presented in the closed one-second window |
+| `MS` | `averageCpuMs` | Average engine CPU time per frame; the `maxFps` wait is excluded |
+| `P95` | `p95CpuMs` | 95th percentile CPU frame time |
+| `MAX` | `maxCpuMs` | Worst CPU frame in the window |
+| `DROP` | `droppedFrames` | Presentation intervals longer than one target refresh |
+| `SPRITES` | `visibleSprites` / `sprites` | Drawn sprites / sprites in the scene |
+| `EMITTERS` | `emitters` | Emitters in the scene |
+| `PARTICLES` | `particles` | Live particles |
+| `DRAWCALLS` | `drawCalls` | Scene draw calls; HUD draw calls excluded |
+| `TEXSWITCH` | `textureSwitches` | Texture switches |
+| `UPDATE` | `averageUpdateMs` | Physics, animation, tween, and scene update time |
+| `TEXTURE` | `averageTexturePrepareMs` | Texture preparation/upload time |
+| `BATCH` | `averageBatchMs` | Batching and drawing time |
+| `PRESENT` | `averagePresentMs` | iOS only: buffer presentation time |
+| `PRESENTFAIL` | `presentFailures` | iOS only: failed presentations |
+
+The event also includes `surfaceWidth` and `surfaceHeight`. Android omits `averagePresentMs` and `presentFailures`; do not interpret missing keys as zero.
+
+## Programmatic telemetry
+
+The `performance` event fires at most once per second and only while a listener exists:
+
+```javascript
+function onPerformance({ fps, averageCpuMs, drawCalls, textureSwitches }) {
+	Ti.API.info(`${fps} fps; ${averageCpuMs.toFixed(1)} ms; ${drawCalls} calls; ${textureSwitches} switches`);
+}
+
+gameView.addEventListener('performance', onPerformance);
+
+function cleanup() {
+	gameView.removeEventListener('performance', onPerformance);
+}
+```
+
+Telemetry is opt-in inside the renderers. With the HUD disabled and no `performance` listener, frame-stat clock reads are disabled. Use the HUD while developing; use the event for short diagnostic sessions or a deliberate in-app performance screen, not permanent per-frame business logic.
+
+## Reading the numbers
+
+- High draw calls with stable sprite count: inspect texture order, blend changes, glow/flash, ropes, skid marks, and debug overlays.
+- High texture switches: pack related art into fewer sheets and group sprites using the same sheet/blend into coherent `zIndex` bands.
+- High update time: narrow collision groups and reduce active colliders/particles; hidden sprites are excluded from render and collision.
+- A large `TileLayer` should keep draw calls and visible work stable while the camera moves; one sprite per tile scales with the whole scene instead.
+- `maxFps: 60` can prevent a 120 Hz display from doubling work when the game does not need it.
+- Judge final performance on hardware. The iOS Simulator's translated OpenGL path is intentionally rendered at 1× and remains slower than a device.
+
+## Common diagnostic order
+
+1. Confirm the object was added and is visible/in bounds.
+2. Turn on the relevant sprite/layer debug shape, then the global overlay if relationships are unclear.
+3. Verify `collisionGroup` is on the target and `solidWith`/`collidesWith` on the mover.
+4. Inspect HUD counts and draw calls before changing code.
+5. Compare the smallest relevant upstream demo from [examples.md](examples.md).
+6. Disable instrumentation after the issue is understood.
+

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

@@ -0,0 +1,54 @@
+# Upstream example catalog
+
+Verified against all 33 self-contained demos under `ti.game@d587081:example/` plus the launcher `example/app.js`.
+
+The demos prove that API combinations run together on the current module. They are **not** production templates: most keep state in one file, repeat launcher/back-button plumbing, and still use pre-ES6 syntax. Start from the closest demo, retain the demonstrated engine calls, then apply the focused structure and cleanup patterns in this skill.
+
+| Demo | What it proves | Production-oriented reference |
+| --- | --- | --- |
+| `basic.js` | Sheets, frame animation, drag/pinch/rotate, tween completion | [Scaffolding](patterns.md#the-scaffolding) |
+| `puzzle.js` | Multi-touch drag, press-to-lift, snapping and tween-back | [Cards and board games](recipes-adventure-effects.md#cards-and-board-games) |
+| `flappy.js` | Gravity impulse, invisible score/death zones, wrapping parallax | [Tap-to-flap](recipes-action.md#tap-to-flap) |
+| `platformer.js` | `solidWith`, `land`, `oneWay`, carried rider, camera follow, multi-touch controls | [Platformer](recipes-action.md#platformer) |
+| `volley.js` | Restitution ball, `land`, collision response, coarse AI timer | [Ball sports](recipes-action.md#ball-sports--breakout-physics) |
+| `racing.js` | `carMode`, drift, skid marks, checkpoints and lap state | [Top-down racer](recipes-action.md#top-down-racer) |
+| `cards.js` | Dealing, fanned layout, selection tweens and idle wobble | [Cards and board games](recipes-adventure-effects.md#cards-and-board-games) |
+| `asteroids.js` | Thrust, angular velocity, wrapping, pooling, additive bolts, effect/music audio | [Space shooter](recipes-action.md#asteroids--space-shooter) |
+| `topdown.js` | Small string map made from sprites, `ySort`, eight-way input, decision timer | [Top-down / Zelda](recipes-action.md#top-down--zelda) |
+| `skate.js` | Endless-runner pooling, carried/uncarried terrain, parallax, emitter and audio hooks | [Endless runner](recipes-action.md#endless-runner) |
+| `pointclick.js` | Tap-to-walk with `findPath` → `followPath`, hotspots and `ySort` | [Point-and-click](recipes-adventure-effects.md#point--click-adventure) |
+| `particles.js` | Continuous/burst emitters, sprite target, HUD telemetry | [Particles](recipes-adventure-effects.md#particles) and [debugging](debugging-performance.md) |
+| `rhythm.js` | Pooled notes, native velocity, `press` pads, timing and audio feedback | [Rhythm game](recipes-action.md#rhythm-game) |
+| `camera.js` | Two-axis follow, bounds, zoom, shake, camera effects, parallax and debug HUD | [Camera work](recipes-adventure-effects.md#camera-work) |
+| `rope.js` | Rope pinned to a sprite, fixed head, tail weight | [Ropes and chains](recipes-adventure-effects.md#ropes-and-chains) |
+| `flip.js` | Draw-only flips driven by direction and inverted gravity | [Visual effects](recipes-adventure-effects.md#visual-effects) |
+| `hitbox.js` | Global/sprite debug overlays and per-axis hitbox correction | [Seeing the hitbox](patterns.md#seeing-the-hitbox--hitboxjs) |
+| `blend.js` | Normal/add/multiply/screen modes and `flash()` | [Visual effects](recipes-adventure-effects.md#visual-effects) |
+| `text.js` | Screen-fixed HUD, world labels, text buttons, word wrap and `attachTo` | [HUD](patterns.md#hud--textjs-flappyjs) |
+| `swept.js` | Identical fast bullets with and without continuous sweep | [Object pooling](patterns.md#object-pooling) and [API gotchas](api.md#gotchas-the-property-tables-do-not-show) |
+| `path.js` | Looped/smoothed paths, one-shot paths and animation chains | [Patrol routes](patterns.md#patrol-routes-and-animation-chains--pathjs) |
+| `raycast.js` | Line of sight, ledge probes and tap-fired hitscan | [Raycast pattern](patterns.md#line-of-sight-ledge-probes-and-hitscan--raycastjs) |
+| `zones.js` | `collision`/`collisionend`, pressure plate and removal during contact | [Zones](patterns.md#zones-you-can-be-inside-of-enter--exit--zonesjs) |
+| `demoscene.js` | Follow-path circles, per-character scroller, glow, blend and music | [Visual effects](recipes-adventure-effects.md#visual-effects) |
+| `maze.js` | Raw/simplified A*, re-pathing AI and path visualization | [Pathfinding](patterns.md#pathfinding-around-obstacles--mazejs-pointclickjs) |
+| `timescale.js` | Slow/frozen scene, engine timer versus real-time interval | [Game-clock timers](patterns.md#timers-on-the-game-clock) |
+| `circles.js` | Rect/circle/rotated-rect solids and `block` versus bilateral `push` | [Shaped solids](patterns.md#shaped-solids-ramps-round-posts-and-bodies-that-push-back--slopesjs-circlesjs-pooljs-drumjs) |
+| `slopes.js` | Rotated-rect ramp normals and restitution supplied by a surface | [Shaped solids](patterns.md#shaped-solids-ramps-round-posts-and-bodies-that-push-back--slopesjs-circlesjs-pooljs-drumjs) |
+| `plinko.js` | Circular pegs, swept balls and trigger slots | [Shaped solids](patterns.md#shaped-solids-ramps-round-posts-and-bodies-that-push-back--slopesjs-circlesjs-pooljs-drumjs) |
+| `pool.js` | Bilateral circle momentum, rails, pockets and linear damping | [Shaped solids](patterns.md#shaped-solids-ramps-round-posts-and-bodies-that-push-back--slopesjs-circlesjs-pooljs-drumjs) |
+| `drum.js` | Analytic circular containment and contact-driven impulses | [Shaped solids](patterns.md#shaped-solids-ramps-round-posts-and-bodies-that-push-back--slopesjs-circlesjs-pooljs-drumjs) |
+| `wind.js` | `gravityX` as wind and as top-down constant acceleration | [Shaped solids](patterns.md#shaped-solids-ramps-round-posts-and-bodies-that-push-back--slopesjs-circlesjs-pooljs-drumjs) |
+| `tilemap.js` | One 120×90 `TileLayer`, visible-cell rendering, cell collision, live edits, A* and HUD | [Tile maps](tilemaps.md) |
+
+## Choosing the right map example
+
+`topdown.js` deliberately creates one sprite per tile for a small 16×12 scene; that remains reasonable when individual tiles need sprite behavior. `tilemap.js` is the reference for large or mostly static grids: one native `TileLayer` avoids ticking, sorting, drawing, and collision-scanning off-screen tile sprites.
+
+## Reading a demo safely
+
+1. Identify the engine-owned behavior being demonstrated.
+2. Copy the smallest connected API sequence, not the entire file.
+3. Replace `var` and function-expression callbacks with the project's current ES6+ style.
+4. Keep resources outside `resize`; create surface-sized scene objects inside one guarded `resize` path.
+5. Separate reusable state from launcher UI and add explicit cleanup for app-owned listeners, timers, and sounds.
+