create-asciitorium 0.1.46 → 0.1.47

package/dist/templates/base/public/art/materials/README.md

@@ -1,27 +1,19 @@
-# Materials Directory
+# Asciitorium Materials
 
-This directory contains ASCII art representations of various materials and textures that can be used in asciitorium games. Materials define the visual appearance of surfaces, walls, floors, and other environmental elements.
-
-## Contents
-
-- `wireframe.art`: A complex wireframe pattern demonstrating layered first-person perspective rendering
+This directory contains ASCII art material files for the **FirstPersonView** and
+**MapView** components. Materials define the visual appearance of walls, floors,
+and other environmental surfaces with depth-based layering.
 
 ## Material File Format
 
-Material files use a special format that combines ASCII art with JSON metadata to define how materials should be rendered in different contexts.
+Material files use the `.art` extension and follow a structured format with
+metadata separators:
 
 ### File Structure
 
-Materials use paragraph markers (`¶`) to separate different layers or variants, with each section containing:
-
-1. **Metadata line**: JSON configuration starting with `¶`
-2. **ASCII art**: The visual representation using text characters
-
-### Example Material
-
-Here's a section from `wireframe.art` showing the layered format:
+#### Wall Material
 
-```text
+```txt
 § {"kind":"material","usage":"first-person"}
 ¶ {"layer":"here","position":"left","x":-1}
 |╲
@@ -41,11 +33,9 @@ Here's a section from `wireframe.art` showing the layered format:
 |____________|
 ```
 
-### Example with Placement
+#### Ground Material
 
-Here's an example from `bone.art` showing placement for ground materials:
-
-```text
+```txt
 § {"kind":"material","usage":"first-person","placement":"ground"}
 ¶ {"layer":"here","position":"center"}
   ⎽       ⎽
@@ -59,221 +49,105 @@ Here's an example from `bone.art` showing placement for ground materials:
 ‥
 ```
 
-## Metadata Properties
-
-### Section Header (`§`)
-
-- **kind**: Type of asset (`"material"`)
-- **usage**: Rendering context (`"first-person"`, `"top-down"`, `"side-scroller"`)
-- **placement**: Surface placement (`"ground"`, `"ceiling"`) - optional property that indicates where the material should be applied. Use `"scenery"` for general background/wall materials (default)
-- **onEnterSound**: Sound that triggers when the player steps onto this tile (optional)
-  - Value: `"filename.mp3"`
-  - Sound files should be placed in `art/sounds/` directory
-- **onExitSound**: Sound that triggers when the player steps off this tile (optional)
-  - Value: `"filename.mp3"`
-  - Sound files should be placed in `art/sounds/` directory
-- **ambientSound**: Looping sound while material is visible (optional, future feature)
-  - Value: `"filename.mp3"`
-  - Sound files should be placed in `art/sounds/` directory
-
-### Layer Configuration (`¶`)
-
-- **layer**: Depth layer (`"here"`, `"near"`, `"middle"`, `"far"`)
-- **position**: Horizontal alignment (`"left"`, `"center"`, `"right"`)
-- **x**: Horizontal offset for precise positioning
-
-## Layer System
-
-The wireframe material demonstrates a sophisticated layering system for first-person perspective:
-
-- **here**: Immediate foreground elements (closest to viewer)
-- **near**: Close objects with full detail
-- **middle**: Mid-distance objects with moderate detail
-- **far**: Distant objects with minimal detail
-
-Each layer can have left, center, and right positioned elements with specific x-offsets for proper perspective alignment.
-
-## Visual Techniques
-
-Materials can use various ASCII characters for different effects:
-
-- **Box drawing**: `|`, `─`, `╱`, `╲`, `╭`, `╮`, `╯`, `╰` for structural lines
-- **Perspective lines**: `╱`, `╲` for diagonal depth
-- **Solid fills**: `_` for horizontal surfaces
-- **Spacing**: Careful use of spaces for proper alignment and depth
-
-## Usage in Maps
+### Key Components
+
+1. **File Header** (`§` separator)
+   - Must start with `§ {"kind":"material"}`
+   - Indicates this is a material asset
+   - Defines material properties:
+     - `usage`: Rendering context (`"first-person"`, `"top-down"`,
+       `"side-scroller"`)
+     - `placement`: Surface type (`"scenery"` [default], `"ground"`,
+       `"ceiling"`)
+     - `onEnterSound`: Sound file to play when player enters tile (e.g.,
+       `"splash.mp3"`)
+     - `onExitSound`: Sound file to play when player exits tile
+     - `ambientSound`: Looping sound while visible (future feature)
+
+2. **Layer Sections** (`¶` separator)
+   - Each layer begins with `¶` followed by JSON metadata
+   - Layer metadata:
+     - `layer`: Depth layer (`"here"`, `"near"`, `"middle"`, `"far"`)
+     - `position`: Horizontal alignment (`"left"`, `"center"`, `"right"`)
+     - `x`: Horizontal offset for precise positioning
+   - Layer content follows immediately after the metadata line
+
+3. **Layer Content**
+   - ASCII art representation of the material at that depth
+   - Each layer can be any width/height
+   - Blank lines are preserved
+   - Multiple layers create perspective depth
+
+**Tips:**
+
+- `"here"` layer is closest to viewer (immediate foreground)
+- `"far"` layer is furthest (distant background)
+- Use box drawing characters for structure: `|`, `─`, `╱`, `╲`, `╭`, `╮`, `╯`,
+  `╰`
+- Each layer can have left/center/right positioned elements with x-offsets for
+  perspective alignment
+
+## Using Materials in Your App
 
 Materials are referenced in map legends through the `asset` property:
 
