@waica/archetype-topdown 0.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayrton Marini and Waica contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/ATTRIBUTION.md

@@ -0,0 +1,28 @@
+# Art attribution
+
+All sprites in this directory are composed from Creative Commons Zero (CC0)
+pixel art by Kenney (www.kenney.nl). CC0 requires no attribution — this file
+credits the source anyway and records exactly how each sheet was assembled,
+so the composition is reproducible.
+
+Sources (both CC0, downloaded 2026-08-10):
+
+- **RPG Urban Pack 1.0** — https://kenney.nl/assets/rpg-urban-pack
+  (`Tilemap/tilemap_packed.png`, a 27×18 grid of 16×16 tiles)
+- **Tiny Dungeon 1.0** — https://kenney.nl/assets/tiny-dungeon
+  (`Tilemap/tilemap_packed.png`, a 12×11 grid of 16×16 tiles)
+
+Tile coordinates below are `(column, row)`, zero-based, into each pack's
+`tilemap_packed.png`.
+
+| File | Size | Source | Composition |
+|---|---|---|---|
+| `waica-hero.png` | 50×50 | RPG Urban | Character 1 (rows 0–2). 3×3 grid of 16×16 cells with 1px transparent gutters between them (frame-edge sampling never reaches a neighbour): rows = facing s/n/e (source columns 24/25/26), columns = idle / walk A / walk B (source rows base+0/1/2). West is mirrored from east at runtime. |
+| `waica-npc.png` | 50×50 | RPG Urban | Character 4, the farmer (rows 9–11). Same 3×3 gutter layout as the hero. |
+| `waica-blob.png` | 16×16 | Tiny Dungeon | (0, 9) — the green blob. |
+| `waica-potion.png` | 16×16 | Tiny Dungeon | (7, 9) — the red potion. |
+| `waica-grass.png` | 16×16 | RPG Urban | (1, 1) — plain grass. |
+| `waica-water.png` | 16×16 | RPG Urban | (9, 7) — pond interior. |
+| `waica-path.png` | 16×16 | Tiny Dungeon | (1, 4) — speckled sand. |
+| `waica-fence.png` | 16×16 | Tiny Dungeon | (5, 6) — fence run. |
+| `waica-tree.png` | 16×32 | RPG Urban | (16, 8)–(16, 9) — tall green tree, two tiles stacked. |

package/dist/animation.d.ts

@@ -0,0 +1,7 @@
+import type { DirectionalAnimation } from '@waica/engine';
+/**
+ * The archetype's directional animation contract: four facings with west
+ * mirrored from east art (the stock sheets only draw s/n/e), clips named
+ * `<state>-<dir>`, and walk falling back to idle when a sheet lacks it.
+ */
+export declare const TOPDOWN_ANIMATION: DirectionalAnimation;

package/dist/animation.js

@@ -0,0 +1,10 @@
+/**
+ * The archetype's directional animation contract: four facings with west
+ * mirrored from east art (the stock sheets only draw s/n/e), clips named
+ * `<state>-<dir>`, and walk falling back to idle when a sheet lacks it.
+ */
+export const TOPDOWN_ANIMATION = {
+    directions: ['n', 's', 'e', 'w'],
+    fallbacks: { w: { dir: 'e', flip: true } },
+    contract: { required: ['idle'], fallbacks: { walk: 'idle' } },
+};

package/dist/art.d.ts

@@ -0,0 +1,10 @@
+import type { ArchetypeArt } from '@waica/engine';
+/**
+ * The archetype's stock art, as pure data (no asset imports: node tooling
+ * like scripts/sync-scene.mjs imports this module directly).
+ *
+ * Demo projects materialize each sheet as a real file at `src/art/<file>`
+ * and reference that path; `uri` is the registry key that in-package
+ * prefab defaults use.
+ */
+export declare const TOPDOWN_ART: ArchetypeArt[];

package/dist/art.js

