docs: consolidate guides and polish documentation entry points

examples/guides/audio-reactive-visualization/spectrum-history.ts

@@ -0,0 +1,28 @@
+// #region guide:spectrum-history
+import { DataTexture, TextureFormat } from '@codexo/exojs';
+
+export class SpectrumHistory {
+  readonly texture = new DataTexture({ width: 256, height: 64, format: TextureFormat.R8 });
+  private column = 0;
+
+  get nextColumn(): number {
+    return this.column;
+  }
+
+  write(bands: Uint8Array): void {
+    if (bands.length !== 64) {
+      throw new Error('SpectrumHistory expects 64 byte-valued bands.');
+    }
+
+    for (let row = 0; row < 64; row++) {
+      this.texture.buffer[row * 256 + this.column] = bands[row];
+    }
+    this.texture.commitRect(this.column, 0, 1, 64);
+    this.column = (this.column + 1) % 256;
+  }
+
+  destroy(): void {
+    this.texture.destroy();
+  }
+}
+// #endregion guide:spectrum-history

examples/guides/audio-reactive-visualization/spectrum-scene.ts

@@ -0,0 +1,31 @@
+// #region guide:spectrum-scene
+import { Color, Graphics, type RenderingContext, Scene } from '@codexo/exojs';
+import { AudioAnalyser } from '@codexo/exojs-audio-fx';
+
+export class SpectrumScene extends Scene {
+  private analyser!: AudioAnalyser;
+  private readonly bars = new Graphics();
+  private readonly barColor = new Color(90, 180, 240);
+
+  override init(): void {
+    this.analyser = this.track(new AudioAnalyser({ source: this.app.audio.music, fftSize: 1024 }));
+    this.root.addChild(this.bars);
+  }
+
+  override update(): void {
+    const levels = this.analyser.getSpectrumLog(undefined, { bands: 32 });
+    const width = this.app.width / levels.length;
+
+    this.bars.clear();
+    this.bars.fillColor = this.barColor;
+    for (let index = 0; index < levels.length; index++) {
+      const height = (levels[index] / 255) * this.app.height * 0.6;
+      this.bars.drawRectangle(index * width, this.app.height - height, Math.max(1, width - 2), height);
+    }
+  }
+
+  override draw(context: RenderingContext): void {
+    context.render(this.root);
+  }
+}
+// #endregion guide:spectrum-scene

examples/guides/coordinates-and-views/split-views.ts

@@ -0,0 +1,19 @@
+// #region guide:split-views
+import { type RenderingContext, type RenderNode, View } from '@codexo/exojs';
+
+export const createSplitViews = (width: number, height: number): { left: View; right: View } => ({
+  left: new View(0, 0, width / 2, height).setViewport(0, 0, 0.5, 1),
+  right: new View(0, 0, width / 2, height).setViewport(0.5, 0, 0.5, 1),
+});
+
+export const drawSplitWorld = (context: RenderingContext, world: RenderNode, left: View, right: View): void => {
+  context.render(world, { view: left });
+  context.render(world, { view: right });
+};
+// #endregion guide:split-views
+
+// #region guide:pointer-world
+import type { PointLike } from '@codexo/exojs';
+
+export const pointerInWorld = (view: View, pointer: PointLike): PointLike => view.screenToWorld(pointer.x, pointer.y);
+// #endregion guide:pointer-world

examples/guides/lighting/basic-lightmap.ts

@@ -0,0 +1,31 @@
+// #region guide:basic-lightmap
+import { Application, Color, Graphics, type RenderingContext, Scene } from '@codexo/exojs';
+import { LightmapLighting, PointLight } from '@codexo/exojs-lighting';
+
+class LightingScene extends Scene {
+  override init(): void {
+    const lighting = new LightmapLighting(this.app, { ambient: new Color(25, 25, 35) });
+    const floor = new Graphics();
+    const lamp = new PointLight({ radius: 360, color: new Color(255, 190, 100) });
+
+    this.systems.add(lighting);
+    floor.fillColor = new Color(180, 190, 210);
+    floor.drawRectangle(0, 0, this.app.width, this.app.height);
+    lamp.setPosition(this.app.width / 2, this.app.height / 2);
+    this.root.addChild(floor, lamp);
+    lighting.add(lamp);
+  }
+
+  override draw(context: RenderingContext): void {
+    context.render(this.root);
+  }
+}
+
+const app = new Application({
+  scenes: { LightingScene },
+  canvas: { width: 800, height: 600, mount: 'body' },
+  clearColor: Color.black,
+});
+
+await app.start(LightingScene);
+// #endregion guide:basic-lightmap

examples/guides/loading-and-resources/basic-loading.ts

