@maccesar/titools 5.1.0 → 5.2.0

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

@@ -232,6 +232,12 @@ Add `blend: 'add'` for fire, magic and sparks — overlaps bloom instead of cove
 
 ## Ropes and chains
 
+Rope `damping` retains a fraction of the previous displacement **per update**,
+unlike Sprite `linearDamping`, whose coefficient is in 1/s. In the pinned
+source, Verlet displacement and constraint relaxation still run at `dt=0`;
+`timeScale=0` does not guarantee a motionless rope. See the equations and
+pause boundary in [physics.md](physics.md#verlet-ropes-and-tethers).
+
 ```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' });
@@ -335,6 +341,11 @@ gameView.addEventListener('tap', () => {
 });
 ```
 
-**`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.
+**`timeScale`** scales the dt for physics, sheet animations, tweens, particles,
+camera and game-clock timers, while rendering/touch keep running. `0.5` gives
+slow motion; `0` gives zero dt for a pause or hit-stop. Rope still applies
+previous displacement and constraints at zero dt in this snapshot, so test
+rope scenes separately. `timescale.js` compares a game-clock timer with an
+independent JS interval; it does not include a rope.
 
 **`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

@@ -8,7 +8,7 @@ Verified against `ti.game@3bea2f4` (2026-09-02), especially upstream `TODO.md` a
 | --- | --- | --- |
 | `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 (`joystick.bind(sprite)`) | Planned | Use overlaid Titanium controls that write native motion/input properties on `touchstart`/`touchend`; sibling views support simultaneous touches. Upstream intends the same binding to accept a gamepad's left stick, which also does not exist yet |
+| Native joystick/d-pad binding (`joystick.bind(sprite)`) | Planned | Use sibling Label/View targets or game sprites that write native motion/input properties on input transitions; UIKit UIButton exclusivity needs care for simultaneous touch. Upstream intends a future joystick binding to accept the left stick |
 | 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 |
@@ -22,7 +22,7 @@ Verified against `ti.game@3bea2f4` (2026-09-02), especially upstream `TODO.md` a
 | 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 |
+| A GameView-level `stop()` | Already covered differently | `timeScale = 0` passes zero dt while rendering/touch continue; Rope can still integrate prior displacement and constraints. `pause()` stops the render loop; see [physics.md](physics.md#verlet-ropes-and-tethers) |
 | 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 |
 

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

@@ -40,7 +40,8 @@ For Tiled JSON, pass the layer data with `cols: map.width`, `rows: map.height`,
 
 ## Portable property timing
 
-The upstream README says every property is live, but the native bindings differ. Use the portable contract below:
+The pinned upstream README now documents the same creation-time portability
+boundary as the native bindings. Use this contract:
 
 | Timing | Properties |
 | --- | --- |

package/skills/ti-game-assets/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: ti-game-assets
+description: Use when creating, editing, preparing or integrating game sprites, animation frames, atlases, particles, backgrounds, parallax layers, HUD art, synthesized sound effects, sound variants, stereo placement, music, ambience, procedural WAV, editable SVG sources, repeating textures or world asset sets in a Titanium project, including pixel art, HD art and alpha cleanup. Applies to visual assets even without native game or sound modules installed.
+metadata:
+  requirements: Raster drawing uses integrated image_gen; authored SVG/procedural exports use project tools; validators need Python 3 and Pillow.
+---
+
+# Game assets for Titanium
+
+Produce coherent visual and sound assets and complete, reproducible exports. Sound creation and refinement are an essential domain alongside images, governed by `ti-synthengine`. Preserve editable SVG/procedural sources when used, full-canvas PNG masters/renders, audio recipes or WAV generators, prompts and provenance in the project's source of truth. Read its art workflow and inventory before editing; a world's own style and authorized rendering exceptions govern that world.
+
+For individual raster masters, request maximum useful canvas coverage and the highest suitable detail supported by the current generator. Frame the complete subject closely with only the transparent edge needed to avoid clipping. Do not prescribe a default occupancy percentage or generous empty margins. Game-size outputs are derivatives of these masters. Record actual generated dimensions; no permanent 1024, 1254 or 1400-pixel cap applies. Shared animation/state canvases and intentional effect extents follow their explicit contracts; see [references/art-direction.md](references/art-direction.md).
+
+For pixel art, specify the actual final logical grid and visible phase extent before generation. HD blocks must map proportionally to final pixels, with consistent square color/alpha blocks; "pixel-art style" alone is insufficient. Preserve progressive smoke alpha on that grid, export with nearest-neighbor resampling and inspect at actual game size. HD gradients follow their own filtering contract.
+
+For HD illustration, require both the highest useful native generation resolution and a visibly refined finish: well-defined materials/textures, clean gradients, precise straight edges, smooth regular curves, crisp delineation and coherent light/shadow. Follow the world's style and any requested symmetry. Inspect the full-resolution master and its final reduction; pixel count alone does not establish quality, and minor sharpening does not satisfy a requested reconstruction.
+
+## Required workflow
+
+Read the relevant references before acting:
+
+| Work | Reference |
+| --- | --- |
+| Generate/edit art, pixel grid, variants, animation continuity | [references/art-direction.md](references/art-direction.md) |
+| Inventory, contracts per game/world/level, frames, aliases, parallax | [references/manifest.md](references/manifest.md) and `references/manifest.example.json` |
+| Analyze/clean alpha, protected regions, trim and alignment | [references/alpha.md](references/alpha.md) |
+| ti.game sprite-sheets, proportional reduction/integer rounding, atlas packing, HUD, previews, densities and sound events | [references/integration.md](references/integration.md) |
+| Create/edit sounds, variants, stereo, mixing and audition | [references/sound-assets.md](references/sound-assets.md) |
+| Editable SVG/procedural art and deterministic builds | [references/vector-sources.md](references/vector-sources.md) |
+| Seamless textures, tile adjacency and circular parallax phase | [references/repeating-textures.md](references/repeating-textures.md) |
+| Offline WAV generation, signal analysis and seamless audio loops | [references/offline-audio.md](references/offline-audio.md) |
+| Requested monetization or existing ad/game transitions | [references/responsible-ads.md](references/responsible-ads.md) |
+| Prompt starting points | [references/prompts.md](references/prompts.md) |
+
+1. Inspect references and existing exporters. Distinguish style references, composition references and the exact image being edited. Scrap art is a reference for its own family, never a universal base.
+2. Define the art contract and complete manifest before integrating a new world. Separate unique resources, variants, states, ordered frames, aliases and technical utilities. Compare counts only between sets sharing a contract. Declare each derived output's actual consumer and explicit resource selection; a complete source inventory does not require exporting every asset to every UI folder. See [references/integration.md](references/integration.md#export-only-what-each-consumer-uses).
+3. Create/edit required sound recipes and patterns through the current `ti-synthengine` workflow; define acoustic palette, meaningful variants, stereo placement and overlap budgets. Preserve the existing clock and lifecycle owner. Generate and edit raster drawings with ChatGPT's integrated `image_gen` tool, requesting real transparency. For authored SVG/procedural art, preserve and edit code/vector sources and rasterize with existing exporters; scripts may generate those declared sources/derivatives and procedural WAV. Raster image-model CLI/API generation remains an explicitly chosen alternative. Inspect tool capabilities at execution time instead of hardcoding a permanent resolution cap.
+4. Validate sound calls and audition when a playback path is available; distinguish contract checks from listening. Review masters, analyze alpha, then explicitly clean identified exterior residue into new files. Preserve ambiguous content. Verify silhouettes, scale, pivots and frame continuity before export.
+5. Check seamless texture/audio joins, source/output hashes and deterministic regeneration when applicable. Use the responsible-ad reference only for requested monetization or affected game transitions. Reuse existing exporters and regenerate every affected atlas PNG/JSON, frame map, HUD, archive card, preview, menu and Android/iOS density. Record provenance and verify outputs before handing back.
+
+## Collaborating skills
+
+`ti-game` and `ti-synthengine` have equal importance in their own domains: native representation/motion/events and synthesis/sound behavior. Coordinate both when the task involves audiovisual work; do not duplicate their manuals.
+
+- Read `ti-game` for sprites, sheets, animation, atlas, particles and parallax integration. Verify APIs against its current references and installed build.
+- Read `ti-synthengine` for creation or editing of synthesized effects, variants, music, ambience, stereo placement and audiovisual timing. The identifier is **`ti.synthengine`**. Read its current API/lifecycle contract before proposing calls.
+- Read `ti-admob-unified` for requested ad integration, configuration and providers using **`ti.admob.unified`**; the responsible-ad guide adds game experience criteria without duplicating that module manual.
+- Read `purgetss` for its existing asset exporters and the Titanium/UI/Alloy skills relevant to the destination. Detect Alloy vs. Classic.
+- Creating drawings does not require installing modules. An image does not authorize a new mechanic, sound, collision profile or balance change.
+
+## Acceptance
+
+Validate with `scripts/validate_manifest.py`; analyze images with `scripts/alpha_tools.py`. Separate technical validation, visual review and listening on a device in the result. A valid manifest is not artistic approval, and an accepted synthesis call is not sound-quality certification. Report missing resources or unverified runtime behavior explicitly. Keep physics and movement native; preserve authorized rendering exceptions.

package/skills/ti-game-assets/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Ti Game Assets"
+  short_description: "Create game art and synthesized sound assets"
+  default_prompt: "Use $ti-game-assets to prepare a complete game asset set and validate its exports."

package/skills/ti-game-assets/references/alpha.md

@@ -0,0 +1,26 @@
+# Analyze alpha before changing it
+
+The scripts need Python 3 and Pillow. In an environment without Pillow, use a project-approved environment or a disposable virtual environment (`python3 -m venv /tmp/game-art-env`, then its `bin/pip install Pillow`). Set `PYTHONDONTWRITEBYTECODE=1` when running installed helpers to avoid generated files in the skill package.
+
+```bash
+python3 scripts/alpha_tools.py master.png --report /tmp/master-alpha.json --preview /tmp/master-alpha.png
+```
+
+Analysis is the default. The JSON reports dimensions, alpha range, translucent pixel count and bounding boxes at 1, 4, 8, 16 and 32 over 255 (inclusive). The preview shows threshold boxes on checkerboard and light/dark backgrounds. Inspect the source at full size too.
+
+Profiles are `pixel-art`, `hard-surface`, `soft-fx`. For defined edges, start evaluating at 8/255 with protection equivalent to one logical pixel: set `--logical-size W H` for pixel art; padding is the ceiling of master/logical scale on each axis. Without a logical grid hard-surface padding is one source pixel. These are evaluation starting values, not universal removal thresholds.
+
+Cleaning is explicit and produces new files:
+
+```bash
+python3 scripts/alpha_tools.py master.png --profile pixel-art --logical-size 64 64 \
+  --clean /tmp/master-clean.png --protect 40 40 984 984 \
+  --threshold 8 --reason 'Reviewed isolated exterior generator residue' \
+  --report /tmp/clean.json --preview /tmp/clean-comparison.png
+```
+
+`--protect` is an exclusive-right/bottom rectangle in source pixels. Everything inside it is preserved byte-for-byte in RGBA. Only alpha outside is zeroed; RGB is preserved everywhere. Choose a rectangle enclosing *all* legitimate pieces, including detached pieces and faint emissions. Never delete components merely because they are small, and never binarize the whole image. A rectangle can leave residue between pieces; preserve it and use a reviewed image edit if a more precise region is needed.
+
+For defined edges, `--auto-protect` proposes the threshold bbox plus logical padding; use it for a reviewed trial only. The report records region, tolerance, reason, removed pixels and original/candidate boxes; the preview compares before/after. Reject a candidate that removes content. Soft smoke, explosions and halos preserve alpha by default and require explicit `--protect` before cleaning. If no threshold bbox exists, do not infer an empty image from that threshold: retain the source and inspect lower thresholds.
+
+Optional `--crop` trims the cleaned image at alpha >= 1. It refuses empty content. `--crop-box X0 Y0 X1 Y1` chooses a common canvas for sequences and must enclose all remaining alpha. Both require cleaning first. Record offset, original and output dimensions in the report; subtract offset from a source pivot to get the trimmed pivot. Independent tight crops are unsuitable for animation: choose the union of all frames, keep common offsets/canvases, and preserve effect growth. Never overwrite a master or an existing output.

package/skills/ti-game-assets/references/art-direction.md

@@ -0,0 +1,37 @@
+# Art contract and masters
+
+Before drawing, read the project's workflow/inventory and inspect its actual reference images. Record style, palette (swatches where useful), materials, texture, perspective, orientation, silhouette, contrast and detail density for each set. A rusty scrap collection cannot dictate a clean spaceship or a different world's palette. Separate the visual style reference from a composition reference and from an edit target.
+
+For raster-authored art, keep each individual HD PNG with real alpha in the source-of-truth directory, alongside prompt, generation/edit provenance and reference roles. Use `image_gen` for raster creation/edits; request `transparent_background: true` for cutouts. Inspect each result on light, dark and checkerboard backgrounds: a painted checkerboard is not transparency. Preserve authored SVG/procedural pipelines when the project uses them or the user requests them; read [vector-sources.md](vector-sources.md). Those scripts author editable geometry and render derivatives, rather than editing raster drawings. CLI/API generation is an explicitly chosen alternative, not an automatic fallback.
+
+Gameplay sprites must have no cast, ground or exterior drop shadows, especially moving/rotating objects. Internal shading is allowed. Declare intentional light emission or halos as effects so alpha cleanup preserves them. Background art can have lighting appropriate to its composition.
+
+## Canvas use and HD detail
+
+Generate each individual sprite as a separate transparent HD master, using as much of the available canvas as its complete silhouette permits. Request tight framing at generation time, an appropriate aspect ratio when supported, and only the narrow transparent edge needed to retain the entire outline and declared effects. Do not default to 78%, 80%, generous margins or a fixed padding percentage. Irregular shapes naturally leave transparent areas; maximum canvas use does not mean distorting or clipping them to fill every pixel.
+
+Inspect the current tool's capabilities and each output's actual dimensions. Outputs observed around 1254×1254 or nearly 1400 pixels wide are observations, not guaranteed sizes or resolution ceilings. Request the highest suitable supported generation quality and retain the original pixels. A sprite displayed at 32×32 still deserves a detailed HD source; native sizes, atlas cells and density exports do not set master resolution.
+
+For HD art, preserve the world's crisp geometry, clean contours, textures, material reflections, controlled gradients and internal shading. Review both full resolution and intended display sizes. A larger file alone does not establish quality. Alpha-tight cropping may remove residual empty space without resampling; it neither creates missing detail nor substitutes for generating a well-framed subject. If excessive margins leave the subject too small or poorly defined, regenerate it. Do not upscale a small drawing and call it an HD master.
+
+Specify the required finish in the generation prompt, not merely "HD" or a large pixel size: finely resolved material textures and joints, clean continuous gradients without banding or warped shading, precise straight lines, smooth regular curves, clearly delineated forms and crisp contours. Reflections, bevels, highlights and shadows must describe the object's structure coherently. Preserve the intended texture density rather than adding random detail to fill space. Review these features at native master resolution and after reduction to every relevant display size; regenerate defects in the source instead of relying on sharpening or downscaling to hide them. Pixel art follows its logical-block contract below rather than these continuous-gradient requirements.
+
+When the user requests reconstruction of manufactured geometry, distinguish recognizable design/topology from defects in the reference rendering. Use the original as a design reference rather than preserving warped contours, uneven rings, wavy gradients or smeared highlights as invariants. Define the required straight panel edges, regular curves, concentric rings, bevels and mechanical joints explicitly. Require geometric symmetry only where the design calls for it; if matching illumination is also requested, specify balanced lighting and corresponding highlights/shadows. Review the result against the stated improvement: a near-identical copy with minor sharpening does not satisfy a request for substantial reconstruction. Preserve deliberate asymmetry and other styles when their contract requires them.
+
+Keep documented common canvases, scale and pivots for intact/damaged states and animation sequences. Explosions reserve the maximum intended radius across frames; propulsion reserves its declared flame extent; asteroid sizes follow the world's variant contract. These technical needs can require empty space. There is no universal occupancy percentage by category. Record any deliberate margin with its reason, actual generation dimensions and subsequent crop offsets. Repeating textures and backgrounds follow their edge-continuity/composition contracts rather than individual-sprite cropping.
+
+## Pixel art
+
+Declare a logical size, typically 32×32, 64×64, 128×128 or 256×256; justify other sizes. Require a strict grid with proportional pixel blocks, consistent block size, constrained palette and no subpixel edge shading. Keep the HD master. Prepare the logical output with nearest-neighbor resampling, then inspect palette and borders at integer zoom: nearest-neighbor resizing alone cannot repair a generator's inconsistent grid. Correct the drawing when necessary. Inspect current image-generator capabilities before choosing master size; no fixed tool-resolution maximum belongs in this contract.
+
+Define block size from the actual final presentation, not from the HD file's resolution or the phrase "pixel-art style". For example, a 32×32 impact and a 64×64 explosion need different logical grids: an HD master near 1280 pixels wide would represent each logical pixel with roughly 40 or 20 source pixels respectively. These are illustrative ratios, not fixed generator dimensions. Request uniform square blocks aligned to the logical grid, with flat color/alpha inside each block; prohibit tiny texture, subpixel sparks and mixed block sizes that disappear or blur after reduction.
+
+Distinguish atlas cell size from visible phase extent. If a 64×64 cell shows a phase only 36 pixels wide, define the source-to-logical mapping for that 36-pixel visible extent or keep a registered 64×64 logical canvas whose artwork occupies 36 pixels. Do not independently maximize all frames and then resize them by different arbitrary factors: that changes apparent block size. Preserve the sequence's intended growth and pixel scale through the documented exporter. Compare states, frames and asteroid size variants at actual game size and integer nearest-neighbor zoom, not only as large HD previews.
+
+Pixel-art smoke can use progressive partial alpha without becoming painted HD smoke. Use deliberate square clusters with controlled alpha levels, transparent gaps and lower-alpha outer clusters; each cluster remains flat RGBA on the same grid as the effect. Preserve those alpha levels during export. Do not replace the smoke with opaque grey polygons, apply binary-alpha cleanup, introduce blurred subpixel fringes or resample pixel art with smoothing. HD effects instead use continuous soft alpha and their declared HD filtering.
+
+## States and sequences
+
+Maintain silhouette, scale, orientation, canvas and pivot between intact/damaged variants. An explosion may grow; reserve its maximum canvas and keep the same anchor throughout. Review contact sheets and a playback preview for animation continuity, frame order, lighting drift and generator deviations. Correct deviations before integration, rather than hiding them in changing hitboxes.
+
+Cover the families the world needs: players, enemies, allies, obstacles, ammunition, rewards, ambient objects and backgrounds. Declare omissions intentionally in the contract; no universal file count applies to every world.

package/skills/ti-game-assets/references/integration.md

@@ -0,0 +1,49 @@
+# Exports and audiovisual integration
+
+Find and reuse project exporters before writing another pipeline. A change to a master is complete only after regenerating affected atlas PNG/JSON, frame map, HUD, archive cards, previews, menus and Android/iOS densities. Record commands, input/output paths and validation results. Check transparent borders, aliases, sequence order and dimensions; make contact sheets for visual review.
+
+For atlas packing record padding and extrusion chosen for the filter/mipmap strategy; check adjacent-frame bleeding in the actual renderer. HD gradients are not pixel art: select filtering per style. For pixel art default to `SpriteSheet` `smoothing: false` and sprite `pixelSnap: true`, while preserving an explicitly authorized project exception. `pixelSnap` aligns only the drawn anchor to framebuffer pixels; it neither changes physics nor eliminates raster changes at arbitrary rotation angles. Do not add JS frame loops to round motion or angles.
+
+Consult `ti-game` for the installed native contract before choosing atlas, animation, particle or parallax calls. Consult Titanium/UI and PurgeTSS only for applicable output paths and project type. Check texture dimensions against device/build capabilities; estimate uncompressed RGBA memory as width × height × 4 bytes per texture, with mipmaps, copies and concurrent textures accounted for separately. Read [repeating-textures.md](repeating-textures.md) for repeat axes, neighbor topology and seam/phase checks, and [vector-sources.md](vector-sources.md) for deterministic SVG exports. Test seams in repeating backgrounds at their actual scale. Keep three parallax layers independent (far, middle, near), with transparent foregrounds where required, increasing order and explicit repeat/displacement. Native scrolling/motion must remain native.
+
+Art updates do not alter collision geometry. If sources or approved collision profiles change, regenerate collision overlays and review impact zones independently from the drawings. Never infer physical mechanics from the existence of a frame.
+
+## Export only what each consumer uses
+
+Before exporting menus, previews, cards or density variants, inspect their actual UI/resource references, including dynamic names. Declare an explicit selection per destination and identify the view, controller or runtime loader that consumes each resource. The complete world inventory belongs in canonical sources; it does not automatically belong in every derived folder. Do not use all source filenames, atlas frames, aliases or pre-existing destination files as the selection for a UI folder.
+
+For example, a gallery that shows one player ship per world needs only that ship's menu icon. A Hangar that switches intact/damaged ship states needs those two HD previews, not HD copies of every enemy, projectile, reward and animation frame. An Archive may legitimately need a much larger selection when its cards actually display those assets. Covers and their full-size viewers follow their own consumers. These are examples, not fixed counts or naming requirements for other games.
+
+When a selection changes, remove only obsolete generated derivatives in the owned destination and all affected Android/iOS density folders. Preserve canonical masters, edit history and provenance. PurgeTSS `images` generates files but does not delete obsolete outputs. Validate both presence of required resources and absence of unused extras; when compiling an app, inspect the package so stale build copies cannot hide a failed cleanup. Regeneration must reproduce the same selection without restoring removed files.
+
+## Sprite-sheets for ti.game: integer dimensions and packing
+
+These sizing and rounding rules apply to every required sprite-sheet size, including rectangular cells and non-power-of-two drawing dimensions. The 32-pixel examples below illustrate the rule; they are not a size restriction.
+
+Keep the individual HD masters as sources. Build the runtime sprite-sheet from those sources with the project's deterministic exporter, choosing either a regular grid (`frameWidth`/`frameHeight`) or a TexturePacker-compatible PNG/JSON atlas (`atlas`) according to the current `ti-game` contract. Define cell dimensions, frame names/order, aliases, animation sequence, pivot and filtering before packing; sprite-sheet cells are runtime containers, not the resolution of the HD originals.
+
+Calculate proportional reduction from the original source dimensions, then round each resulting image dimension to the nearest positive integer: `floor(value + 0.5)` for positive pixel sizes. Preserve the fixed integer axis and round only the fractional result on the other axis. Do not always truncate or always round up, retain fractional PNG dimensions, or resize repeatedly through intermediate reductions.
+
+| Proportional result | Final drawing size |
+| --- | --- |
+| Height fixed at 32; width computes to 28.3 | 28×32 pixels |
+| Width fixed at 32; height computes to 17.7 | 32×18 pixels |
+| Width computes to 28.5; height fixed at 32 | 29×32 pixels |
+
+For a source `W×H` fitted inside a `cellW×cellH` limit, calculate `scale = min(cellW / W, cellH / H)` and round `W * scale` and `H * scale` once. If one axis is explicitly fixed, use its scale first and verify that the other axis fits the cell. If it does not fit, fit against both limits; non-proportional compression requires an explicit project contract. Record the final integer dimensions and effective ratio. The tiny ratio difference introduced by integer rounding is expected; the master remains unchanged.
+
+Place the resulting image at integer offsets inside its transparent cell: `x = floor((cellW - width) / 2)`, `y = floor((cellH - height) / 2)`. When the gap is odd, the extra empty pixel goes to the right/bottom; do not place the image at half-pixel coordinates. Thus 28×32 in a 32×32 cell starts at (2,0), and 32×18 starts at (0,7). Preserve a declared noncentral pivot or registered animation alignment rather than recentering it blindly. Atlas rectangles (`x`, `y`, `w`, `h`), grid cells, padding and extrusion also use integer source pixels.
+
+For animations, retain common cell dimensions, pivot and sequence order. Preserve any documented phase-size progression; separately scaling every frame to the full cell erases growth. Keep pixel-art block size proportional to the final visible extent, as specified in [art-direction.md](art-direction.md). Use nearest-neighbor reduction for pixel art and preserve its partial-alpha levels. Use the declared HD resampling/filter for gradients, reflections and continuous smoke alpha. Neither style uses binary-alpha cleanup by default.
+
+Generate PNG, JSON and runtime frame map together; verify that semantic aliases resolve to the intended frames, all rectangles fit, padding/extrusion prevents neighbour bleeding and sequences stay aligned. Do not silently enable rotation/trimming unless the installed module and project pivot/offset handling support them. Inspect native-size contact sheets and playback previews, then distinguish export validation from visual acceptance in the actual renderer. This integer rounding belongs to image preparation and packing; do not round physics positions or introduce JS per-frame loops.
+
+## Sound coordination
+
+Use `ti-game` and `ti-synthengine` together for creating/refining sound assets and audiovisual coordination. Read [sound-assets.md](sound-assets.md) for the acoustic palette, meaningful variations, stereo and audition workflow. Map semantic events (shot, impact, explosion, thrust, reward, damage, UI, ambience) to created or existing sound/pattern references in the manifest. Count audio resources separately from PNGs and frames. Creating visual art alone does not authorize a sound library or module installation.
+
+Read the current `ti-synthengine` API, guide and relevant sound references before writing calls: options, envelopes, timing, results, pause behavior and cleanup belong to that contract, not to this skill. Preserve the project's engine owner, clock and lifecycle. Distinguish discrete effects, sustained sounds and music; do not play a sound for every animation frame. Use discrete native events and documented mechanisms. Avoid inventing indefinite voices, per-voice control, a pause API or sample-accurate sync; check documented limitations. Handle rejected calls and cleanup at their existing ownership level.
+
+Report separately: export/contract validation, visual inspection, runtime synchronization and device listening. No script result certifies aesthetic or acoustic quality.
+
+For requested monetization or affected ad transitions, read [responsible-ads.md](responsible-ads.md). Coordinate native pause/audio cleanup with the existing game and ad owners; asset work alone does not enable advertising.