@maccesar/titools 5.1.1 → 5.2.1

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

@@ -0,0 +1,101 @@
+# Keyboard, mouse and action maps
+
+Reviewed 2026-10-23 against `m1ga/ti.game@88e181cb85526d8146d0be6e09b2b90c2551baad` native input resolvers and canvas adapters, with README clarification from `macCesar/ti.game@2bf5f828a3bb8028eed20d6ba27b97dd3aa9a753`. Requires an artifact containing those APIs; a shared version number is insufficient evidence. Existing controller events and analog input remain documented in [api.md](api.md#gamepads).
+
+## Map and event contract
+
+`GameView.inputMap` is optional, live, readable/writable and defaults to `{}`. It maps contexts to named actions, each with an array of digital bindings. `inputContext` accepts only a string or `null` (other types throw) and defaults to `'gameplay'`; `null` disables actions. Replace the whole map to rebind; the module supplies no settings UI or persistence.
+
+```javascript
+const gameView = Game.createGameView({
+	inputMap: {
+		gameplay: {
+			thrust: [
+				{ device: 'keyboard', code: 'KeyW' },
+				{ device: 'keyboard', code: 'ArrowUp' }
+			],
+			fire: [
+				{ device: 'keyboard', code: 'Space' },
+				{ device: 'mouse', button: 'left' },
+				{ device: 'gamepad', button: 'a' }
+			],
+			pause: [{ device: 'keyboard', code: 'Escape' }]
+		},
+		paused: { pause: [{ device: 'keyboard', code: 'Escape' }] }
+	}
+});
+gameView.addEventListener('actiondown', ({ action, context }) => {
+	// Dispatch discrete actions or write native motion properties here.
+	// A pause handler can change inputContext to 'paused' and timeScale to 0.
+});
+gameView.addEventListener('actionup', ({ action, context }) => {
+	// Clear held controls, including releases caused by lost focus/cancellation.
+});
+// Add the view, open the window, then call this (also after native text entry):
+gameView.focusInput();
+```
+
+The snippet is a map/transition template; scene setup and window lifecycle are in [project-setup.md](project-setup.md). No per-frame JavaScript polling is needed: action resolution runs natively on input transitions.
+
+| Input | Contract |
+| --- | --- |
+| `actiondown` / `actionup` | Payload `{ action, context }`. An action goes down on its first active binding and up after its last source releases, across different bindings and controllers |
+| Map replacement | A valid map releases previous active actions and requires a fresh press; held keys cannot activate the replacement map until released and pressed again |
+| Context change | Releases active actions from the old context, requires a fresh press; assigning the same context leaves state unchanged |
+| Invalid map | Throws without replacing the map or active state |
+| Cancellation | Focus loss, suspension, device disconnection and view shutdown release held actions. An action release need not have a physical/raw `keyup`; drive gameplay from action transitions |
+| Auto-repeat | Ignored as a new press; holding a key does not repeat `actiondown` |
+
+Context and action names must be nonempty strings. Empty contexts and empty action arrays are allowed. Each binding has **exactly two keys**: `device` plus `code` for keyboard, or `device` plus `button` for mouse/gamepad. Analog axes are not action bindings.
+
+| Device | Accepted binding values |
+| --- | --- |
+| `keyboard` (`code`) | `KeyA`…`KeyZ`, `Digit0`…`Digit9`, `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`, `Space`, `Escape`, `Enter`, `Tab`, `Backspace`, `Delete`, `Home`, `End`, `PageUp`, `PageDown`, `F1`…`F12`, `ShiftLeft`/`ShiftRight`, `ControlLeft`/`ControlRight`, `AltLeft`/`AltRight`, `MetaLeft`/`MetaRight` |
+| `mouse` (`button`) | `left`, `middle`, `right` |
+| `gamepad` (`button`) | `a`, `b`, `x`, `y`, `l1`, `r1`, `l2`, `r2`, `l3`, `r3`, `start`, `select`, `home`, `up`, `down`, `left`, `right` |
+
+Existing gamepad properties, individual button events, sticks and triggers are unchanged. Use mapped actions **or** individual button handlers for each gameplay action to avoid dispatching twice. An app keeping its own gamepad adapter can omit gamepad bindings from the map.
+
+## Keyboard focus and pointer ownership
+
+Raw `keydown` / `keyup` events carry `{ code, character, modifiers: { shift, control, alt, meta } }`. `code` identifies the physical key independently of its text character; `character` can be empty for non-text keys.
+
+Only the focused GameView receives keyboard events. `focusInput()` requests canvas focus on the UI thread; it neither opens a software keyboard nor captures keys globally. Native text fields retain their focus. Call it after opening the game window and after returning from a native text field.
+
+When the active context has mouse bindings, pointer gestures delivered to the canvas feed mapped actions and are consumed rather than also becoming sprite tap/drag interactions. Empty maps, keyboard-only contexts and disabled actions preserve existing sprite pointer interaction. Overlay Titanium controls retain their clicks and focus; the module does not capture their mouse events. Android retains the engine touch listener.
+
+For iOS/iPadOS 13.4–16 pointer identification, set the consuming application's `tiapp.xml` opt-in (iOS 17+ defaults it to true):
+
+```xml
+<ios>
+  <plist>
+    <dict>
+      <key>UIApplicationSupportsIndirectInputEvents</key>
+      <true/>
+    </dict>
+  </plist>
+</ios>
+```
+
+This application-level setting distinguishes indirect pointers from direct touch; the module does not change global input settings at runtime. The current Apple package targets iOS/iPadOS **15+** and Mac Catalyst with Metal. Its keyboard/pointer guards dating from iOS 13.4 and disconnection notification guards dating from iOS 14 do not lower that package minimum.
+
+## Runnable example and acceptance limits
+
+`example/inputmap.js` is the current action-map demo. The launcher exposes it on Mac only; mobile builds retain touch-ready demos. The source remains usable for external-peripheral testing on mobile.
+
+- A/D, J/L, arrows or gamepad move the character. The last pressed direction wins; releasing it resumes the other held direction.
+- Space or gamepad A jumps. W/I/Up aims upward, including diagonal combinations; S/K/Down crouches.
+- Left canvas click or gamepad X fires. Right/middle mouse bindings are accepted for testing but currently do not trigger actions on Mac; left click is verified by the source's acceptance notes.
+- Escape switches pause/resume action contexts. A separate monitor shows raw key codes/modifiers and existing gamepad buttons, sticks and triggers.
+- Instructions and action feedback occupy separate areas. An overlaid text field and focus button demonstrate native ownership; clicking the canvas after text entry restores game focus, and the first click does not fire. The shared back control returns to the launcher.
+
+Upstream verification commands, run from the module checkout:
+
+```sh
+python3 tests/input-map/run.py
+python3 tests/input-map/uikit.py
+python3 tests/gamepad-fixture/check.py
+node --test tests/example-input/controls.test.js
+```
+
+Resolver regressions test native binding validation, aggregation and transitions. UIKit fixtures exercise production responder methods with renderer/event sinks for focus, raw-key repetition/cancellation and pointer/overlay ownership. GameController fixtures cover receiver fanout, disconnect and action delivery without individual listeners. JavaScript example tests check demo control behavior. Compilation and these fixtures do not establish physical keyboard, mouse, controller or overlay behavior on every supported device; record that acceptance separately.

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

@@ -1,6 +1,7 @@
 # Cross-cutting ti.game patterns
 
-Verified against `ti.game@3bea2f4` and the runnable examples under `example/`. These are production-oriented extractions of the API combinations demonstrated upstream; they intentionally omit demo-launcher and back-navigation plumbing.
+Reviewed against upstream native `88e181c` and the documentation/examples in
+`macCesar/ti.game@2bf5f82` on 2026-10-23. These are production-oriented extractions of the API combinations demonstrated upstream; they intentionally omit demo-launcher and back-navigation plumbing.
 
 See [examples.md](examples.md) to choose the source demo, [api.md](api.md) for exact members, and the genre recipe files for complete game loops.
 
@@ -76,7 +77,14 @@ module.exports = function () {
 };
 ```
 
-Sizing everything as a fraction of `W`/`H` is not cosmetic — a jump tuned in absolute pixels becomes unplayable on a different device. The demos consistently express speeds as `W * f`, accelerations as `H * f` and sprite sizes as `Math.min(W, H) * f`.
+Use the actual canvas for sizing. Current demos cap foreground art and text by
+height as well as width so short desktop windows do not clip their controls.
+For example, text can use `Math.max(1, Math.round(Math.min(W / 240, H / 360)))`.
+Measure surface pixels per view point from `W / gameView.rect.width` when
+converting native control margins; use a positive finite density fallback.
+Keep a guarded first `resize` for world creation and relayout the HUD on later
+resizes when the app supports changing windows. See
+[project-setup.md](project-setup.md) for complete integration.
 
 ## Cross-cutting patterns
 
@@ -146,7 +154,7 @@ Recycling a sprite with `visible = false` fires `collisionend` on anything it wa
 
 ### Freeing a level's textures
 
-Pooling recycles sprites; it does not free the **texture** behind them. A game that streams worlds accumulates every atlas it has ever loaded until the GL context dies. `unload()` releases one on the next rendered frame.
+Pooling recycles sprites; it does not free the **texture** behind them. A game that streams worlds accumulates every atlas it has ever loaded until scene resources are released. `unload()` releases one on the next rendered frame.
 
 ```javascript
 function unloadLevel(level) {
@@ -206,7 +214,17 @@ Slower layers read as further away. Three layers (clouds at 0.15×, hills at 0.4
 
 ### Multitouch on-screen controls
 
-Each button must be **its own Titanium view** — sibling views receive simultaneous pointers, so holding a direction while pressing jump works. A single container splitting touches itself does not.
+Use separate sibling input targets for held directions and actions. Their
+native control type also matters for simultaneous touch; the factory below
+uses Label rather than UIButton-backed controls.
+
+The factory below deliberately uses Label. In Titanium SDK13.4.1.GA on iOS,
+TiUIButton sets its internal UIButton's `exclusiveTouch=YES`; changing the
+outer view's multitouch flag does not remove that exclusivity. Keep held
+flight controls as sibling Label/View targets or native game sprites and
+verify simultaneous input on-device. See `iphone/Classes/TiUIButton.m`,
+method `button`, in that SDK; this is a Titanium UI boundary, not a ti.game
+physics discrepancy.
 
 ```javascript
 function makeButton(title, position, fontSize) {
@@ -252,7 +270,14 @@ bindHold(leftButton, () => {
 });
 ```
 
-The guard in the release handler is what keeps two opposite buttons from fighting: releasing left only zeroes steering if left is still the active direction.
+The guard avoids releasing one control cancelling a newer opposite command.
+It does not restore a still-held older direction. For mixed touch, keyboard and
+controller input, track each source's held state and derive direction from the
+active set, as current `platformer.js`/`volley.js` do. They cancel opposing
+directions and resume the remaining one on release. `inputmap.js` deliberately
+uses a different last-pressed-wins rule. Choose the policy explicitly; do not
+confuse either with the native action aggregator, which combines bindings for
+one named action. See [input.md](input.md) for native input maps and focus rules.
 
 ### HUD — `text.js`, `flappy.js`
 
@@ -306,7 +331,11 @@ dialog.addEventListener('tap', () => {
 
 `maxWidth` is measured before `scale`, which is the only trap here — pass screen pixels straight in and the block comes out `scale` times too wide. `align` positions the lines against each other (the block's own width), not inside the wrap column, so anchor the sprite where the text should sit. A word longer than `maxWidth` overflows instead of breaking mid-word.
 
-Overlaid `Ti.UI.Label` views remain the answer for text the engine's font cannot draw (accents, system fonts, right-to-left) and for real UI: menus, dialogs, text inputs.
+The built-in font now includes the accented characters listed in
+[api.md](api.md#font); do not assume all accents need an overlay. Ship a custom
+bitmap font for other supported glyph sets. Overlaid `Ti.UI.Label` views remain
+appropriate for system fonts, right-to-left interfaces and native UI such as
+menus, dialogs and text inputs.
 
 ### Labels, bars and turrets pinned to a sprite — `attachTo`, `text.js`
 
@@ -485,7 +514,15 @@ const ball = Game.createSprite({
 
 Two things bite here. The sweep **ignores** anything that is not `solidMode: 'block'`, so `swept: true` will not stop a fast enough ball crossing the boundary between frames — keep the speeds inside a container sane. And a `'contain'` solid only holds *circles*: a rect mover runs a resolver that never reads `solidMode` and gets pushed **out** of the boundary instead of held in.
 
-**`linearDamping` is the missing friction, with a caveat.** `drag` only ever worked inside `carMode`; this is the same idea for ordinary sprites, and it is what brings a pool table to rest. But nothing checks contact — it bleeds speed on both axes, in the air as much as on the felt, and along a slope as much as across it. Right for a table, wrong for a hill. Below a combined 4 px/s the engine zeroes the velocity outright, so a deliberate 3 px/s drift dies the moment that sprite also carries damping.
+**`linearDamping` attenuates velocity everywhere.** Car `drag` works inside
+`carMode`; linear damping also works for ordinary sprites and can bring a pool
+table to rest. The attenuation is not contact-only friction: it bleeds speed
+on both axes, in the air as much as on felt, and along a slope as much as
+across it. Below a combined 4 px/s the engine settles coasting or blocked motion, but
+allows effective acceleration to build from rest; the decision is completed
+after contact response. A deliberate unpowered 3 px/s drift with damping still
+stops. See [thrust and damping](physics.md#thrust-inertia-and-linear-damping)
+for the current rest policy and the older powered-launch bug.
 
 **A bouncy surface is now a property of the surface.** `restitution` is read off both sides and mixed as `max`, so a springy floor rebounds riders that are not themselves bouncy:
 
@@ -557,7 +594,7 @@ ship.followPath(diamond, {
 
 A non-looping run fires `pathcomplete` and clears itself; `followPath(null)` stops in place. Two points is the minimum — one point is ignored with a warning, not treated as "go there".
 
-The path writes `x`/`y` outright, after velocity and gravity have been integrated, so **a sprite on a path ignores its own physics for placement**. It still feeds the frame delta, though, which means a platform on a looping circuit carries whatever is standing on it — a moving platform is now a path, not a tween ping-pong.
+The path writes `x`/`y` outright, after velocity and gravity have been integrated, so **a sprite on a path ignores its own physics for placement**. In a periodic world the engine aligns the cursor before advancing so crossing the seam retains the intended frame delta; this does not make pathfinding periodic. It still feeds the frame delta, though, which means a platform on a looping circuit carries whatever is standing on it — a moving platform is now a path, not a tween ping-pong.
 
 Animation chains are native in the same spirit:
 
@@ -597,7 +634,7 @@ Run these from a coarse timer or a tap handler — the demo probes at 150 ms —
 
 ### Pathfinding around obstacles — `maze.js`, `pointclick.js`
 
-`gameView.findPath(from, to, options)` is grid A\* over the same sprites `raycast` sees: visible, tagged with a `collisionGroup`, nothing else to set up. It returns `{ x, y }` waypoints — or `null` — and those waypoints go straight into `followPath`, so the walk itself runs natively.
+`gameView.findPath(from, to, options)` is grid A\* over the same sprites `raycast` sees: visible, non-`screenFixed`, tagged with a `collisionGroup`. It also includes fully solid cells from matching TileLayers; one-way cells remain walkable. It returns `{ x, y }` waypoints — or `null` — and those waypoints go straight into `followPath`, so the walk itself runs natively.
 
 ```javascript
 gameView.addEventListener('tap', (e) => {
@@ -673,7 +710,16 @@ What still belongs in `setTimeout`: anything that must keep running while the ga
 
 ### Hit-stop on impact
 
-Freezing the scene for a few frames makes an impact read before the explosion starts. `timeScale = 0` stops the engine from advancing while it keeps drawing and accepting touches — no render loop to restart, no state to save. (Pattern from Titanium Lander: 140 ms on a crash, 90 ms when a shield absorbs a hit.)
+Giving the scene zero dt for a few frames makes an impact read before the
+explosion starts, while it keeps drawing and accepting touches. This avoids
+restarting the render loop. (Pattern from Titanium Lander: 140 ms on a crash,
+90 ms when a shield absorbs a hit.)
+
+This sets scene dt to zero while touch and explicit property writes remain
+active. Current Rope integration, history, constraints and tether response
+freeze as well; newly created geometry can still initialize. The older
+`3bea2f4` rope exception is fixed. See
+[physics.md](physics.md#verlet-ropes-and-tethers).
 
 ```javascript
 let hitStopTimer = null;