minimojs 1.0.0-alpha.3 → 1.0.0-alpha.5

package/README.md

@@ -1,332 +1,97 @@
 # MinimoJS v1
 
-> Ultra-minimal, flat, deterministic 2D web game engine.  
-> Emoji-only sprites · Degrees rotation · Milliseconds timing · rAF loop · TypeScript-first · LLM-friendly
+Ultra-minimal, deterministic 2D web game engine for browser games.
 
----
+MinimoJS focuses on a flat API, direct game-loop control, and fast iteration for small games and agent-generated prototypes.
 
-## Install
+This README is intentionally high-level. It explains what the project is and how to use it quickly, without listing the full API surface.
 
-```bash
-npm install minimojs
-```
+## What MinimoJS Is
 
-Or build from source:
+- ESM-only TypeScript-first engine
+- Single `Game` entry point
+- Emoji-based sprite rendering
+- rAF-driven loop (timers/animations/updates)
+- Responsive auto-centered canvas
 
-```bash
-npm install
-npm run build
-```
+## Core Conventions
 
-Output: `dist/minimo.js` + `dist/minimo.d.ts`
+- Time arguments are milliseconds (`ms`)
+- Rotation uses degrees
+- Runtime update delta (`dt`) is seconds
+- Coordinate system is center-based world space
+- Positive Y goes downward
 
----
+## What It Intentionally Avoids
 
-## Examples
-
-- `examples/chickens-eggs-basket/` — Pollos lanzan huevos y una cesta los recoge.
-- `examples/run-dino-run/` — Classic endless runner: jump with the dino and avoid obstacles.
+- Scene manager/ECS architecture
+- Heavy physics engine features
+- Image spritesheets and asset pipelines
+- Nested subsystem APIs
+- `setTimeout` / `setInterval` game loops
 
-Run examples from project root with a static server:
+## Install
 
 ```bash
-npx serve .
+npm install minimojs
 ```
 
-Open:
-
-`http://localhost:3000/examples/chickens-eggs-basket/`
-
-`http://localhost:3000/examples/run-dino-run/`
-
----
-
 ## Quick Start
 
