# Star Run sprite guide

The game uses a 480 × 270 logical canvas, scaled with nearest-neighbor pixels. The Miras 9 renders at 64 × 32 game pixels; enemies and obstacles render at 32 × 32. Collision boxes stay deliberately forgiving and do not follow the exhaust or tilt.

## Miras 9 hero: movement poses

The installed asset is `assets/miras9-approved-roll-v4.png`, edited with built-in imagegen from the user's approved sprite sheet. That sheet controls the weathered bright-orange texture, cockpit shape, swept engine housings, rails, and proportions; the preceding sheet supplies only the corrected viewing angles. Preserve the broad flat rectangular deck, two raised armor panels, projecting dark side rails, rear cockpit between bulky engine pods, belly panels and service hatches, and twin BLUE rear engines. The game nose faces RIGHT and the exhaust faces LEFT. Earlier sheets remain as unused previous versions.

- Transparent RGBA PNG, **1024 × 1536**, three vertical **1024 × 512** cells.
- Row 0: default side elevation. Row 1: moving UP exposes the underside at a 45° longitudinal roll. Row 2: moving DOWN exposes the top deck at the opposite 45° roll. Both banked poses retain a visible side face; neither is a straight top/bottom view. The nose-to-tail X axis stays horizontal in every row, with no nose-up/down pitch.
- These are movement states, not a timed animation. WASD, arrows, and touch select the pose. Stopping vertical movement, reaching a boundary, restarting, or pausing returns to level.
- All rows use the same scale. `anchorY: [294, 229, 245]` in `sprites.js` specifies each hull's center within its source row and compensates for the generated sheet's different padding. A replacement preview should align its hull centers to these coordinates. For newly published centered sheets use `[256, 256, 256]`.
- No runtime rotation, mirroring, background removal, or smoothing: the three rendered views come directly from the transparent sheet.
- Rendering uses nearest-neighbor sampling into the low-resolution canvas. The source PNG is preserved intact.
- Hero collisions remain a 7 px half-size box against obstacles and 9 px against enemy pellets. Shots start 25 px ahead of the ship center. Horizontal bounds include the wider sprite.

### Hero generation prompt

Built-in imagegen; approved sprite sheet supplied as appearance authority, previous sheet for angles only; transparent background enabled. Full prompts, including the targeted angle correction, are saved in `MIRAS9-APPROVED-PROMPT.md`.

> Preserve the reference geometry, burnt-orange palette and blue rear exhaust. Three vertically stacked poses: neutral side elevation; moving up rolls 45° to expose the belly and side; moving down rolls the opposite 45° to expose the upper deck and side. Nose right, engines left, longitudinal axis horizontal in all views. No pitch rotation. Transparent pixel-art sheet, 1024 × 1536, three 1024 × 512 cells.

## Ahmarian Patrol Skiffs

Both scout and fighter roles now use `assets/ahmarian-skiff-side.png`, a transparent 1024 × 1536 sheet with three 1024 × 512 rows: level side view, underside roll (up), top roll (down). Rendered footprint is 48 × 32 game pixels; source anchors are `[319, 303, 270]`. Nose faces LEFT and blue exhaust RIGHT. The original generated design is preserved separately as `assets/ahmarian-skiff-original.png`. Generation and side-view correction prompts are in `AHMARIAN-SKIFF-PROMPT.md`.

Both roles weave vertically and select roll poses from actual movement; near turnarounds or screen edges they return to level. Scout has one hull point and a faster weave; fighter has two hull points and aimed fire. Collision half-size remains a forgiving 10 px, excluding wings and exhaust.

## Obstacles: exact PNG contract

- One transparent RGBA PNG per unit: **128 × 32 pixels**, exactly.
- Four **32 × 32** cells, in one horizontal row, read left to right. No gutters, margins, captions, borders, or background.
- Center each frame at (16, 16). Keep the silhouette mostly inside the central 24 × 24 area. Leave transparent padding so animation does not clip.
- Same scale, center, orientation and silhouette across all frames. Animate thrusters, lights, or surface highlights; do not move the entire sprite between cells.
- Both enemies face **left**. Obstacles have no preferred direction.
- Limited 12–16 color palette, crisp pixel clusters, no antialiasing, gradients, shadows outside the sprite, or motion blur.
- Repeat an identical image in all four cells for static art.