@@ -0,0 +1,19 @@
+/**
+ * The archetype's stock art, as pure data (no asset imports: node tooling
+ * like scripts/sync-scene.mjs imports this module directly).
+ *
+ * Demo projects materialize each sheet as a real file at `src/art/<file>`
+ * and reference that path; `uri` is the registry key that in-package
+ * prefab defaults use.
+ */
+export const TOPDOWN_ART = [
+    { file: 'waica-hero.png', uri: 'waica:hero' },
+    { file: 'waica-npc.png', uri: 'waica:npc' },
+    { file: 'waica-blob.png', uri: 'waica:blob' },
+    { file: 'waica-potion.png', uri: 'waica:potion' },
+    { file: 'waica-grass.png', uri: 'waica:grass' },
+    { file: 'waica-path.png', uri: 'waica:path' },
+    { file: 'waica-water.png', uri: 'waica:water' },
+    { file: 'waica-fence.png', uri: 'waica:fence' },
+    { file: 'waica-tree.png', uri: 'waica:tree' },
+];

package/dist/bundle.d.ts

@@ -0,0 +1,3 @@
+import type { ArchetypeBundle } from '@waica/engine';
+/** Role and state-code baseline installed for a top-down project. */
+export declare const TOPDOWN_BUNDLE: ArchetypeBundle;

package/dist/bundle.js

@@ -0,0 +1,10 @@
+import { CHASER_ROLE, NPC_ROLE, PATROLLER_ROLE, TOPDOWN_PLAYER_ROLE, } from '@waica/behaviors';
+/** Role and state-code baseline installed for a top-down project. */
+export const TOPDOWN_BUNDLE = {
+    roles: {
+        player: TOPDOWN_PLAYER_ROLE,
+        patroller: PATROLLER_ROLE,
+        chaser: CHASER_ROLE,
+        npc: NPC_ROLE,
+    },
+};

package/dist/controls.d.ts

@@ -0,0 +1,5 @@
+import type { InputBindings } from '@waica/engine';
+/** Top-down actions: four directions plus interact, arrows and WASD. */
+export declare const TOPDOWN_BINDINGS: Readonly<InputBindings>;
+/** Friendly labels shown by the editor's controls panel. */
+export declare const TOPDOWN_ACTION_LABELS: Readonly<Record<string, string>>;

package/dist/controls.js

@@ -0,0 +1,16 @@
+/** Top-down actions: four directions plus interact, arrows and WASD. */
+export const TOPDOWN_BINDINGS = {
+    up: ['ArrowUp', 'KeyW'],
+    down: ['ArrowDown', 'KeyS'],
+    left: ['ArrowLeft', 'KeyA'],
+    right: ['ArrowRight', 'KeyD'],
+    interact: ['KeyE', 'Space'],
+};
+/** Friendly labels shown by the editor's controls panel. */
+export const TOPDOWN_ACTION_LABELS = {
+    up: 'Move up',
+    down: 'Move down',
+    left: 'Move left',
+    right: 'Move right',
+    interact: 'Interact',
+};

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+export { TOPDOWN_ANIMATION } from './animation.js';
+export { TOPDOWN_BUNDLE } from './bundle.js';
+export { TOPDOWN_ACTION_LABELS, TOPDOWN_BINDINGS } from './controls.js';
+export { TOPDOWN_SCENE, TOPDOWN_BLANK_SCENE, HERO_SPRITE } from './scene-default.js';
+export { TOPDOWN_PREFABS } from './prefabs.js';
+export { TOPDOWN_UI } from './ui.js';
+export { TOPDOWN_ART } from './art.js';
+export { TOPDOWN_REGISTRY, TOPDOWN_PALETTE, TOPDOWN_ART_URLS } from './registry.js';
+/** Browser-complete manifest exported by the package root. */
+export declare const ARCHETYPE: {
+    id: string;
+    label: string;
+    scene: import("@waica/engine").SceneJson;
+    blankScene: import("@waica/engine").SceneJson;
+    palette: import("@waica/engine").EntityTemplate[];
+    prefabs: Record<string, import("@waica/engine").PrefabJson>;
+    art: import("@waica/engine").ArchetypeArt[];
+    entityIcons: Readonly<Record<string, string>>;
+    bindings: Readonly<import("@waica/engine").InputBindings>;
+    actionLabels: Readonly<Record<string, string>>;
+    bundle: import("@waica/engine").ArchetypeBundle;
+    animation: import("@waica/engine").DirectionalAnimation<string>;
+    registry: import("@waica/engine").SceneRegistry;
+    artUrls: Record<string, string>;
+};

package/dist/index.js