-```html
-<script type="module">
-  import { Game, Sprite } from "./dist/minimo.js";
-
-  const game = new Game(800, 600);
-  game.gravityY = 980;
-
-  const player = new Sprite("🐢");
-  player.x = 400;
-  player.y = 300;
-  player.size = 48;
-  player.gravityScale = 1;
-  game.add(player);
-
-  game.onUpdate = (dt) => {
-    if (game.isKeyDown("ArrowLeft"))  player.vx = -200;
-    else if (game.isKeyDown("ArrowRight")) player.vx =  200;
-    else player.vx = 0;
-
-    if (game.isKeyPressed(" ") && player.y >= 550) player.vy = -600;
-
-    if (player.y > 700) game.reset();
-
-    game.drawText(`x: ${Math.round(player.x)}`, 10, 10, 16, "#ffffff");
-  };
-
-  game.start();
-</script>
-```
-
----
-
-## Core Rules
-
-| Rule | Value |
-|---|---|
-| All time parameters | **milliseconds** |
-| All rotations | **degrees** |
-| Game loop | **requestAnimationFrame only** |
-| Sprites | **emoji only** |
-| Canvas layout | **auto-centered + responsive scaling** |
-| Coordinate system | **center-based world space** |
-| Y-axis | **positive = down** |
-
----
-
-## API Reference
-
-### `new Game(width?, height?)`
-
-Creates the engine, creates its own canvas, and appends it to the page.
-Canvas is automatically centered and scaled to the maximum viewport space
-while keeping aspect ratio.
-
-```ts
-const game = new Game(800, 600);
-```
-
----
-
-### Sprite Management
-
-| Method | Description |
-|---|---|
-| `game.add(sprite)` | Register a Sprite instance with the engine and return it |
-| `game.destroySprite(sprite)` | Remove a sprite from the engine |
-| `game.getSprites()` | Read-only snapshot of all sprites |
-
-**Creating sprites** — instantiate `Sprite` directly or subclass it:
-
-```ts
-// Plain instantiation
-const coin = new Sprite("🪙");
-coin.x = 300; coin.y = 200; coin.size = 32;
-game.add(coin);
-
-// Subclassing
-class Enemy extends Sprite {
-  health = 3;
-  constructor(x: number, y: number) {
-    super("👾");
-    this.x = x; this.y = y; this.size = 40; this.gravityScale = 1;
-  }
-}
-const enemy = game.add(new Enemy(600, 100));
-```
-
-**Sprite properties and defaults:**
-
-| Property | Type | Default | Description |
-|---|---|---|---|
-| `sprite` | `string` | — | **Required in constructor.** Single emoji |
-| `x` | `number` | `0` | World X (center), pixels |
-| `y` | `number` | `0` | World Y (center), pixels |
-| `size` | `number` | `32` | Bounding square size, pixels |
-| `rotation` | `number` | `0` | Degrees, clockwise |
-| `flipX` | `boolean` | `false` | Visual horizontal mirror |
-| `flipY` | `boolean` | `false` | Visual vertical mirror |
-| `ignoreScroll` | `boolean` | `false` | Render in screen space (ignore `scrollX`/`scrollY`) |
-| `alpha` | `number` | `1` | Opacity 0–1 |
-| `visible` | `boolean` | `true` | Render toggle |
-| `layer` | `number` | `0` | Render order (higher = on top) |
-| `vx` | `number` | `0` | Horizontal velocity, px/s |
-| `vy` | `number` | `0` | Vertical velocity, px/s |
-| `gravityScale` | `number` | `0` | Gravity multiplier |
-
----
-
-### Public State
-
-| Property | Type | Description |
-|---|---|---|
-| `game.gravityX` | `number` | Horizontal gravity acceleration, px/s² |
-| `game.gravityY` | `number` | Vertical gravity acceleration, px/s² |
-| `game.scrollX` | `number` | Camera scroll X offset, pixels |
-| `game.scrollY` | `number` | Camera scroll Y offset, pixels |
-| `game.background` | `string \| null` | Solid canvas background color |
-| `game.backgroundGradient` | `{ from: string; to: string } \| null` | Vertical canvas gradient (`from` top, `to` bottom) |
-| `game.pageBackground` | `string \| null` | Full page (`document.body`) background color |
-| `game.pointerX` | `number` | Pointer X in screen space, pixels (read-only) |
-| `game.pointerY` | `number` | Pointer Y in screen space, pixels (read-only) |
-| `game.width` | `number` | Canvas width, pixels (read-only) |
-| `game.height` | `number` | Canvas height, pixels (read-only) |
-| `game.onCreate` | `() => void` | Scene creation callback (start + reset) |
-| `game.onUpdate` | `(dt: number) => void` | Frame callback. `dt` = seconds |
-
----
-
-### Background
-
-```ts
-game.background = "#92d7ff";      // solid canvas background
-game.backgroundGradient = { from: "#92d7ff", to: "#5ca44f" }; // vertical gradient
-game.pageBackground = "#f4e4bc";  // page background
-// If backgroundGradient is set, it takes priority over background.
-```
-
----
-
-### Collision (AABB, no resolution)
-
-```ts
-game.overlap(a, b)               // → boolean
-game.overlapAny(listA, listB)    // → [Sprite, Sprite] | null
-```
-
-Bounding box is a square centered at `(x, y)` with side `size`. Rotation ignored.
-
----
-
-### Input
-
 ```ts
-// Keyboard
-game.isKeyDown("ArrowRight")   // true every frame while held
-game.isKeyPressed("ArrowRight") // true only on first frame of press
-
-// Pointer (mouse / touch)
-game.isPointerDown()   // true every frame while held
-game.isPointerPressed() // true only on first frame of press
-game.pointerX          // screen space X
-game.pointerY          // screen space Y
-```
-
----
-
-### Sound
-
-```ts
-game.sound(freq, durationMs)
-// Square wave only. freq in Hz. durationMs in milliseconds.
-game.sound(440, 100);  // 440 Hz beep for 100ms
-```
-
----
-
-### Animation
-
-```ts
-game.animateAlpha(sprite, to, durationMs, onComplete?)
-game.animateRotation(sprite, toDegrees, durationMs, onComplete?)
-// Linear interpolation. durationMs in milliseconds.
-// New animation on same property replaces the current one immediately.
-```
+import { Game, Sprite } from "minimojs";
 
