# Islumina AI Ecosystem

Islumina is a family of small, independently published TypeScript modules for browser, Worker, WebView, and game runtimes. The packages have no required cross-package dependencies and are currently aligned at version 0.5.9 under the MIT licence.

Authoritative source: https://github.com/islumina
Human documentation: https://islumina.org/en/guides/ecosystem/
Agent quick start: https://islumina.org/en/guides/ai-quick-start/
Hosted read-only Playground: https://islumina.org/playground/

## Selection guide

- `aiecsjs`: game data, entities, components, queries, relations, and serialization.
- `aispritejs`: renderer-independent sprite animation graph. Use `aispritejs/pixi` for PixiJS v8, `aispritejs/atlas` for atlas parsing, and `aispritejs/schema` for its JSON Schema.
- `aiaudiojs`: audio lifecycle over Howler. Install its `howler` peer dependency.
- `aieventjs`: typed in-process event emitter with abort-aware subscriptions.
- `aifsmjs`: deterministic application or game-logic finite-state machine.
- `aiquadtreejs`: 2D collision broadphase; callers perform narrow-phase checks.
- `aipooljs`: fixed-size object reuse for bullets, particles, and other hot-path objects.
- `aibridgejs`: iframe, Flutter WebView, mock, or custom transport communication.
- AI Sprite Studio (`aisprite-studio`): sprite asset request, reference repair, generation, QA, packing, ai*js preview workflow, and local stdio MCP bridge for AI image generation.

Install only the modules required by the application. Inspect `package.json` exports and the package's own `llms-full.txt` before generating code.

## PixiJS sprite path

```bash
pnpm add aispritejs pixi.js
```

```ts
import { createPixiSpriteAnimator } from "aispritejs/pixi";

const view = createPixiSpriteAnimator(sprite, graph, spritesheet);
view.setInput("speed", 1);
view.update(deltaMs);
view.dispose();
```

The graph uses lowercase input types (`number`, `boolean`, `trigger`), an `initial` state, `when` condition arrays, and `"*"` for any-state transitions. Validate external graphs before creating a runtime.

## AI Sprite Studio asset safety

The checked-in generated images are known failed outputs. They are fixtures for testing the pipeline and must not be used as shippable assets or visual references. A pack is approved only after file/dimension checks and visual QA both pass. The output atlas is intended to be consumed by a renderer such as PixiJS through `aispritejs`.

## Agent workflow

1. Read this index and the selected package's repository `llms-full.txt`.
2. Check `package.json` exports instead of inventing subpaths.
3. Use the repository's declared package manager.
4. Run available `typecheck`, `lint`, `test`, `build`, export, and size checks.
5. Treat atlases, bridge messages, serialized worlds, and snapshots as untrusted boundary data.
6. Keep game logic, data, rendering, and transport as separate responsibilities.

## Repository links

- https://github.com/islumina/aiaudiojs
- https://github.com/islumina/aibridgejs
- https://github.com/islumina/aiecsjs
- https://github.com/islumina/aieventjs
- https://github.com/islumina/aifsmjs
- https://github.com/islumina/aipooljs
- https://github.com/islumina/aiquadtreejs
- https://github.com/islumina/aispritejs
- https://github.com/islumina/aisprite-studio