@@ -0,0 +1,44 @@
+// #region guide:required-scene
+import { type RenderingContext, Scene, Sprite, type Texture } from '@codexo/exojs';
+
+export class HeroScene extends Scene {
+  private texture!: Texture;
+
+  override async load(): Promise<void> {
+    this.texture = await this.loader.load('image/hero.png');
+  }
+
+  override init(): void {
+    const hero = new Sprite(this.texture);
+
+    hero.setAnchor(0.5).setPosition(this.app.width / 2, this.app.height / 2);
+    this.root.addChild(hero);
+  }
+
+  override draw(context: RenderingContext): void {
+    context.render(this.root);
+  }
+}
+// #endregion guide:required-scene
+
+// #region guide:scope-ownership
+import type { LoaderScope } from '@codexo/exojs';
+
+export const demonstrateClaims = async (parent: LoaderScope): Promise<void> => {
+  const level = parent.createScope({ name: 'level' });
+  const hud = parent.createScope({ name: 'hud' });
+
+  try {
+    const texture = level.get('image/hero.png');
+
+    hud.get('image/hero.png');
+    await texture.loaded;
+    level.destroy();
+
+    console.log(texture.ready); // true: the HUD still holds a claim
+  } finally {
+    level.destroy(); // repeated destruction is safe
+    hud.destroy();
+  }
+};
+// #endregion guide:scope-ownership

examples/guides/loading-and-resources/catalogs.ts

@@ -0,0 +1,30 @@
+// #region guide:catalog-definition
+import { Asset, Assets } from '@codexo/exojs';
+
+interface Settings {
+  startLevel: string;
+}
+
+export const SharedAssets = Assets.from({
+  logo: 'image/logo.png',
+  settings: Asset.type<Settings>('json', 'data/settings.json'),
+});
+// #endregion guide:catalog-definition
+
+// #region guide:catalog-result
+import type { LoaderScope } from '@codexo/exojs';
+
+export const readStartLevel = async (scope: LoaderScope): Promise<string> => {
+  const loaded = await scope.load(SharedAssets);
+
+  console.log(SharedAssets.settings.value.startLevel);
+  return loaded.settings.startLevel;
+};
+// #endregion guide:catalog-result
+
+// #region guide:catalog-composition
+const LevelLocal = Assets.from({ ground: 'image/day.png' });
+
+export const DayAssets = Assets.compose(SharedAssets, LevelLocal);
+export const NightAssets = Assets.extend(DayAssets, { ground: 'image/night.png' });
+// #endregion guide:catalog-composition

examples/guides/particles/basic-emitter.ts

@@ -0,0 +1,43 @@
+// #region guide:basic-emitter
+import { Application, Color, type RenderingContext, Scene } from '@codexo/exojs';
+import { ApplyForce, ConeDirection, Constant, Curve, particlesExtension, ParticleSystem, RateSpawn, ScaleOverLifetime } from '@codexo/exojs-particles';
+
+class FountainScene extends Scene {
+  private particles!: ParticleSystem;
+
+  override init(): void {
+    this.particles = new ParticleSystem({ capacity: 512 });
+    this.particles.setPosition(this.app.width / 2, this.app.height - 60);
+    this.particles.addSpawnModule(
+      new RateSpawn({
+        rate: new Constant(80),
+        lifetime: new Constant(2),
+        velocity: new ConeDirection(-Math.PI / 2, Math.PI / 6, 120, 220),
+      }),
+    );
+    this.particles.addUpdateModule(new ApplyForce(0, 180));
+    this.particles.addUpdateModule(
+      new ScaleOverLifetime(
+        new Curve([
+          { t: 0, v: 6 },
+          { t: 1, v: 0 },
+        ]),
+      ),
+    );
+    this.systems.add(this.particles);
+  }
+
+  override draw(context: RenderingContext): void {
+    context.render(this.particles);
+  }
+}
+
+const app = new Application({
+  scenes: { FountainScene },
+  extensions: [particlesExtension],
+  canvas: { width: 800, height: 600, mount: 'body' },
+  clearColor: Color.black,
+});
+
+await app.start(FountainScene);
+// #endregion guide:basic-emitter

examples/guides/physics-basics/falling-box.ts

@@ -0,0 +1,43 @@
+// #region guide:falling-box
+import { Application, Color, Graphics, type RenderingContext, Scene, SystemOrder } from '@codexo/exojs';
+import { BoxShape, PhysicsWorld } from '@codexo/exojs-physics';
+
+class FallingBoxScene extends Scene {
+  override init(): void {
+    const world = new PhysicsWorld({ gravity: { x: 0, y: 980 } });
+    const floor = new Graphics();
+    const box = new Graphics();
+
+    this.systems.add(world, { order: SystemOrder.Physics });
+    floor.fillColor = new Color(90, 110, 140);
+    floor.drawRectangle(-350, -16, 700, 32);
+    box.fillColor = Color.white;
+    box.drawRectangle(-20, -20, 40, 40);
+
+    world.attach(floor, {
+      type: 'static',
+      position: { x: 400, y: 560 },
+      shape: new BoxShape(700, 32),
+    });
+    world.attach(box, {
+      type: 'dynamic',
+      position: { x: 400, y: 100 },
+      shape: new BoxShape(40, 40),
+      restitution: 0.2,
+    });
+    this.root.addChild(floor, box);
+  }
+
+  override draw(context: RenderingContext): void {
+    context.render(this.root);
+  }
+}
+
+const app = new Application({
+  scenes: { FallingBoxScene },
+  canvas: { width: 800, height: 600, mount: 'body' },
+  clearColor: new Color(20, 24, 32),
+});
+
+await app.start(FallingBoxScene);
+// #endregion guide:falling-box

