minimojs 1.0.0-alpha.2 → 1.0.0-alpha.21

package/README.md

@@ -1,333 +1,130 @@
 # 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
+- Image-backed sprite rendering, with emoji as a zero-asset alternative
+- rAF-driven loop (timers/animations/updates)
+- Responsive auto-centered canvas
 
-```bash
-npm install
-npm run build
-```
-
-Output: `dist/minimo.js` + `dist/minimo.d.ts`
+## Core Conventions
 
----
+- 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
+- For new mobile-first games, prefer a portrait canvas of `720x1280`
 
-## Examples
+## What It Intentionally Avoids
 
-- `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.
+- Heavy scene-manager/ECS architecture
+- Heavy physics engine features
+- Spritesheets, texture atlases, 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);
-```
+import { DrawSprite, EmojiSprite, Game, type IScene } from "minimojs";
 
----
+const game = new Game(720, 1280);
+game.gravityY = 980;
 
-### Sprite Management
+class MeterSprite extends DrawSprite {
+  public value = 0.5;
 
-| 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;
+    super(160, 28, x, y);
   }
-}
-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
-```
-
----
+  redraw(ctx: CanvasRenderingContext2D) {
+    ctx.fillStyle = "#1a2236";
+    ctx.fillRect(0, 0, this.width, this.height);
+    ctx.fillStyle = "#7ce7ff";
+    ctx.fillRect(0, 0, this.width * this.value, this.height);
+  }
+}
 
-### Animation
+class DemoScene implements IScene {
+  private player: EmojiSprite | null = null;
+  private meter: MeterSprite | null = null;
 
-```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.
-```
-
----
+  onCreate() {
+    this.player = game.add(new EmojiSprite("🐢", 360, 640, 48));
+    this.player.gravityScale = 1;
+    this.meter = game.add(new MeterSprite(360, 80));
+    this.meter.ignoreScroll = true;
+  }
 
-### Timers
+  onUpdate(dt: number) {
+    if (!this.player) return;
 
-```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().
-```
+    if (game.isKeyDown("ArrowLeft")) this.player.vx = -200;
+    else if (game.isKeyDown("ArrowRight")) this.player.vx = 200;
+    else this.player.vx = 0;
 
----
-
-### Text Overlay
+    if (game.isKeyPressed(" ")) this.player.vy = -600;
+    if (this.meter) this.meter.value = Math.abs(this.player.vx) / 200;
+    game.drawText("MinimoJS", 10, 10, 16);
+  }
+}
 
-```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).
+game.start(new DemoScene());
 ```
 
----
-
-### Misc
+Note: `drawText()` uses `"Press Start 2P", monospace`. Load the font in your HTML if you want pixel-font styling.
 
-```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
-```
-
----
+## Examples
 
-## Scene Creation and Reset
+- `examples/chickens-eggs-basket/`
+- `examples/run-dino-run/`
+- `examples/space-invader/`
+- `examples/super-minimo-bros/`
+- `examples/scale-shift/`
+- `examples/background-desert/`
+- `examples/scene-lab/`
+- `examples/image-sprite-sad-plush/`
+- `examples/draw-sprite/`
+- `examples/pseudo-3d-racer/`
+- `examples/animations/`
 
-MinimoJS has no scene system. Use `onCreate()` to build scenes and `reset()` to rebuild:
+Run locally from the `minimojs` directory:
 
-```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);
-};
-
-function goToGameOver() {
-  game.reset(); // clears everything, calls onCreate()
-}
+```bash
+npx serve .
 ```
 
----
-
-## Forbidden Features
+## Full API Reference
 
-These do **not** exist in MinimoJS v1:
+For complete API details, use source/docs generated from types:
 
-- 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`
+- `dist/minimo.d.ts`
+- `src/minimo.ts` (JSDoc)
 
----
-
-## Build
+## Development
 
 ```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
+npm run build
+npm run clean
+npm run rebuild
+npm run pack:check
 ```
 
-TypeScript target: **ES2020**, module: **ES2020**, strict mode, declaration files enabled.
-
----
-
-## NPM Publish Notes
-
-- `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.
-
----
-
 ## License
 
 MIT