@@ -0,0 +1,16 @@
+import { ARCHETYPE as DATA_ARCHETYPE } from './manifest.js';
+import { TOPDOWN_REGISTRY, TOPDOWN_ART_URLS } from './registry.js';
+export { TOPDOWN_ANIMATION } from './animation.js';
+export { TOPDOWN_BUNDLE } from './bundle.js';
+export { TOPDOWN_ACTION_LABELS, TOPDOWN_BINDINGS } from './controls.js';
+export { TOPDOWN_SCENE, TOPDOWN_BLANK_SCENE, HERO_SPRITE } from './scene-default.js';
+export { TOPDOWN_PREFABS } from './prefabs.js';
+export { TOPDOWN_UI } from './ui.js';
+export { TOPDOWN_ART } from './art.js';
+export { TOPDOWN_REGISTRY, TOPDOWN_PALETTE, TOPDOWN_ART_URLS } from './registry.js';
+/** Browser-complete manifest exported by the package root. */
+export const ARCHETYPE = {
+    ...DATA_ARCHETYPE,
+    registry: TOPDOWN_REGISTRY,
+    artUrls: TOPDOWN_ART_URLS,
+};

package/dist/manifest.d.ts

@@ -0,0 +1,16 @@
+/** Asset-import-free manifest for Node tooling. */
+export declare const ARCHETYPE: {
+    id: string;
+    label: string;
+    scene: import("@waica/engine").SceneJson;
+    blankScene: import("@waica/engine").SceneJson;
+    registry: import("@waica/engine").SceneRegistry;
+    palette: import("@waica/engine").EntityTemplate[];
+    prefabs: Record<string, import("@waica/engine").PrefabJson>;
+    art: import("@waica/engine").ArchetypeArt[];
+    entityIcons: Readonly<Record<string, string>>;
+    bindings: Readonly<import("@waica/engine").InputBindings>;
+    actionLabels: Readonly<Record<string, string>>;
+    bundle: import("@waica/engine").ArchetypeBundle;
+    animation: import("@waica/engine").DirectionalAnimation<string>;
+};

package/dist/manifest.js

@@ -0,0 +1,29 @@
+import { TOPDOWN_ANIMATION } from './animation.js';
+import { TOPDOWN_ART } from './art.js';
+import { TOPDOWN_BUNDLE } from './bundle.js';
+import { TOPDOWN_ACTION_LABELS, TOPDOWN_BINDINGS } from './controls.js';
+import { TOPDOWN_PREFABS } from './prefabs.js';
+import { TOPDOWN_PALETTE, TOPDOWN_REGISTRY_DATA } from './registry-data.js';
+import { TOPDOWN_BLANK_SCENE, TOPDOWN_SCENE } from './scene-default.js';
+const TOPDOWN_ENTITY_ICONS = {
+    TopDownMotor: '🧒',
+    Interactable: '💬',
+    Collectible: '🧪',
+    Hazard: '👾',
+};
+/** Asset-import-free manifest for Node tooling. */
+export const ARCHETYPE = {
+    id: 'topdown',
+    label: 'Top-down',
+    scene: TOPDOWN_SCENE,
+    blankScene: TOPDOWN_BLANK_SCENE,
+    registry: TOPDOWN_REGISTRY_DATA,
+    palette: TOPDOWN_PALETTE,
+    prefabs: TOPDOWN_PREFABS,
+    art: TOPDOWN_ART,
+    entityIcons: TOPDOWN_ENTITY_ICONS,
+    bindings: TOPDOWN_BINDINGS,
+    actionLabels: TOPDOWN_ACTION_LABELS,
+    bundle: TOPDOWN_BUNDLE,
+    animation: TOPDOWN_ANIMATION,
+};

package/dist/prefabs.d.ts

@@ -0,0 +1,11 @@
+import type { PrefabJson } from '@waica/engine';
+/**
+ * The archetype's reusable entity templates, keyed by ref ('tiles/tree').
+ * Scenes reference these and override per-entity props; the palette derives
+ * its pieces from this catalog.
+ *
+ * Ground tiles draw on negative layers so the y-sort pass never weaves
+ * them between characters: meadow (-2), then decor tiles (-1), then
+ * everything that occludes at 0.
+ */
+export declare const TOPDOWN_PREFABS: Record<string, PrefabJson>;

package/dist/prefabs.js