----
-
-### Timers
-
-```ts
-const id = game.addTimer(delayMs, repeat, callback)
-game.clearTimer(id)
-// rAF-driven (no setTimeout). delayMs in milliseconds.
-// repeat=true fires every delayMs; repeat=false fires once then removes.
-// All timers cleared on game.reset().
-```
-
----
-
-### Text Overlay
-
-```ts
-game.drawText(text, x, y, fontSize, color?, centered?)
-// Screen space (ignores scroll). Must be called every frame.
-// Always renders on top of all sprites.
-// Font is always monospace (fixed by engine).
-// Default color: "#ffffff"
-// centered=true makes (x, y) the center anchor (both axes).
-```
-
----
-
-### Misc
-
-```ts
-game.isMobileDevice() // true on likely mobile/touch-first devices (heuristic)
-game.random()  // Math.random() wrapper → [0, 1)
-game.reset()   // Full state clear + calls onCreate() for scene rebuild
-game.start()   // Start rAF loop
-game.stop()    // Stop rAF loop
-```
-
----
+const game = new Game(800, 600);
+game.gravityY = 980;
 
-## Scene Creation and Reset
+const player = game.add(new Sprite("🐢", 400, 300, 48));
+player.x = 400;
+player.y = 300;
+player.gravityScale = 1;
 
-MinimoJS has no scene system. Use `onCreate()` to build scenes and `reset()` to rebuild:
+game.onUpdate = (dt) => {
+  if (game.isKeyDown("ArrowLeft")) player.vx = -200;
+  else if (game.isKeyDown("ArrowRight")) player.vx = 200;
+  else player.vx = 0;
 
-```ts
-game.onCreate = () => {
-  // Scene init — called on start and after reset()
-  const skull = new Sprite("💀");
-  skull.x = 400; skull.y = 300; skull.size = 96;
-  game.add(skull);
+  if (game.isKeyPressed(" ")) player.vy = -600;
+  game.drawText("MinimoJS", 10, 10, 16);
 };
 
-function goToGameOver() {
-  game.reset(); // clears everything, calls onCreate()
-}
+game.start();
 ```
 
----
-
-## Forbidden Features
+Note: `drawText()` uses `"Press Start 2P", monospace`. Load the font in your HTML if you want pixel-font styling.
 
-These do **not** exist in MinimoJS v1:
-
-- Scene system / scene manager
-- Entity Component System (ECS)
-- Physics engine
-- Camera zoom
-- Nested APIs
-- Text input
-- Parallax
-- Multiple cameras
-- Collision resolution
-- Image sprites (PNG/SVG)
-- `setTimeout` / `setInterval`
+## Examples
 
----
+- `examples/chickens-eggs-basket/`
+- `examples/run-dino-run/`
+- `examples/space-invader/`
+- `examples/super-minimo-bros/`
+- `examples/scale-shift/`
 
-## Build
+Run locally from the `minimojs` directory:
 
 ```bash
-npm run build    # compile to dist/
-npm run clean    # remove dist/
-npm run rebuild  # clean + build
-npm run pack:check # preview npm package contents
+npx serve .
 ```
 
-TypeScript target: **ES2020**, module: **ES2020**, strict mode, declaration files enabled.
+## Full API Reference
 
----
+For complete API details, use source/docs generated from types:
 
-## NPM Publish Notes
+- `dist/minimo.d.ts`
+- `src/minimo.ts` (JSDoc)
 
-- `prepack` runs `npm run build` automatically before packaging.
-- `files` whitelist includes only:
-  - `dist/`
-  - `README.md`
-  - `LICENSE`
-- Example code under `examples/` is for repository usage and is excluded from the npm package.
+## Development
 
----
+```bash
+npm run build
+npm run clean
+npm run rebuild
+npm run pack:check
+```
 
 ## License