# Guides overview

The Guides section covers how to build with Flare — animation, interactive experiences, and games: project setup, scenes and the ECS world, rendering sprites through Skia, input, audio, and shipping to iOS, Android, and the web. Start with [Getting started](/getting-started) to scaffold a runnable app, then return here as each topic-specific guide lands. The **Showcases** below rebuild the five hero animations on this site, step by step.

## What building with Flare looks like

A Flare app mounts a single root view and starts a fixed-timestep loop; from there you spawn entities, attach components, and register systems that run each frame. You scaffold a project with `create-flare-app`, write your game logic against the ECS world and scene manager, and let the renderer batch sprites into Skia draw calls.

```bash
npm create flare-app@latest my-game
```

The smallest app mounts a `GameView` and starts the loop — everything else (entities, input, systems) is added from the ready handler:

```tsx

function handleReady(ctx: GameContextValue): void {
  ctx.loop.start();
}

export function App(): React.ReactElement {
  return (
    <View style={styles.root}>
      <GameView onReady={handleReady} style={styles.game} />
    </View>
  );
}

const styles = StyleSheet.create({
  root: { flex: 1, backgroundColor: "#000" },
  game: { flex: 1 },
});
```

## The engine at a glance

Flare is a TypeScript-first 2D engine for React Native and the web: one codebase — animation, gamification, interactive UI, and games — renders to iOS, Android, and the web. It ships as **{catalog.packageCount} packages** across nine bands — Foundation, Core, Systems, Persistence (2.5), Features, UI & post-FX (3.5), Integration, Tooling (5), and Platform integrations (6) — where lower layers never import from higher ones. Rendering runs on `@shopify/react-native-skia` natively and CanvasKit WASM on the web; you typically install the `@flare-engine/engine` umbrella alongside `@flare-engine/react` for the component surface.

For the live list of every package see the [package catalog](/reference/packages); for the layer map and dependency rules, see [Concepts: Architecture](/concepts/architecture) and the canonical engine design docs.

<CardGrid>
  <LinkCard
    title="Getting started"
    description="Scaffold a runnable Flare app and render your first frame."
    href="/getting-started"
  />
  <LinkCard
    title="Architecture"
    description="The layer model, package surface, and rendering backends."
    href="/concepts/architecture"
  />
  <LinkCard
    title="Engine design docs"
    description="Canonical architecture.md on GitHub (engine repo)."
    href="https://github.com/grzott/flare-engine/blob/main/docs/design/architecture.md"
  />
  <LinkCard
    title="API specs"
    description="Canonical api-specs.md on GitHub (engine repo)."
    href="https://github.com/grzott/flare-engine/blob/main/docs/design/api-specs.md"
  />
</CardGrid>

<Aside type="caution" title="Pre-launch">
The engine repo is private until the OSS launch (target October 2026); the `@flare-engine`
packages are published restricted until then. The two GitHub links above are the canonical
targets once the repo is public.
</Aside>

## Showcases

The hero animation on this site is a switchable showcase — five self-contained Skia/CanvasKit
pieces built on a common seam: the engine's loop and post-FX surface, with most also leaning on
its math and particle pool (the Logo piece is the exception — loop + post-FX only). These guides
rebuild them from scratch and are explicit about the seam: what the engine gives you versus what
is your own application code. Read **Foundations** first; the five then build on it in rising
complexity.

<CardGrid>
  <LinkCard
    title="Foundations"
    description="The shared spine: the animation contract, the post-FX surface, the palette, and the engine-liftable pure-module discipline."
    href="/guides/foundations"
  />
  <LinkCard
    title="Physarum network"
    description="A slime-mold transport network — data-oriented agents over a pheromone field, rendered as a single image blit."
    href="/guides/physarum"
  />
  <LinkCard
    title="Nuclear reactor"
    description="An emergent chain reaction on the ECS — neutron agents, real reactor kinetics, coroutine choreography, and rod tweens."
    href="/guides/reactions"
  />
  <LinkCard
    title="Spacetime lattice"
    description="A symplectic N-body merger ballet — a warp lattice, gravitational lensing, and the LIGO chirp, for free."
    href="/guides/spacetime"
  />
  <LinkCard
    title="Procedural map"
    description="A deterministic, seeded fantasy cartography animation — edge-mask autotiled roads, logical terrain clusters, and an adventure line; the repo's first raster pipeline."
    href="/guides/map"
  />
  <LinkCard
    title="Logo reveal"
    description="The brand wordmark on a seamless loop — a pure unit-tested timeline plus a hand-written SkSL specular shine; the smallest engine seam."
    href="/guides/logo"
  />
</CardGrid>

## Planned guides

These topics are planned for the Guides section; each will land as a focused walkthrough.

- **Project setup** — scaffold an app with `create-flare-app`, pick a template, and run it on a device or the web.
- **Scenes & the game loop** — register scenes with the `SceneManager` and drive logic from the fixed-timestep loop.
- **The ECS world** — spawn entities, define components, and add systems with `@flare-engine/ecs`.
- **Rendering sprites** — draw with the built-in `Sprite` component and flush the `SpriteBatch` once per frame.
- **Input & virtual controls** — wire touch input and the overlay `VirtualJoystick` / `VirtualButton` components.
- **Audio** — load and play sound through the engine's audio manager.
- **Assets & atlases** — pack sprite folders into atlases with the `flare pack-atlas` CLI command.
- **Tilemaps** — convert Tiled `.tmj` maps with `flare tiled-to-flare` and render them at runtime.
- **Shipping** — build and release the same project to iOS, Android, and the web.

The engine's design documents are the single source of truth for the API surface — guides summarize and link rather than duplicate them. Browse the canonical set in the [engine repo](https://github.com/grzott/flare-engine/blob/main/docs/design/architecture.md) (architecture, api-specs, dependencies, ecosystem, native-acceleration, lighting-2-5d). The public npm release is targeted for October 2026.