@@ -0,0 +1,178 @@
+import { NPC_STATE_GRAPH, TOPDOWN_PLAYER_STATE_GRAPH } from '@waica/behaviors';
+import { HERO_SPRITE } from './scene-default.js';
+/**
+ * The archetype's reusable entity templates, keyed by ref ('tiles/tree').
+ * Scenes reference these and override per-entity props; the palette derives
+ * its pieces from this catalog.
+ *
+ * Ground tiles draw on negative layers so the y-sort pass never weaves
+ * them between characters: meadow (-2), then decor tiles (-1), then
+ * everything that occludes at 0.
+ */
+export const TOPDOWN_PREFABS = {
+    'characters/player': {
+        waicaPrefab: 1,
+        type: 'character',
+        components: [
+            { type: 'AnimatedSprite', props: HERO_SPRITE },
+            { type: 'TopDownMotor' },
+            {
+                type: 'StateMachine',
+                props: {
+                    role: 'player',
+                    initial: TOPDOWN_PLAYER_STATE_GRAPH.initial,
+                    states: TOPDOWN_PLAYER_STATE_GRAPH.states,
+                },
+            },
+            { type: 'Hitbox', props: { width: 0.8, height: 0.8 } },
+            { type: 'Respawnable' },
+            { type: 'Health', props: { max: 3, invulnerability: 1 } },
+        ],
+    },
+    'characters/villager': {
+        waicaPrefab: 1,
+        type: 'character',
+        components: [
+            {
+                type: 'AnimatedSprite',
+                props: {
+                    texture: 'waica:npc',
+                    cols: 3,
+                    rows: 3,
+                    spacingX: 1,
+                    spacingY: 1,
+                    width: 1.2,
+                    height: 1.2,
+                    clips: {
+                        // The plain 'idle' is what a code-free NPC plays (it has no
+                        // facing provider); the directional clips are ready for the
+                        // day a project gives it a motor.
+                        idle: { frames: [0], fps: 2 },
+                        'idle-s': { frames: [0], fps: 2 },
+                        'idle-n': { frames: [3], fps: 2 },
+                        'idle-e': { frames: [6], fps: 2 },
+                        'walk-s': { frames: [1, 0, 2, 0], fps: 8 },
+                        'walk-n': { frames: [4, 3, 5, 3], fps: 8 },
+                        'walk-e': { frames: [7, 6, 8, 6], fps: 8 },
+                    },
+                    initialClip: 'idle',
+                },
+            },
+            {
+                type: 'StateMachine',
+                props: {
+                    role: 'npc',
+                    initial: NPC_STATE_GRAPH.initial,
+                    states: NPC_STATE_GRAPH.states,
+                },
+            },
+            { type: 'Interactable', props: { line: 'Hello, traveler!', radius: 1.5 } },
+            // Villagers block the way like any solid prop.
+            { type: 'Solid', props: { width: 0.8, height: 0.5 } },
+        ],
+    },
+    'characters/blob': {
+        waicaPrefab: 1,
+        type: 'character',
+        components: [
+            {
+                type: 'AnimatedSprite',
+                props: {
+                    texture: 'waica:blob',
+                    cols: 1,
+                    rows: 1,
+                    width: 1,
+                    height: 1,
+                    clips: { idle: { frames: [0], fps: 2 } },
+                    initialClip: 'idle',
+                },
+            },
+            { type: 'Patrol', props: { distance: 2, speed: 2 } },
+            {
+                type: 'StateMachine',
+                props: {
+                    role: 'patroller',
+                    initial: 'walk',
+                    states: { walk: { clip: 'idle' } },
+                },
+            },
+            { type: 'Hitbox', props: { width: 0.8, height: 0.7 } },
+            // No stomping without gravity: any contact hurts.
+            { type: 'Hazard', props: { stompable: false, contactDamage: 1 } },
+        ],
+    },
+    'objects/potion': {
+        waicaPrefab: 1,
+        type: 'object',
+        components: [
+            {
+                type: 'AnimatedSprite',
+                props: {
+                    texture: 'waica:potion',
+                    cols: 1,
+                    rows: 1,
+                    width: 0.7,
+                    height: 0.7,
+                    clips: { idle: { frames: [0], fps: 2 } },
+                    initialClip: 'idle',
+                },
+            },
+            { type: 'Hitbox', props: { width: 0.5, height: 0.5 } },
+            { type: 'Collectible', props: { value: 1 } },
+        ],
+    },
+    'tiles/meadow': {
+        waicaPrefab: 1,
+        type: 'tile',
+        components: [
+            // The ground plane: a flat field the size you stretch it to, in the
+            // grass sheet's dominant green so textured tiles blend on top.
+            { type: 'Sprite', props: { width: 1, height: 1, color: 0x38cbab, layer: -2 } },
+        ],
+    },
+    'tiles/grass': {
+        waicaPrefab: 1,
+        type: 'tile',
+        components: [
+            { type: 'Sprite', props: { texture: 'waica:grass', width: 1, height: 1, layer: -1 } },
+        ],
+    },
+    'tiles/path': {
+        waicaPrefab: 1,
+        type: 'tile',
+        components: [
+            { type: 'Sprite', props: { texture: 'waica:path', width: 1, height: 1, layer: -1 } },
+        ],
+    },
+    'tiles/water': {
+        waicaPrefab: 1,
+        type: 'tile',
+        components: [
+            { type: 'Sprite', props: { texture: 'waica:water', width: 1, height: 1, layer: -1 } },
+            { type: 'Solid', props: { width: 1, height: 1 } },
+        ],
+    },
+    'tiles/fence': {
+        waicaPrefab: 1,
+        type: 'tile',
+        components: [
+            { type: 'Sprite', props: { texture: 'waica:fence', width: 1, height: 1 } },
+            // Shorter than the art so the player can overlap the top rail a bit,
+            // the way top-down fences read.
+            { type: 'Solid', props: { width: 1, height: 0.6 } },
+        ],
+    },
+    'tiles/tree': {
+        waicaPrefab: 1,
+        type: 'tile',
+        components: [
+            // Anchored at the trunk: the 1×2 canopy is drawn upward so the
+            // entity Y — the y-sort key — is where the tree meets the ground.
+            {
+                type: 'Sprite',
+                props: { texture: 'waica:tree', width: 1, height: 2, offsetY: 0.5 },
+            },
+            { type: 'Solid', props: { width: 0.8, height: 0.6 } },
+        ],
+    },
+};