| Key / suggested filename | Subject | Playback | Collision half-size |
| --- | --- | --- | --- |
| asteroid / asteroid.png | Cratered irregular rock | 6 fps | 13 px |
| trash / trash.png | Broken satellite or space junk | 4 fps | 10 px |

Collisions use centered boxes, deliberately forgiving for the hero. Player pellets add 3 px to target half-size. Transparent pixels are not inspected. Keep recognizable solid art in the center.

## Copyable image-generation prompt

Create a sprite sheet for a retro NES/SNES-inspired horizontal space shooter. Subject: [SUBJECT]. Facing [RIGHT for hero / LEFT for enemies]. Output exactly 128 by 32 pixels, transparent RGBA PNG, four equal 32 by 32 cells in a single horizontal row, no spacing. Each cell contains one complete centered sprite at the same scale and position, centered at (16,16), mostly within the central 24 by 24 pixels. Four seamless animation frames changing only [THRUSTER / LIGHTS / ROCK HIGHLIGHTS]. Crisp hand-placed pixel-art appearance, limited 12–16 color palette, hard edges, no antialiasing, no background, no text, no grid, no watermark, no perspective changes. All four frames face the same direction.

Image generators may not honor exact dimensions. Inspect and crop/resize with nearest-neighbor in a pixel editor to meet the contract before uploading. Do not merely squash a large sheet with incorrect cell boundaries.

## Preview and publish

1. Open Star Run from the homepage and expand **Sprite workshop**.
2. Select the unit and choose its PNG. Invalid dimensions are rejected; the previous sprite stays active. Preview uploads are local to this page, are never sent to a server, and disappear on reload.
3. To publish, place approved PNGs in `public/arcade/assets/` (create that directory when needed).
4. Set that unit's `src` in `public/arcade/sprites.js`, e.g. `src: 'arcade/assets/hero.png'`. Paths are relative to `arcade.html`. Deploy with the rest of the site. No gameplay edits needed.

Empty, missing, or invalid configured images fall back to built-in pixel art. Keep obstacle size/frames at 32/4; `fps` can be adjusted independently. Ships use their pose contracts above instead.

## Other art and game tuning

The CSS space background is in `public/arcade/arcade.css` under `.screen`. Moving parallax stars and pellet/explosion visuals are in `game.js`'s `render` and `burst` functions. A future background image can be added to `.screen` without replacing unit sprites. No background uploads are implemented yet.

Destruction uses `explode`, `updateEffects`, and `renderExplosions`: a short bright core, expanding stepped pixel lobes, orange fire, outward debris and dark fading smoke over 0.85 seconds. Asteroids use a mineral/dust palette. Nonlethal hits retain smaller sparks. Effects freeze when paused and are cleared on restart. Player destruction runs for 0.9 seconds before the game-over overlay appears.

`game.js` keeps spawning, movement, collision and rendering separate. `addObject` controls enemy/obstacle distribution and health; `update` sets movement, firing and bounded difficulty progression. Sectors advance every 25 seconds, spawns ramp down to a 0.35-second minimum, and enemy speed growth caps after 200 seconds. Runs end after three hits, with 1.6 seconds of protection per hit. Best score is saved on this browser when a run ends; there is no account or online leaderboard.

## Hosted mobile images (v0.97.15)

Hostinger CDN was verified to return 800 x 1200 versions of the 1024 x 1536 ship sheets for mobile user agents. Bundled sheets accept proportional resizing; source frame crops use the decoded image dimensions while display size and pose anchors retain their logical values. Custom sprite uploads still require the exact documented dimensions. The arcade regression covers mobile atlas acceptance, strict upload rejection, and resized pose cropping. When changing the loader, update the script cache token in arcade.html and rebuild the deployment ZIP.