create-asciitorium 0.1.45 → 0.1.47

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

@@ -1,115 +1,42 @@
 # Art Directory
 
-This directory contains ASCII art assets for a project. It is organized into subfolders for maps, materials, and sprites. Each file uses plain text or JSON for easy editing and integration.
-
-## Asset Loading and Caching
-
-**IMPORTANT:** All assets are automatically loaded and cached by `AssetManager` using reactive `State` objects. When developing components that use assets:
-
-### For Component Developers
-
-**✅ DO:**
-- Use `AssetManager.getMapState(name)` to get a reactive State for maps
-- Use `AssetManager.getMaterialState(name)` to get a reactive State for materials
-- Subscribe to the returned State to react to loading completion or changes
-- Use `GameWorld.getMapState()` when working with GameWorld instances
-- Share State references across components - the cache handles deduplication
-
-**❌ DON'T:**
-- Create local caches in components (Map, Set, plain objects)
-- Use the legacy non-reactive methods (`getMap()`, `getMaterial()`) for new code
-- Load the same asset multiple times - AssetManager caches automatically
-- Store asset data in component properties - subscribe to State instead
-
-### Example Usage
-
-```typescript
-// ✅ Correct: Use reactive State from AssetManager
-const materialState = AssetManager.getMaterialState('brick-wall');
-
-// Subscribe to get the value when loaded
-materialState.subscribe((material) => {
-  if (material) {
-    // Material is loaded, use it
-    console.log('Material loaded:', material);
-  }
-});
-
-// Check current value (may be null if still loading)
-if (materialState.value) {
-  // Material already loaded from cache
-}
-
-// ✅ Correct: GameWorld automatically uses AssetManager's State cache
-const gameWorld = new GameWorld({ mapName: 'dungeon' });
-gameWorld.getMapState().subscribe((mapAsset) => {
-  // Automatically updates when map loads
-});
-
-// ❌ Wrong: Don't create your own cache
-class MyComponent {
-  private myCache: Map<string, Material> = new Map(); // DON'T DO THIS!
-}
-```
+This directory contains asciitorium art assets for the asciitorium framework. They are organized into categories: fonts, maps, materials, sounds, and sprites.
 
-### Architecture Benefits
+## Asset Loading
 
-- **Single source of truth**: AssetManager is the only cache
-- **Automatic updates**: Components react when assets load or change
-- **Memory efficient**: One copy of each asset shared across all components
-- **Hot-reload ready**: Asset changes propagate automatically to all subscribers
-- **No manual cache management**: State handles all invalidation and updates
+Assets are automatically loaded and cached by `AssetManager` using reactive
+`State` objects. The AssetManager provides a single source of truth with
+automatic caching and updates.
 
 ## Directory Structure
 