package/dist/registry-data.d.ts

@@ -0,0 +1,9 @@
+import { type EntityTemplate, type SceneRegistry } from '@waica/engine';
+/**
+ * Asset-import-free registry. Browser URL resolution is layered on
+ * separately. No DynamicBody or OutOfBounds: gravity physics and kill
+ * heights have no meaning seen from above.
+ */
+export declare const TOPDOWN_REGISTRY_DATA: SceneRegistry;
+/** The editor palette: pieces you can drag into the viewport, one per prefab. */
+export declare const TOPDOWN_PALETTE: EntityTemplate[];

package/dist/registry-data.js

@@ -0,0 +1,54 @@
+import { AnimatedSprite, Hitbox, Solid, Sprite, StateMachine, } from '@waica/engine';
+import { Chaser, Collectible, Hazard, Health, Interactable, Lifetime, Patrol, Respawnable, TopDownMotor, } from '@waica/behaviors';
+import { TOPDOWN_ART } from './art.js';
+import { TOPDOWN_PREFABS } from './prefabs.js';
+import { TOPDOWN_UI } from './ui.js';
+const PACKAGE_ASSETS = Object.fromEntries(TOPDOWN_ART.map((art) => [art.uri, `assets/${art.file}`]));
+/**
+ * Asset-import-free registry. Browser URL resolution is layered on
+ * separately. No DynamicBody or OutOfBounds: gravity physics and kill
+ * heights have no meaning seen from above.
+ */
+export const TOPDOWN_REGISTRY_DATA = {
+    components: {
+        Sprite,
+        AnimatedSprite,
+        Solid,
+        Hitbox,
+        StateMachine,
+        TopDownMotor,
+        Interactable,
+        Collectible,
+        Patrol,
+        Chaser,
+        Hazard,
+        Health,
+        Respawnable,
+        Lifetime,
+    },
+    resolveAsset: (uri) => PACKAGE_ASSETS[uri] ?? uri,
+    prefabs: TOPDOWN_PREFABS,
+    ui: TOPDOWN_UI,
+};
+const PALETTE_ICONS = {
+    player: '🧒',
+    villager: '🧑‍🌾',
+    blob: '👾',
+    potion: '🧪',
+    meadow: '▩',
+    grass: '🌿',
+    path: '🟫',
+    water: '🌊',
+    fence: '🚧',
+    tree: '🌳',
+};
+/** The editor palette: pieces you can drag into the viewport, one per prefab. */
+export const TOPDOWN_PALETTE = Object.entries(TOPDOWN_PREFABS).map(([key, prefab]) => {
+    const base = key.slice(key.indexOf('/') + 1);
+    return {
+        label: base,
+        icon: PALETTE_ICONS[base] ?? '▣',
+        category: prefab.type,
+        make: () => ({ name: base.charAt(0).toUpperCase() + base.slice(1), prefab: key }),
+    };
+});