examples/guides/ui/basic-hud.ts

@@ -0,0 +1,27 @@
+// #region guide:basic-hud
+import { Application, Button, Color, Label, ProgressBar, Scene } from '@codexo/exojs';
+
+class HudScene extends Scene {
+  override init(): void {
+    const score = new Label('Score: 0', { fontSize: 24 });
+    const health = new ProgressBar({ width: 220, height: 16, value: 1 });
+    const damage = new Button({ label: 'Take damage', width: 180, height: 44 });
+
+    score.anchorIn(this.ui, 'top-left', 20, 20);
+    health.anchorIn(this.ui, 'top-left', 20, 56);
+    damage.anchorIn(this.ui, 'bottom-right', -20, -20);
+    damage.onClick.add(() => {
+      health.value = Math.max(0, health.value - 0.1);
+    });
+    this.ui.addChild(score, health, damage);
+  }
+}
+
+const app = new Application({
+  scenes: { HudScene },
+  canvas: { width: 800, height: 600, mount: 'body' },
+  clearColor: new Color(20, 24, 32),
+});
+
+await app.start(HudScene);
+// #endregion guide:basic-hud

packages/create-exo-app/README.md

@@ -1,53 +1,43 @@
 # create-exo-app
 
-Official starter for [ExoJS](https://github.com/Exoridus/ExoJS).
+Create an ExoJS application with Vite, TypeScript, and a working scene. Use `minimal` to learn the runtime before adding optional systems.
 
-## Usage
-
-```bash
-npm create exo-app@latest my-game
-```
-
-Or pick a template:
-
-```bash
+```sh
 npm create exo-app@latest my-game -- --template minimal
-npm create exo-app@latest my-game -- --template game-starter
-npm create exo-app@latest my-game -- --template platformer
-npm create exo-app@latest my-game -- --template top-down
-npm create exo-app@latest my-game -- --template ui-app
-npm create exo-app@latest my-game -- --template audio-reactive
-```
-
-Then:
-
-```bash
 cd my-game
 npm install
 npm run dev
 ```
 
+Omit `--template` to choose interactively. The generated project belongs to you: edit its source, commit its lockfile, and keep compatible ExoJS package versions pinned.
+
 ## Templates
 
-| Template         | Description                                                                            |
-| ---------------- | -------------------------------------------------------------------------------------- |
-| `minimal`        | Smallest TypeScript ExoJS app — one `Scene`, one rotating box                          |
-| `game-starter`   | Keyboard-controlled player, `GameScene` + `GameOverScene`, score HUD                   |
-| `platformer`     | Side-scroller on `@codexo/exojs-physics`: coyote time, jump buffer, camera follow      |
-| `top-down`       | Tilemap + physics + click-to-move pathfinding, procedurally built or loaded from Tiled |
-| `ui-app`         | Settings screen built from the core UI widgets                                         |
-| `audio-reactive` | `AudioAnalyser`-driven frequency bar visualiser; click-to-start gesture                |
+| Template         | Starting point                                                                 |
+| ---------------- | ------------------------------------------------------------------------------ |
+| `minimal`        | One visible animated object in one scene.                                      |
+| `game-starter`   | Keyboard-controlled gameplay and a game-over scene.                            |
+| `platformer`     | Side-scrolling physics, camera follow, and jump handling.                      |
+| `top-down`       | Tilemaps, collision, and click-to-move pathfinding; procedural or Tiled input. |
+| `ui-app`         | A settings interface built from Core UI widgets.                               |
+| `audio-reactive` | Shapes driven by live audio analysis.                                          |
 
-## CLI options
+Availability follows the scaffolder version you run. The repository's `next` branch can contain a template that is not yet in an older npm release. A specialized template includes more systems; it is not a prerequisite for using the engine.
 
-```
-create-exo-app <project-name> [--template <name>] [--force]
+## Locate the application code
 
-  --template  minimal | game-starter | platformer | top-down | ui-app | audio-reactive  (default: minimal)
-  --force     overwrite an existing non-empty directory
+`src/main.ts` creates the application, registers scene classes, mounts the canvas, and awaits startup. Scene behavior lives in `src/scenes/`. Files under `public/assets/` are served unchanged; `public/` is not part of their request URL.
+
+```sh
+npm run build
+npm run preview
 ```
 
-When run interactively (TTY) without `--template`, the CLI prompts for a template choice. In non-TTY / CI environments it defaults to `minimal` automatically.
+The build writes the static application to `dist/`. Preview checks that output locally; verify the actual hosted output as well, especially loader base paths and optional browser capabilities.
+
+## Documentation
+
+[Setup and project layout](https://exoridus.github.io/ExoJS/en/guide/getting-started/setup/) · [Your first scene](https://exoridus.github.io/ExoJS/en/guide/getting-started/your-first-scene/) · [Build and deploy](https://exoridus.github.io/ExoJS/en/guide/shipping/deployment/)
 
 ## License