create-asciitorium 0.1.34 → 0.1.36

package/README.md

@@ -1,6 +1,6 @@
 # create-asciitorium
 
-`create-asciitorium` is a command-line tool that helps you quickly scaffold a new [asciitorium](https://github.com/iroknee/asciitorium) project. It sets up all the necessary files, folders, and dependencies so you can start building ASCII art-based web applications with minimal setup.
+`create-asciitorium` is a command-line tool that helps you quickly scaffold a new [asciitorium](https://github.com/iroknee/asciitorium) project. It sets up all the necessary files, folders, and dependencies so you can start building CLUI applications with minimal setup.
 
 ## Features
 
@@ -41,7 +41,7 @@ npm run build
 
 ### Other Scripts
 
-Asciitorium supports viewing ascii art files. There are a few easy ways to create some specific ascii art, including FIGlet fonts and mazes/maps.
+Asciitorium supports viewing ascii art files. There are a few easy ways to create some specific ascii art, including FIGlet fonts and maps.
 
 To generate FIGlet ASCII art assets (automatically placed in public/art):
 
@@ -94,8 +94,8 @@ To generate ASCII maze files (placed in public/art/mazes):
 node scripts/maze-builder.js <width> <height> <filename> [--smooth]
 
 # Examples:
-node scripts/maze-builder.js 10 10 dungeon-level-1.txt
-node scripts/maze-builder.js 15 20 castle-maze.txt --smooth
+node scripts/maze-builder.js 10 10 dungeon-level-1.art
+node scripts/maze-builder.js 15 20 castle-maze.art --smooth
 ```
 
 The `--smooth` flag uses Unicode box drawing characters for improved visual appearance.

package/dist/index.js

@@ -34,7 +34,8 @@ async function main() {
         console.log(red(`✖ Directory "${target}" already exists.`));
         process.exit(1);
     }
-    const pm = argv.pm ?? process.env.npm_config_user_agent?.split('/')[0] ?? 'npm';
+    // Always use npm as the package manager
+    const pm = argv.pm ?? 'npm';
     const template = argv.template ?? 'base';
     const useGit = Boolean(argv.git);
     const doInstall = Boolean(argv.install);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/templates/base/index.html

@@ -2,7 +2,7 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <link rel="icon" type="image/png" href="/images/logo.png" />
+    <link rel="icon" type="image/png" href="/logo.png" />
     <title>asciitorium</title>
     <link rel="stylesheet" href="index.css" />
   </head>

package/dist/templates/base/package.json

@@ -10,7 +10,7 @@
     "cli": "tsx src/main.tsx",
     "figlet": "node scripts/gen-figlet-art.js",
     "figlet:fonts": "node -e 'require(\"figlet\").fonts((_, f) => console.log(f.join(\"\\n\")))\"",
-    "maze-builder": "node scripts/maze-builder.js"
+    "map-builder": "node scripts/map-builder.js"
   },
   "devDependencies": {
     "typescript": "^5.6.0",

package/dist/templates/base/public/art/ART-DESIGN-SPEC.md

@@ -0,0 +1,375 @@
+# Art Asset Format Specification
+
+This document defines the metadata format for ASCII art assets in asciitorium, including fonts, materials, and sprites.
+
+## Overview
+
+Art assets use a text-based format that combines:
+
+- **Section headers** (`§`) defining global asset properties
+- **Layer/frame separators** (`¶`) with metadata for each section
+- **ASCII art content** following each separator
+
+## Design Goals
+
+1. **Human-readable**: Artists should be able to read and write metadata without tooling
+2. **Simple**: Use standard JSON format with flat key-value structure
+3. **No nesting**: Flat data structures only - no nested objects or arrays
+4. **Consistent**: Same format works for materials, sprites, and font asset types
+5. **Extensible**: Easy to add new properties without breaking existing assets
+
+## Format Syntax
+
+### File Header (`§`)
+
+The file header appears once at the beginning of the file and defines the asset type and global properties.
+
+**Format:**
+
+```json
+§ {"key":"value","key":"value"}
+```
+
+**Example:**
+
+```json
+§ {"kind":"material","usage":"first-person","placement":"scenery"}
+```
+
+### Layer/Frame Separator (`¶`)
+
+Separates different layers (materials), characters (fonts) or frames (sprites) with section-specific metadata.
+
+**Format:**
+
+```json
+¶ {"key":"value","key":"value"}
+[ASCII art content follows]
+```
+
+**Example:**
+
+```json
+¶ {"layer":"here","pos":"center"}
+   |‽‽‽‽‽‽‽|
+   |‽‽‽‽‽‽‽|
+```
+
+## Parsing Rules
+
+### JSON Format
+
+1. **Parse as JSON**: Standard JSON.parse() after removing separator character
+2. **Primitive values only**: All values must be strings, numbers, or booleans
+3. **No nesting**: Objects must be flat - no nested objects or arrays
+4. **Empty metadata**: Empty separator `¶` or `§` is valid (inherits defaults)
+
+### Single-Frame Sprites
+
+If a file does not start with a `§` file header, it is assumed to be a single-frame sprite with no metadata:
+
+```txt
+  ___
+ /   \
+|  o  |
+ \___/
+```
+
+This is equivalent to:
+
+```json
+§ {"kind":"sprite","loop":"false"}
+¶
+  ___
+ /   \
+|  o  |
+ \___/
+```
+
+### Empty Separators
+
+A separator with no metadata is valid for sprites:
+
+```txt
+¶
+[ASCII art content]
+```
+
+This inherits defaults or indicates a frame with no special properties.
+
+## Font Assets
+
+Fonts define ASCII art representations of characters for rendering text in stylized formats.
+
+### File Header Properties
+
+| Key    | Values | Required | Description           |
+| ------ | ------ | -------- | --------------------- |
+| `kind` | `font` | Yes      | Asset type identifier |
+
+### Character Separator Properties
+
+| Key         | Values | Required | Description                         |
+| ----------- | ------ | -------- | ----------------------------------- |
+| `character` | string | Yes      | The character this glyph represents |
+
+### Font Example
+
+``` json
+§ {"kind":"font"}
+¶ {"character":"a"}
+
+╭─╮
+╭─┤
+╰─╰
+
+¶ {"character":"b"}
+│
+├─╮
+│ │
+╯─╯
+
+¶ {"character":"c"}
+
+╭─╮
+│
+╰─╯
+```
+
+### Font Design Rules
+
+- Each character glyph should have consistent height (including leading/trailing blank lines)
+- Characters can have variable width
+- Blank lines before/after the glyph art create vertical spacing
+- The `character` property must be a single character (letter, number, punctuation, etc.)
+- Fonts are typically loaded by name and used to render styled text
+
+## Sprite Assets
+
+Sprites define animated ASCII art with multiple frames.
+
+### File Header Properties
+
+| Key                  | Values          | Required | Description                                |
+| -------------------- | --------------- | -------- | ------------------------------------------ |
+| `kind`               | `sprite`        | Yes      | Asset type identifier                      |
+| `loop`               | `true`, `false` | No       | Whether animation loops (default: `false`) |
+| `default-frame-rate` | number (ms)     | No       | Default frame duration in milliseconds (default is 250 if none is supplied)     |
+
+### Frame Separator Properties
+
+| Key        | Values      | Required | Description                        |
+| ---------- | ----------- | -------- | ---------------------------------- |
+| `duration` | number (ms) | No       | Frame duration (overrides default) |
+| `sound`    | filename    | No       | Sound to play when frame displays  |
+| `event`    | string      | No       | Custom event name to trigger       |
+
+### Sprite Example
+
+```
+§ {"kind":"sprite","loop":true,"default-frame-rate":120}
+¶ {"duration":1000}
+                _ _ _             _
+  __ _ ___  ___(_|_) |_ ___  _ __(_)_   _ _ __ ___
+ / _` / __|/ __| | | __/ _ \| '__| | | | | '_ ` _ \
+| (_| \__ \ (__| | | || (_) | |  | | |_| | | | | | |
+ \__,_|___/\___|_|_|\__\___/|_|  |_|\__,_|_| |_| |_|
+¶ {"duration":500}
+              .   _ * _             *     .
+  __ _ ___  ___(_|_).|_   *  _ __(_)_   _   *  __
+ / _` / __|/ _ .  |  __/  . \ '__| | | | '   `  \ .
+| (_| \__  (__| *|.| || (_) |  * | | |_|  *| | | │ .
+ \__,_|___/\__ ._|_|\__\  * /|_|   .|\__   |_| |_│
+¶
+          *      _    *     .    *     .    *
+  __   *      (_|_)   .  *   _ __   .     .    __
+ /   `    __|  |    __/   * \ '__|     *      ` \
+| *   * \__    | | || (_) |   .  |  *  *   |   | │
+   .  .|___/   |_| \__\___/|_|   .    .  |_|  . |_│
+```
+
+### Animation Control
+
+- **loop:true**: Animation repeats from first frame after last frame
+- **loop:false**: Animation plays once and stops on last frame
+
+## Material Assets
+
+Materials define visual representations at different distances in first-person view.
+
+### File Header Properties
+
+| Key            | Values                                      | Required | Description                       |
+| -------------- | ------------------------------------------- | -------- | --------------------------------- |
+| `kind`         | `material`                                  | Yes      | Asset type identifier             |
+| `usage`        | `first-person`, `top-down`, `side-scroller` | Yes      | Rendering context                 |
+| `placement`    | `scenery`, `ground`, `ceiling`              | No       | Surface type (default: `scenery`) |
+| `onEnterSound` | filename                                    | No       | Sound when player enters tile     |
+| `onExitSound`  | filename                                    | No       | Sound when player exits tile      |
+| `ambientSound` | filename                                    | No       | Looping sound near this material  |
+
+### Layer Separator Properties
+
+| Key     | Values                          | Required | Description                     |
+| ------- | ------------------------------- | -------- | ------------------------------- |
+| `layer` | `here`, `near`, `middle`, `far` | Yes      | Distance layer                  |
+| `pos`   | `left`, `center`, `right`       | Yes      | Horizontal position             |
+| `x`     | number                          | No       | Horizontal offset for alignment |
+
+### Material Example
+
+```
+§ {"kind":"material","usage":"first-person","placement":"scenery","onEnterSound":"door-open.mp3","onExitSound":"door-close.mp3"}
+¶ {"layer":"here","pos":"left"}
+ ╲
+ ┊╲
+╲┊ ╲
+¶ {"layer":"here","pos":"center"}
+   |‽‽‽‽‽‽‽‽‽‽|
+   |‽‽‽‽‽‽‽‽‽‽|
+   |‽‽‽‽‽‽‽‽‽‽|
+¶ {"layer":"here","pos":"right"}
+      ╱
+     ╱┊
+    ╱ ┊╱
+¶ {"layer":"near","pos":"center"}
+ …… ……… ……… …
+┊……┊………┊………┊…┊
+┊┊…╭───────╮…┊
+┊……|┋┋┋┋┋┋┋|…┊
+¶ {"layer":"middle","pos":"center"}
+ … … ……
+┊…┊…┊……┊
+┊…╭──╮…┊
+┊…|┋┋|…┊
+¶ {"layer":"far","pos":"center"}
+ ……
+┊……┊
+┊||┊
+```
+
+### Layer System
+
+Materials use a layered perspective system that adapts to different usage contexts:
+
+#### First-Person Usage
+
+- **here**: Immediate foreground (player is on this tile)
+- **near**: Close distance (1-2 tiles away)
+- **middle**: Mid distance (3-5 tiles away)
+- **far**: Far distance (6+ tiles away)
+
+#### Side-Scroller Usage (Parallax Layers)
+
+- **here**: Interactive elements (platforms player stands on, walls player collides with)
+- **near**: Foreground elements (close platforms, foreground decorations)
+- **middle**: Midground elements (trees, buildings, mid-distance scenery)
+- **far**: Background elements (mountains, clouds, distant scenery)
+
+#### Top-Down Usage
+
+- **here**: Ground level elements (floors, paths the player walks on)
+- **near**: Low obstacles and ground decorations
+- **middle**: Medium height elements (furniture, props)
+- **far**: Tall elements and ceiling details
+
+Each layer can have `left`, `center`, and `right` positioned elements for additional composition control.
+
+### Sound Triggers
+
+Sound properties are defined once in the file header and apply to the entire material:
+
+- **onEnterSound**: Plays once when player steps onto the tile
+- **onExitSound**: Plays once when player leaves the tile
+- **ambientSound**: Looping sound while material is visible (future feature)
+
+Sound files must be placed in `art/sounds/` directory.
+
+### Side-Scroller Material Example
+
+Here's an example of materials for a side-scrolling platformer game:
+
+**Ground Platform:**
+
+```
+§ {"kind":"material","usage":"side-scroller","placement":"ground","onEnterSound":"step.mp3"}
+¶ {"layer":"here","pos":"center"}
+═══════════════════════
+▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
+```
+
+**Brick Wall:**
+
+```
+§ {"kind":"material","usage":"side-scroller","placement":"scenery"}
+¶ {"layer":"here","pos":"center"}
+█▓▒░█▓▒░█▓▒░
+░▒▓█░▒▓█░▒▓█
+█▓▒░█▓▒░█▓▒░
+░▒▓█░▒▓█░▒▓█
+```
+
+**Background Mountain (Parallax):**
+
+```
+§ {"kind":"material","usage":"side-scroller","placement":"scenery"}
+¶ {"layer":"far","pos":"center"}
+      /\
+     /  \
+    /    \
+   /      \
+  /        \
+¶ {"layer":"middle","pos":"center"}
+    /\  /\
+   /  \/  \
+  /        \
+¶ {"layer":"near","pos":"center"}
+ /\/\
+/    \
+```
+
+In side-scrollers, the layer system naturally supports parallax scrolling where `far` layers move slower than `here` layers, creating depth perception.
+
+## Validation Rules
+
+### Required Properties
+
+- File header MUST have `kind` property
+- Material layers MUST have `layer` and `pos` properties
+- Sprite frames MAY omit all properties (inherits defaults)
+
+### No Nesting Rule
+
+- All values MUST be primitives (string, number, or boolean)
+- Nested objects are NOT allowed
+- Arrays are NOT allowed
+- This keeps the format simple and predictable
+
+**Invalid (nested object):**
+
+```json
+{ "onEnter": { "sound": "door.mp3" } }
+```
+
+**Valid (flat structure with primitives):**
+
+```json
+{ "onEnterSound": "door.mp3", "duration": 1000, "loop": true }
+```
+
+### Value Constraints
+
+- **layer**: Must be one of `here`, `near`, `middle`, `far`
+- **pos**: Must be one of `left`, `center`, `right`
+- **placement**: Must be one of `scenery`, `ground`, `ceiling`
+- **usage**: Must be one of `first-person`, `top-down`, `side-scroller`
+- **loop**: Must be boolean `true` or `false`
+- **duration**: Must be positive number (milliseconds)
+- **default-frame-rate**: Must be positive number (milliseconds)
+- **x**: Must be number (integer)
+
+### Sound File References
+
+- Sound properties contain filename only (no path)
+- Files resolved relative to `art/sounds/` directory
+- Format: `"onEnterSound":"door-open.mp3"` not `"onEnterSound":"art/sounds/door-open.mp3"`

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

@@ -0,0 +1,115 @@
+# 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!
+}
+```
+
+### Architecture Benefits
+
+- **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
+
+## Directory Structure
+
+```bash
+public/art/
+├─ maps/
+│ └─ example/
+│ ├─ map.art
+│ └─ legend.json
+│
+├─ materials/
+│ ├─ brick-wall.art
+│ └─ wooden-door.art
+│
+├─ sprites/
+├─ giant-rat.art
+└─ wolf.art
+```
+
+## 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.
+
+## materials/
+
+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.
+
+**Contents:**
+
+- `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
+
+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.
+
+## sprites/
+
+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.
+
+**Contents:**
+
+- `giant-rat.art` - ASCII sprite for giant rat creature
+- `wolf.art` - ASCII sprite for wolf creature
+
+Sprites are referenced in map legends via the `asset` property and can be combined with entity types to define interactive game objects.

package/dist/templates/base/public/art/asciitorium.art

@@ -0,0 +1,111 @@
+§ {"loop":true,"duration":120}
+                _ _ _             _                 
+  __ _ ___  ___(_|_) |_ ___  _ __(_)_   _ _ __ ___  
+ / _` / __|/ __| | | __/ _ \| '__| | | | | '_ ` _ \ 
+| (_| \__ \ (__| | | || (_) | |  | | |_| | | | | | |
+ \__,_|___/\___|_|_|\__\___/|_|  |_|\__,_|_| |_| |_|
+¶ {"duration":8000}
+                _ _              _                 
+  __ _ ___  ___(_| )| _ ___  _ __(_)_   _   _ __ .  
+ / _` / __|/ __| | | __/ _ \| '__| | | | | '_ ` _ \.
+| (_| \__ \ (__| | | || (_) | |  | | |_| | | | | | |
+ \__,_|___/\___|_|_|\__\___/|_|  |_|\__,_|_| |_| |_|
+¶ {"duration":1000}
+              .   _ * _             *     .        
+  __ _ ___  ___(_|_).|_   *  _ __(_)_   _   *  __  
+ / _` / __|/ _ .  |  __/  . \ '__| | | | '   `  \ .
+| (_| \__  (__| *|.| || (_) |  * | | |_|  *| | | │ .
+ \__,_|___/\__ ._|_|\__\  * /|_|   .|\__   |_| |_│  
+¶ {"duration":140}
+          *      _    *     .    *     .    *      
+  __   *      (_|_)   .  *   _ __   .     .    __   
+ /   `    __|  |    __/   * \ '__|     *      ` \   
+| *   * \__    | | || (_) |   .  |  *  *   |   | │  
+   .  .|___/   |_| \__\___/|_|   .    .  |_|  . |_│
+¶ {"duration":140}
+     .  *   .     _   *         .       .    .     
+  __    *  * (_|_).    .  *     _   *     .    __  
+ / _`  * __|   | __/  *   * \ '__|    .  *     _ \ 
+| (_| * \__    | || (_)  .     |  *   .   *  | | │ 
+   . ._|___/   |_| \__\  *     |_|  .   *   |_| |_│
+¶ {"duration":160}
+ .   *    .      _     *     .     *     .     .   
+    *    .  (_|_)    .   .   *    .    *   .        
+ /   `  * __|   __/  *    .    *  .  *    .     \  
+|  *  * \__    | (_)*   .  *      .   *   .  |   │ 
+    .  .|___/   |_|   *    .   *     .     .  |_|  
+¶ {"duration":140}
+     .    *        .       .   *    .         .    
+ .       .     .        *       .     *       .     
+    *        .      .        .     *       .        
+       .        *      .      .        .     *      
+          .        .        *     .        .        
+¶ {"duration":240}
+           .    *        .       .   *    .        
+      .       .     .        *       .     *        
+ .        *        .      .        .     *          
+    .         .        *      .      .        .     
+       *         .        .        *     .          
+¶ {"duration":240}
+                .    *        .       .   *        
+         .       .     .        *       .           
+    .         *        .      .        .            
+       .          .        *      .      .          
+  *         .         .        .        *           
+¶ {"duration":240}
+                                            
+          .        .   *      .       .            
+     .          *        .      .                  
+        .           .        *      .              
+   *         .          .        .                 
+¶ {"duration":240}
+                                            
+                                            
+                .        .   *       .             
+           .          *        .      .            
+      *         .          .        .              
+¶ {"duration":240}
+                                            
+                                            
+                                            
+                 .   *       .                    
+            *         .          .                 
+¶ {"duration":260}
+                                            
+                                            
+                                            
+                                            
+                 .     .                          
+¶ {"duration":280}
+                                            
+                                            
+                                            
+                                            
+                                            
+¶ {"duration":1000}
+
+
+
+
+                _ _ _             _                 
+¶ {"duration":140}
+
+
+
+
+                _ _ _             _                 
+  __ _ ___  ___(_|_) |_ ___  _ __(_)_   _ _ __ ___  
+¶ {"duration":140}
+
+
+
+                _ _ _             _                 
+  __ _ ___  ___(_|_) |_ ___  _ __(_)_   _ _ __ ___  
+ ╱ _` ╱ __|╱ __| | | __╱ _ ╲| '__| | | | | '_ ` _ ╲ 
+¶ {"duration":140}
+
+
+                _ _ _             _                 
+  __ _ ___  ___(_|_) |_ ___  _ __(_)_   _ _ __ ___  
+ / _` / __|/ __| | | __/ _ \| '__| | | | | '_ ` _ \ 
+| (_| \__ \ (__| | | || (_) | |  | | |_| | | | | | |