+### Map Legend Entry
+
 ```json
 {
   "chars": ["#"],
-  "kind": "material",
   "name": "wireframe-wall",
   "solid": true,
-  "asset": "material/wireframe"
+  "material": "wireframe"
 }
 ```
 
-The system will load the corresponding `wireframe.art` file and render the appropriate layer based on the viewing context and distance.
-
-## Relationship with Legend Entities
-
-The architecture separates visual presentation (materials) from gameplay behavior (legend entities):
-
-### Materials Handle
+The system loads the corresponding `wireframe.art` file and renders the
+appropriate layer based on viewing context and distance.
 
-- **Visual representation** at different distances (layer system)
-- **Ambient sounds** tied to proximity (howling when near a wolf wall)
-- **Transition sounds** when moving between layers (door creaking as you approach)
-- **Distance-based events** (footsteps on different floor types)
+## Technical Details
 
-### Legend Entities Handle
+### Loading
 
-- **Interactions** (opening doors, picking up items, talking to NPCs)
-- **Game state** (is door locked/unlocked, enemy health, treasure quantity)
-- **Collision detection** (solid vs passable)
-- **Gameplay behaviors** (enemy AI, trap triggers, puzzle mechanics)
+Materials are loaded asynchronously via the `AssetManager`:
 
-### Example: Door Material + Entity
-
-**Material file** (`door-wooden.art`):
-
-```text
-§ {"kind":"material","usage":"first-person","placement":"scenery","onEnterSound":"door-open.mp3","onExitSound":"door-close.mp3"}
-¶ {"layer":"here","position":"center"}
-[ASCII art for door at immediate distance - plays open sound when player steps onto this tile, close sound when leaving]
-¶ {"layer":"near","position":"center"}
-[ASCII art for door at near distance]
-```
-
-**Legend entry** (references the material):
-
-```json
-{
-  "chars": ["o"],
-  "kind": "material",
-  "entity": "door",
-  "variant": "wooden",
-  "name": "Wooden Door",
-  "solid": false,
-  "asset": "material/door-wooden",
-  "state": {
-    "locked": false,
-    "open": false
-  },
-  "interactions": {
-    "onInteract": "toggle-door",
-    "onMelee": "bash-door"
-  }
-}
-```
-
-This design allows:
-
-- **Reusable materials**: Same door material can be used for locked/unlocked/magic doors
-- **Instance-specific behavior**: Each door on the map can have different state (some locked, some open)
-- **Separation of concerns**: Artists focus on materials, game designers focus on legend entities
-- **Sensory cohesion**: Sounds/visuals stay together in material files
-
-### Example: Puddle with Sound
-
-Ground materials can also use `onEnterSound` for footstep sounds:
-
-**Material file** (`puddle.art`):
-
-```text
-§ {"kind":"material","usage":"first-person","placement":"ground","onEnterSound":"splash.mp3"}
-¶ {"layer":"here","position":"center"}
-  ~~~~
- ~~~~~~
-~~~~~~~~
- ~~~~~~
-  ~~~~
-¶ {"layer":"near","position":"center"}
-~~
-```
-
-**Legend entry**:
-
-```json
-{
-  "chars": ["~"],
-  "kind": "material",
-  "name": "puddle",
-  "solid": false,
-  "asset": "material/puddle"
-}
+```typescript
+const materialAsset = await AssetManager.getMaterial('wireframe');
 ```
 
-When the player steps onto a `~` tile, they'll hear a splash sound. This same pattern works for:
-
-- Gravel paths (`crunch.mp3`)
-- Creaky floorboards (`creak.mp3`)
-- Grass (`rustle.mp3`)
-- Snow (`snow-step.mp3`)
-
-## Sound System
-
-Materials support sound playback through properties in the section header (`§`). Sounds are automatically triggered by the GameWorld when the player moves.
-
-### Sound File Requirements
-
-- **Location**: Place sound files in `art/sounds/` directory relative to your project root
-- **Formats**: MP3, WAV, and other browser-supported audio formats
-- **Environment**: Sounds only play in web environments (browser), not in CLI mode
-- **Reference**: Use filename in section header: `{"onEnterSound":"filename.mp3"}`
-
-### Sound Properties
+### Caching
 
-- **onEnterSound**: Plays once when the player steps onto a tile with this material
-- **onExitSound**: Plays once when the player steps off a tile with this material
-- **ambientSound**: Looping sound while material is visible (future feature)
+Material assets are cached on first load - subsequent uses of the same material
+reuse the cached data.
 
-### How Sound Triggering Works
+### Sound System
 
-When using `GameWorld` for game logic:
+Materials support sound playback through properties in the file header (`§`):
 
-1. Player moves to a new tile coordinate (x, y)
-2. GameWorld triggers `onExitSound` for the previous tile's material (if any)
-3. GameWorld checks the new tile's legend entry
-4. If the entry is a material, GameWorld loads the material asset
-5. If the material has `onEnterSound`, the sound plays
-6. When the player leaves the tile, `onExitSound` plays (if defined)
-7. Sounds play once per tile entry/exit (moving onto the same tile repeatedly will retrigger both sounds)
+- **Sound files location**: `art/sounds/` directory
+- **Supported formats**: MP3
+- **Environment**: Sounds only play in web mode (not CLI)
+- **onEnterSound**: Plays once when player steps onto tile with this material
+- **onExitSound**: Plays once when player steps off tile
 
-### Controlling Sound Playback
-
-You can control sound globally through the `SoundManager`:
+Control sounds globally via `SoundManager`:
 
 ```typescript
 import { SoundManager } from 'asciitorium';
 