package/dist/registry.d.ts

@@ -0,0 +1,6 @@
+import type { SceneRegistry } from '@waica/engine';
+export { TOPDOWN_PALETTE } from './registry-data.js';
+/** Browser URL per stock-art file; Node resolves these to packed file URLs. */
+export declare const TOPDOWN_ART_URLS: Record<string, string>;
+/** Browser registry with bundled asset resolution layered over the shared registry. */
+export declare const TOPDOWN_REGISTRY: SceneRegistry;

package/dist/registry.js

@@ -0,0 +1,21 @@
+import { TOPDOWN_ART } from './art.js';
+import { TOPDOWN_REGISTRY_DATA } from './registry-data.js';
+export { TOPDOWN_PALETTE } from './registry-data.js';
+/** Browser URL per stock-art file; Node resolves these to packed file URLs. */
+export const TOPDOWN_ART_URLS = {
+    'waica-hero.png': new URL('../assets/waica-hero.png', import.meta.url).href,
+    'waica-npc.png': new URL('../assets/waica-npc.png', import.meta.url).href,
+    'waica-blob.png': new URL('../assets/waica-blob.png', import.meta.url).href,
+    'waica-potion.png': new URL('../assets/waica-potion.png', import.meta.url).href,
+    'waica-grass.png': new URL('../assets/waica-grass.png', import.meta.url).href,
+    'waica-path.png': new URL('../assets/waica-path.png', import.meta.url).href,
+    'waica-water.png': new URL('../assets/waica-water.png', import.meta.url).href,
+    'waica-fence.png': new URL('../assets/waica-fence.png', import.meta.url).href,
+    'waica-tree.png': new URL('../assets/waica-tree.png', import.meta.url).href,
+};
+const BUILTIN_ASSETS = Object.fromEntries(TOPDOWN_ART.map((art) => [art.uri, TOPDOWN_ART_URLS[art.file] ?? art.uri]));
+/** Browser registry with bundled asset resolution layered over the shared registry. */
+export const TOPDOWN_REGISTRY = {
+    ...TOPDOWN_REGISTRY_DATA,
+    resolveAsset: (uri) => BUILTIN_ASSETS[uri] ?? uri,
+};

package/dist/scene-default.d.ts

@@ -0,0 +1,57 @@
+import type { SceneJson } from '@waica/engine';
+/**
+ * Clips matching the top-down animation contract, applied to the hero
+ * sheet: 3×3 grid, one row per facing (s/n/e), columns idle/walk-A/walk-B.
+ * West clips come from mirroring east at runtime (the contract's fallback).
+ * Cells sit 1px apart — transparent gutters keep frame-edge sampling
+ * (MSAA extrapolation, linear filtering) from bleeding a neighbour in.
+ */
+export declare const HERO_SPRITE: {
+    texture: string;
+    cols: number;
+    rows: number;
+    spacingX: number;
+    spacingY: number;
+    width: number;
+    height: number;
+    clips: {
+        'idle-s': {
+            frames: number[];
+            fps: number;
+        };
+        'idle-n': {
+            frames: number[];
+            fps: number;
+        };
+        'idle-e': {
+            frames: number[];
+            fps: number;
+        };
+        'walk-s': {
+            frames: number[];
+            fps: number;
+        };
+        'walk-n': {
+            frames: number[];
+            fps: number;
+        };
+        'walk-e': {
+            frames: number[];
+            fps: number;
+        };
+    };
+    initialClip: string;
+};
+/**
+ * The top-down archetype's starting scene: a village clearing that
+ * exercises everything the genre adds — y-sorted occlusion (walk behind
+ * and in front of the trees), the two-axis camera (vertical lookahead),
+ * an NPC to interact with, a patrolling enemy and potions to collect.
+ */
+export declare const TOPDOWN_SCENE: SceneJson;
+/**
+ * The blank-start variant: same framing and y-sorted rendering, zero
+ * entities. No `follow` because there is no Player yet — the editor's
+ * palette places the first one.
+ */
+export declare const TOPDOWN_BLANK_SCENE: SceneJson;