-```bash
-public/art/
-├─ maps/
-│ └─ example/
-│ ├─ map.art
-│ └─ legend.json
-│
-├─ materials/
-│ ├─ brick-wall.art
-│ └─ wooden-door.art
-│
-├─ sprites/
-├─ giant-rat.art
-└─ wolf.art
+``` bash
+art/
+├── fonts/         # ASCII font definitions
+├── maps/          # Game map layouts with legends
+├── materials/     # Wall textures and environmental materials
+├── sounds/        # Audio files (MP3)
+└── sprites/       # Animated character and object sprites
 ```
 
-## maps/
-
-Contains map layouts and legends for game environments. Maps are typically stored as text files with ASCII characters representing different terrain types, while legend files (JSON format) define what each character represents, including visual assets, collision properties, and gameplay entity types.
-
-**Contents:**
-
-- `example/` - Sample map directory containing:
-  - `map.art` - ASCII representation of the map layout
-  - `legend.json` - Character-to-entity mapping with visual assets, collision, and behavior definitions
-
-See [maps/README.md](maps/README.md) for detailed information on map file format, legend properties, and the entity/variant system.
+## Subdirectories
 
-## materials/
+### [fonts/](fonts/README.md)
 
-Includes ASCII representations of various materials and textures that can be used in game environments. Materials define layered visual representations at different distances (here, near, middle, far) and can include proximity-based sound effects and ambient events.
+ASCII font definitions for `Banner` component rendering. See the fonts README for file format details.
 
-**Contents:**
+### [maps/](maps/README.md)
 
-- `brick-wall.art` - ASCII pattern for brick wall textures
-- `bone.art` - Ground-placed bone material with placement metadata
-- `door-on-brick.art` - Door material overlaid on brick wall background
-- `wireframe-wall.art` - Complex wireframe demonstrating layered perspective rendering
+Map layouts paired with legend metadata define the position of terrain and entities. See the maps README for format specifications and the entity system.
 
-See [materials/README.md](materials/README.md) for detailed information on material file format, layer system, placement properties, and the relationship between materials and legend entities.
+### [materials/](materials/README.md)
 
-## sprites/
+Materials are used for `FirstPersonView` textures with layered depth rendering (here, near, middle, far). Materials can include placement metadata and sound effects. See the materials README for layer syntax and properties.
 
-Stores animated sprite files for characters, creatures, and other game entities. Sprites support multiple frames with configurable timing and can be referenced by legend entities for dynamic visual representation.
+### [sounds/](sounds/README.md)
 
-**Contents:**
+Audio files in MP3 format used throughout the application. See the sounds README for usage details.
 
-- `giant-rat.art` - ASCII sprite for giant rat creature
-- `wolf.art` - ASCII sprite for wolf creature
+### [sprites/](sprites/README.md)
 
-Sprites are referenced in map legends via the `asset` property and can be combined with entity types to define interactive game objects.
+Static or animated ASCII art with frame timing are in the sprites directory. They can be added using the `Art` component. See the sprites README for animation format details.

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

@@ -0,0 +1,113 @@
+# Asciitorium Fonts
+
+This directory contains ASCII font files for the **Banner** component. Fonts
+allow you to display large, stylized text using ASCII art characters.
+
+## Font File Format
+
+Font files use the `.art` extension and follow a structured format with metadata
+separators:
+
+### File Structure
+
+``` txt
+§ {"kind":"font"}
+¶ {"character":"A"}
+╭─╮
+│ │
+├─┤
+╵ ╵
+
+¶ {"character":"a"}
+
+╭─╮
+╭─┤
+╰─╰
+
+¶ {"character":["b", "B"]}
+╷
+├─╮
+│ │
+╯─╯
+```
+
+### Key Components
+
+1. **File Header** (`§` separator)
+   - Must start with `§ {"kind":"font"}`
+   - Indicates this is a font asset
+
+2. **Glyph Sections** (`¶` separator)
+   - Each glyph begins with `¶ {"character":"x"}` where `x` is the character
+   - Character can be a single string: `"a"`
+   - Or an array for multiple mappings: `["b", "B"]` (both lowercase and
+     uppercase)
+   - Glyph content follows immediately after the metadata line
+
+3. **Glyph Content**
+   - ASCII art representation of the character
+   - Each glyph can be any width/height
+   - Vertical positioning is preserved (blank lines matter!)
+   - Maximum font height is determined by the tallest glyph
+
+**Tips:**
+
+- Empty lines within glyphs are preserved to maintain vertical alignment
+- The first line after the glyph metadata is part of the character (no automatic
+  trimming)
+- Map multiple characters to the same glyph using arrays:
+  `{"character":["a","A"]}`
+- All glyphs should have consistent height for best results (pad with empty
+  lines if needed)
+
+## Using Fonts in Your App
+
+### Basic Usage
+
+```tsx
+<Banner font="pencil" text="asciitorium" />
+```
+
+### With Letter Spacing
+
+```tsx
+<Banner font="marker" text="HELLO" letterSpacing={1} />
+```
+
+### With Reactive State
+
+```tsx
+import { State } from 'asciitorium';
+
+const titleText = new State<string>("Welcome");
+
+<Banner font="shadows" text={titleText} align="center" />
+```
+
+### Available Props
+
+- `font` (required): Name of the font file (without `.art` extension)
+- `text`: String or `State<string>` to render
+- `letterSpacing`: Additional spacing between characters (default: 0)
+- Plus all standard component props: `position`, `border`, `align`, `style`,
+  etc.
+
+## Technical Details
+
+### Loading
+
+Fonts are loaded asynchronously via the `AssetManager`:
+
+```typescript
+const fontAsset = await AssetManager.getFont('myfont');
+```
+
+### Caching
+
+Font assets are cached on first load - subsequent uses of the same font reuse
+the cached data.
+
+### Fallback Rendering
+
+If a character is not found in the font, the Banner component renders the
+character itself as a single-width glyph on the top line.

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

@@ -0,0 +1,113 @@
+# Asciitorium Fonts
+
+This directory contains ASCII font files for the **Banner** component. Fonts
+allow you to display large, stylized text using ASCII art characters.
+
+## Font File Format
+
+Font files use the `.art` extension and follow a structured format with metadata
+separators:
+
+### File Structure
+
+``` txt
+§ {"kind":"font"}
+¶ {"character":"A"}
+╭─╮
+│ │
+├─┤
+╵ ╵
+
+¶ {"character":"a"}
+
+╭─╮
+╭─┤
+╰─╰
+
+¶ {"character":["b", "B"]}
+╷
+├─╮
+│ │
+╯─╯
+```
+
+### Key Components
+
+1. **File Header** (`§` separator)
+   - Must start with `§ {"kind":"font"}`
+   - Indicates this is a font asset
+
+2. **Glyph Sections** (`¶` separator)
+   - Each glyph begins with `¶ {"character":"x"}` where `x` is the character
+   - Character can be a single string: `"a"`
+   - Or an array for multiple mappings: `["b", "B"]` (both lowercase and
+     uppercase)
+   - Glyph content follows immediately after the metadata line
+
+3. **Glyph Content**
+   - ASCII art representation of the character
+   - Each glyph can be any width/height
+   - Vertical positioning is preserved (blank lines matter!)
+   - Maximum font height is determined by the tallest glyph
+
+**Tips:**
+
+- Empty lines within glyphs are preserved to maintain vertical alignment
+- The first line after the glyph metadata is part of the character (no automatic
+  trimming)
+- Map multiple characters to the same glyph using arrays:
+  `{"character":["a","A"]}`
+- All glyphs should have consistent height for best results (pad with empty
+  lines if needed)
+
+## Using Fonts in Your App
+
+### Basic Usage
+
+```tsx
+<Banner font="pencil" text="asciitorium" />
+```
+
+### With Letter Spacing
+
+```tsx
+<Banner font="marker" text="HELLO" letterSpacing={1} />
+```
+
+### With Reactive State
+
+```tsx
+import { State } from 'asciitorium';
+
+const titleText = new State<string>("Welcome");
+
+<Banner font="shadows" text={titleText} align="center" />
+```
+
+### Available Props
+
+- `font` (required): Name of the font file (without `.art` extension)
+- `text`: String or `State<string>` to render
+- `letterSpacing`: Additional spacing between characters (default: 0)
+- Plus all standard component props: `position`, `border`, `align`, `style`,
+  etc.
+
+## Technical Details
+
+### Loading
+
+Fonts are loaded asynchronously via the `AssetManager`:
+
+```typescript
+const fontAsset = await AssetManager.getFont('myfont');
+```
+
+### Caching
+
+Font assets are cached on first load - subsequent uses of the same font reuse
+the cached data.
+
+### Fallback Rendering
+
+If a character is not found in the font, the Banner component renders the
+character itself as a single-width glyph on the top line.