-// Disable all sounds
-SoundManager.setEnabled(false);
-
-// Re-enable sounds
-SoundManager.setEnabled(true);
-
-// Check if sounds are enabled
-const enabled = SoundManager.isEnabled();
-
-// Manually play a sound
-SoundManager.playSound('custom-sound.mp3');
-
-// Clear sound cache
-SoundManager.clearCache();
+SoundManager.setEnabled(false);  // Disable all sounds
+SoundManager.setEnabled(true);   // Re-enable sounds
+SoundManager.playSound('custom-sound.mp3');  // Play manually
 ```
 
-## Creating New Materials
+### Layer System
 
-When creating new material files:
+The layering system creates first-person perspective depth:
 
-1. Start with a section header (`§`) defining the material type and usage
-2. Define multiple layers for depth perception
-3. Use consistent positioning and x-offsets for alignment
-4. Test with different viewing distances and angles
-5. Follow ASCII art best practices for readability
+- **here**: Immediate foreground (closest to viewer)
+- **near**: Close objects with full detail
+- **middle**: Mid-distance objects with moderate detail
+- **far**: Distant objects with minimal detail
 
-Use this directory as a reference for creating rich, layered materials that enhance the visual depth of your asciitorium games.
+Each layer can have left, center, and right positioned elements with specific
+x-offsets for proper perspective alignment.

package/dist/templates/base/public/art/sounds/README.md

@@ -0,0 +1,9 @@
+# Sounds Directory
+
+This directory contains audio assets in MP3 format used throughout the
+application.
+
+## Usage
+
+Sound files can be referenced in material definitions, sprite definitions, or
+played programmatically through the application's audio system.

package/dist/templates/base/public/art/sprites/README.md

@@ -0,0 +1,136 @@
+# Asciitorium Sprites
+
+This directory contains ASCII sprite files for the **Art** component. Sprites
+allow you to display static or animated ASCII art via the Art component.
+
+## Sprite File Format
+
+Sprite files use the `.art` extension and follow a structured format with
+metadata separators:
+
+### File Structure
+
+#### Simple Static Sprite (no metadata)
+
+``` txt
+ ▄█▀█▄  ▄███▄
+▐█░██████████▌
+ ██▒█████████
+  ▀████████▀
+     ▀██▀
+```
+
+#### Animated Sprite with Metadata
+
+``` txt
+§ {"kind":"sprite","loop":true,"default-frame-rate":100}
+¶ {"duration":1000}
+ ▄█▀█▄  ▄███▄
+▐█░██████████▌
+ ██▒█████████
+  ▀████████▀
+     ▀██▀
+¶
+  ▄█▀▄  ▄██▄
+ ▐█░████████▌
+  ██▒███████
+   ▀██████▀
+      ▀▀
+¶
+   ▄█▀▄▄██▄
+  ▐█░██████▌
+   ██▒█████
+    ▀████▀
+      ▀▀
+```
+
+### Key Components
+
+1. **File Header** (`§` separator) - Optional
+   - Must start with `§ {"kind":"sprite"}`
+   - Indicates this is a sprite asset
+   - Defines default animation settings:
+     - `default-frame-rate`: Default duration in milliseconds for each frame
+     - `loop`: Whether animation loops (true/false)
+     - `transparent`: Single character to treat as transparent (e.g., `" "`)
+
+2. **Frame Sections** (`¶` separator) - Optional
+   - Each frame begins with `¶` followed by optional JSON metadata
+   - Frame metadata (all optional):
+     - `duration`: Override default frame duration in milliseconds
+     - `sound`: Sound ID to play when frame displays
+   - Frame content follows immediately after the metadata line
+   - If no metadata needed, use `¶` alone
+
+3. **Frame Content**
+   - ASCII art representation of the sprite frame
+   - Each frame can be any width/height
+   - Blank lines are preserved
+   - Maximum sprite dimensions determined by largest frame
+
+**Tips:**
+
+- Files without `§` or `¶` are treated as single-frame static sprites
+- Empty lines within frames are preserved for vertical spacing
+- The first line after frame metadata is part of the sprite (no automatic
+  trimming)
+- All frames should have consistent dimensions for best results
+- Use the `transparent` property to define overlay sprites
+
+## Using Sprites in Your App
+
+### Basic Usage (Async Loading)
+
+```tsx
+<Art sprite="balloon" />
+```
+
+### With Reactive State
+
+```tsx
+import { State } from 'asciitorium';
+
+const playerSprite = new State<string>(defaultArt);
+
+<Art content={playerSprite} />
+```
+
+### Available Props
+
+- `sprite`: Name of sprite file (without `.art` extension) to load asynchronously
+- `content`: String or `State<string>` for inline sprite content
+- `children`: Alternative way to provide inline content
+- Plus all standard component props: `position`, `border`, `align`, `style`,
+  etc.
+
+## Technical Details
+
+### Loading
+
+Sprites are loaded asynchronously via the `AssetManager`:
+
+```typescript
+const spriteAsset = await AssetManager.getSprite('mysprite');
+```
+
+### Caching
+
+Sprite assets are cached on first load - subsequent uses of the same sprite
+reuse the cached data.
+
+### Animation System
+
+The Art component automatically:
+
+- Parses sprite metadata and frames
+- Schedules frame transitions based on duration
+- Handles looping vs. one-shot playback
+- Requests renders when frames change
+- Cleans up timers when component is destroyed
+
+### Dimension Calculation
+
+Component dimensions are automatically calculated from the largest frame:
+
+- Width: Maximum line length across all frames
+- Height: Maximum number of lines across all frames

package/dist/templates/base/src/main.tsx

@@ -1,7 +1,7 @@
 import {
   App,
   Art,
-  Button,
+  Banner,
   Column,
   Text,
   PerfMonitor,
@@ -25,14 +25,14 @@ const app = (
     <Keybind keyBinding="p" action={togglePerfMonitor} />
 
     <Column style={{ align: 'center', gap: 1, width: '100%' }}>
-      <Art font="pencil" text="Welcome to" align="center" />
-      <Art src="asciitorium" align="center" />
+      <Banner font="pencil" text="Welcome to" align="center" />
+      <Banner font="shadows" text="asciitorium" align="center" />
 
       <Text style={{ align: 'center', gap: 1 }}>
         Edit src/main.tsx and save to reload.
       </Text>
 
-      <Art src="beating-heart" width={20} align="center" />
+      <Art sprite="beating-heart" width={20} align="center" />
 
       <Text style={{ align: 'center', gap: 1 }}>
         Press [P] to toggle performance monitor

package/dist/templates/base/src/reference-validation.tsx

@@ -291,7 +291,7 @@ Line 3
       <Column gap={1}>
         <Text>If art/asciitorium.art exists, it should render below:</Text>
         {/* Uncomment if you have art files:
-        <Art src="asciitorium" align="center" />
+        <Art sprite="asciitorium" align="center" />
         */}
         <Text>Art test skipped (no art files in template)</Text>
       </Column>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-asciitorium",
-  "version": "0.1.46",
+  "version": "0.1.47",
   "private": false,
   "description": "Scaffold a Vite + TypeScript project prewired for asciitorium (web + cli).",
   "bin": {