package/dist/scene-default.js

@@ -0,0 +1,110 @@
+/**
+ * Clips matching the top-down animation contract, applied to the hero
+ * sheet: 3×3 grid, one row per facing (s/n/e), columns idle/walk-A/walk-B.
+ * West clips come from mirroring east at runtime (the contract's fallback).
+ * Cells sit 1px apart — transparent gutters keep frame-edge sampling
+ * (MSAA extrapolation, linear filtering) from bleeding a neighbour in.
+ */
+export const HERO_SPRITE = {
+    texture: 'waica:hero',
+    cols: 3,
+    rows: 3,
+    spacingX: 1,
+    spacingY: 1,
+    width: 1.2,
+    height: 1.2,
+    clips: {
+        'idle-s': { frames: [0], fps: 2 },
+        'idle-n': { frames: [3], fps: 2 },
+        'idle-e': { frames: [6], fps: 2 },
+        'walk-s': { frames: [1, 0, 2, 0], fps: 8 },
+        'walk-n': { frames: [4, 3, 5, 3], fps: 8 },
+        'walk-e': { frames: [7, 6, 8, 6], fps: 8 },
+    },
+    initialClip: 'idle-s',
+};
+/**
+ * The top-down archetype's starting scene: a village clearing that
+ * exercises everything the genre adds — y-sorted occlusion (walk behind
+ * and in front of the trees), the two-axis camera (vertical lookahead),
+ * an NPC to interact with, a patrolling enemy and potions to collect.
+ */
+export const TOPDOWN_SCENE = {
+    waicaScene: 3,
+    render: { sort: 'y' },
+    camera: {
+        position: [0, 0],
+        zoom: 12,
+        follow: 'Player',
+        lookaheadY: 1,
+        // Clamped to the meadow: 22×14 world units centered on the origin.
+        limits: { minX: -11, maxX: 11, minY: -7, maxY: 7 },
+    },
+    entities: [
+        { name: 'Player', prefab: 'characters/player', position: [0, -2] },
+        {
+            name: 'Meadow',
+            prefab: 'tiles/meadow',
+            position: [0, 0],
+            overrides: { Sprite: { width: 22, height: 14 } },
+        },
+        { name: 'Path-1', prefab: 'tiles/path', position: [-2, 0] },
+        { name: 'Path-2', prefab: 'tiles/path', position: [-1, 0] },
+        { name: 'Path-3', prefab: 'tiles/path', position: [0, 0] },
+        { name: 'Path-4', prefab: 'tiles/path', position: [1, 0] },
+        { name: 'Path-5', prefab: 'tiles/path', position: [2, 0] },
+        { name: 'Path-6', prefab: 'tiles/path', position: [0, -1] },
+        { name: 'Path-7', prefab: 'tiles/path', position: [0, 1] },
+        { name: 'Grass-1', prefab: 'tiles/grass', position: [-4, 1] },
+        { name: 'Grass-2', prefab: 'tiles/grass', position: [1, 2] },
+        { name: 'Grass-3', prefab: 'tiles/grass', position: [5, -2] },
+        { name: 'Grass-4', prefab: 'tiles/grass', position: [-8, 3] },
+        { name: 'Grass-5', prefab: 'tiles/grass', position: [8, -3] },
+        { name: 'Grass-6', prefab: 'tiles/grass', position: [-1, -4] },
+        { name: 'Water-1', prefab: 'tiles/water', position: [-7, -2] },
+        { name: 'Water-2', prefab: 'tiles/water', position: [-6, -2] },
+        { name: 'Water-3', prefab: 'tiles/water', position: [-5, -2] },
+        { name: 'Water-4', prefab: 'tiles/water', position: [-7, -3] },
+        { name: 'Water-5', prefab: 'tiles/water', position: [-6, -3] },
+        { name: 'Water-6', prefab: 'tiles/water', position: [-5, -3] },
+        // Trees sit in open ground so walking above/below them flips the
+        // draw order — the y-sort showcase.
+        { name: 'Tree-1', prefab: 'tiles/tree', position: [-6, 3] },
+        { name: 'Tree-2', prefab: 'tiles/tree', position: [-2, 3.5] },
+        { name: 'Tree-3', prefab: 'tiles/tree', position: [2, 4] },
+        { name: 'Tree-4', prefab: 'tiles/tree', position: [6, 3] },
+        { name: 'Tree-5', prefab: 'tiles/tree', position: [4, -1] },
+        { name: 'Tree-6', prefab: 'tiles/tree', position: [-4, -3] },
+        { name: 'Fence-1', prefab: 'tiles/fence', position: [5, -4] },
+        { name: 'Fence-2', prefab: 'tiles/fence', position: [6, -4] },
+        { name: 'Fence-3', prefab: 'tiles/fence', position: [7, -4] },
+        {
+            name: 'Villager',
+            prefab: 'characters/villager',
+            position: [3, 1],
+            overrides: { Interactable: { line: 'Lovely day in Waica Village!' } },
+        },
+        {
+            name: 'Blob',
+            prefab: 'characters/blob',
+            position: [-2, -4],
+            overrides: { Patrol: { distance: 2.5, speed: 1.5 } },
+        },
+        { name: 'Potion-1', prefab: 'objects/potion', position: [-3, 2] },
+        { name: 'Potion-2', prefab: 'objects/potion', position: [7, 1] },
+        { name: 'Potion-3', prefab: 'objects/potion', position: [-6, 1] },
+        { name: 'Potion-4', prefab: 'objects/potion', position: [2, -4] },
+    ],
+    ui: ['potion-counter'],
+};
+/**
+ * The blank-start variant: same framing and y-sorted rendering, zero
+ * entities. No `follow` because there is no Player yet — the editor's
+ * palette places the first one.
+ */
+export const TOPDOWN_BLANK_SCENE = {
+    waicaScene: 3,
+    render: { sort: 'y' },
+    camera: { position: [0, 0], zoom: 12 },
+    entities: [],
+};

