Organize your game project

Keep the route thin, the game state local, and every ECS concern easy to find as your game grows.

Start with a game module

Squander does not require a generated project layout. For a SvelteKit game, this structure gives the runtime a clear home while keeping browser routes focused on composition:

src/
├── lib/
│   └── game/
│       ├── components/
│       │   ├── index.ts
│       │   └── ...
│       ├── scenes/
│       │   ├── main-menu.ts
│       │   └── play.ts
│       ├── systems/
│       │   ├── movement.ts
│       │   └── combat.ts
│       ├── ui/
│       │   ├── Hud.svelte
│       │   └── PauseMenu.svelte
│       └── game.ts
└── routes/
    └── +page.svelte

Add folders only when the game needs them. The important boundary is src/lib/game: it contains game-owned state and composition, while src/routes delivers that game through SvelteKit.

Keep the route at the edge

A route should connect SvelteKit to the game and stay out of gameplay. Import the Game component from squander/svelte and the game entrypoint from your own module:

svelte
<script lang="ts">
  import { Game } from "squander/svelte";
  import { start_game } from "$lib/game/game";
</script>

<Game class="game-canvas" onReady={start_game} />

<style>
  :global(.game-canvas) {
    width: min(100%, 800px);
    aspect-ratio: 16 / 9;
  }
</style>

Make game.ts the composition root

Use game.ts to create the world for one game instance, mount the starting scene, and decide which systems run in which lifecycle phase. It should assemble the game, not contain every mechanic.

typescript
import { create_world } from "squander/ecs";
import type { GameReadyContext } from "squander/svelte";
import { game_schema } from "./components";
import { movement_system } from "./systems/movement";

export const start_game = async ({ scenes }: GameReadyContext): Promise<void> => {
  const world = create_world(game_schema);

  await scenes.mount(({ renderer }) => ({
    name: "play",
    update: ({ delta_seconds }) => {
      movement_system(world, delta_seconds);
    },
    draw: (frame) => {
      frame.draw_commands([
        { kind: "rectangle", draw: { rectangle: { x: 0, y: 0, width: 800, height: 450 }, color: { red: 0.05, green: 0.08, blue: 0.15, alpha: 1 } } },
      ]);
    },
  }));
};

Let each folder own one kind of decision

components/
Define component tokens, the local schema, and the data shape shared by systems.
systems/
Write ordinary functions that query and update a world. They do not register themselves with an ECS scheduler.
scenes/
Own lifecycle boundaries, assets, input, and which systems run together for a mode of play.
ui/
Keep HUDs, menus, and overlays in Svelte. UI reads the state you intentionally publish; it does not become the gameplay source of truth.
game.ts
Assemble the world and scenes, define game-level events, and expose the entrypoint that the route calls.

Define the ECS schema locally

Squander's ECS uses component tokens that belong to a local schema. Keep those tokens together so systems share one typed vocabulary without global registration or declaration merging:

typescript
import { define_component, define_components, type World } from "squander/ecs";

export type Position = { x: number; y: number };

export const position = define_component<Position>({ name: "position" });
export const game_schema = define_components({ position });
export type GameWorld = World<typeof game_schema>;

Keep systems small and caller-owned

A system is just a function with the dependencies it needs. The scene or game module owns ordering, so the same system can be reused in a different scene or composed with non-ECS game code:

typescript
import { position, type GameWorld } from "../components";

export const movement_system = (world: GameWorld, delta_seconds: number): void => {
  world.query().with(position).each(({ write }) => {
    write(position).x += 60 * delta_seconds;
  });
};

Why this scales

  • The route remains a small SvelteKit adapter instead of becoming a second game loop.
  • The game module owns composition without hiding the update and draw order.
  • Components describe data, systems describe transformations, and scenes describe lifecycle.
  • Svelte stays at the UI seam, while gameplay state remains in the game runtime.

Start with one game.ts, one scene, and a local schema. Split a folder when a game concern has its own vocabulary or lifecycle—not because the tree looks more complete.