package/dist/ui.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The archetype's default UI pieces: self-contained HTML fragments
+ * (markup + <style>, {{stat}} bindings) keyed by piece name. Projects
+ * override them with src/ui/<name>.html files; scenes list the pieces
+ * they start with in their "ui" field.
+ *
+ * TS template literals (not .html files) because this package builds
+ * with plain tsc — no bundler to inline raw imports.
+ */
+export declare const TOPDOWN_UI: Record<string, string>;

package/dist/ui.js

@@ -0,0 +1,43 @@
+/**
+ * The archetype's default UI pieces: self-contained HTML fragments
+ * (markup + <style>, {{stat}} bindings) keyed by piece name. Projects
+ * override them with src/ui/<name>.html files; scenes list the pieces
+ * they start with in their "ui" field.
+ *
+ * TS template literals (not .html files) because this package builds
+ * with plain tsc — no bundler to inline raw imports.
+ */
+export const TOPDOWN_UI = {
+    'potion-counter': `<style>
+  .potion-counter {
+    position: absolute;
+    top: 12px;
+    left: 12px;
+    font: 600 20px system-ui, sans-serif;
+    color: #ff6b6b;
+    text-shadow: 0 1px 3px #000a;
+    user-select: none;
+  }
+</style>
+<div class="potion-counter">🧪 {{points}}</div>
+`,
+    'npc-line': `<style>
+  .npc-line {
+    position: absolute;
+    left: 50%;
+    bottom: 24px;
+    transform: translateX(-50%);
+    max-width: 70%;
+    padding: 10px 18px;
+    border-radius: 8px;
+    background: #1a1a2ecc;
+    border: 1px solid #ffffff2e;
+    font: 500 18px system-ui, sans-serif;
+    color: #f5f5f5;
+    text-shadow: 0 1px 2px #000a;
+    user-select: none;
+  }
+</style>
+<div class="npc-line">{{npcLine}}</div>
+`,
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@waica/archetype-topdown",
+  "version": "0.6.1",
+  "description": "Waica top-down archetype — opinionated setup for Zelda-like overhead adventures",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chichex/waica",
+    "directory": "packages/archetype-topdown"
+  },
+  "files": [
+    "dist",
+    "assets"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    }
+  },
+  "dependencies": {
+    "@waica/engine": "^0.6.1",
+    "@waica/behaviors": "^0.6.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3"
+  },
+  "scripts": {
+    "build": "node ../../scripts/clean-dist.mjs && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  }
+}