1 files changed, 474 insertions, 0 deletions
diff --git a/js/baba-yaga/scratch/docs/GAME-ENGINE-ARCHITECTURE.md b/js/baba-yaga/scratch/docs/GAME-ENGINE-ARCHITECTURE.md
new file mode 100644
index 0000000..fb9e726
--- /dev/null
+++ b/js/baba-yaga/scratch/docs/GAME-ENGINE-ARCHITECTURE.md
@@ -0,0 +1,474 @@
+# Baba Yaga Game Engine Architecture
+
+## Vision
+
+Create an integrated game development environment inspired by Pico-8, where Baba Yaga serves as the scripting language for creating 2D graphical games, text adventures, and visual novels. The system should be approachable for beginners while powerful enough for complex games.
+
+## Core Design Principles
+
+1. **Batteries Included**: Everything needed for game development in one package
+2. **Immediate Feedback**: Live coding with instant visual results
+3. **Constraint-Based Creativity**: Reasonable limits that encourage creative solutions
+4. **Cross-Genre Support**: Unified API that works for graphics, text, and hybrid games
+5. **Functional Game Logic**: Leverage Baba Yaga's functional nature for clean game state management
+
+## System Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Baba Yaga Game Engine                     │
+├─────────────────────────────────────────────────────────────┤
+│  Game Scripts (.baba files)                                │
+├─────────────────────────────────────────────────────────────┤
+│  Game Runtime API                                          │
+│  ├── Graphics API    ├── Audio API     ├── Input API      │
+│  ├── Text/UI API     ├── Storage API   ├── Scene API      │
+├─────────────────────────────────────────────────────────────┤
+│  Core Engine Systems                                       │
+│  ├── Renderer       ├── Audio System  ├── Input Manager   │
+│  ├── Asset Loader   ├── Save System   ├── Scene Manager   │
+├─────────────────────────────────────────────────────────────┤
+│  Platform Layer (Web/Desktop/Mobile)                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Game Runtime API Design
+
+### Core Game Loop
+
+```baba
+// Game entry point - called once at startup
+init : () -> GameState;
+
+// Main update loop - called every frame
+update : (state: GameState, input: Input, dt: Float) -> GameState;
+
+// Render function - called every frame after update
+draw : (state: GameState) -> Unit;
+```
+
+### Graphics API (`gfx` namespace)
+
+**Display System:**
+```baba
+// Display management
+gfx.width : Int;                    // Screen width (e.g., 320)
+gfx.height : Int;                   // Screen height (e.g., 240)
+gfx.clear : (color: Color) -> Unit; // Clear screen
+gfx.present : () -> Unit;           // Present frame (auto-called)
+
+// Coordinate system: (0,0) at top-left, (width-1, height-1) at bottom-right
+```
+
+**Drawing Primitives:**
+```baba
+// Basic shapes
+gfx.pixel : (x: Int, y: Int, color: Color) -> Unit;
+gfx.line : (x1: Int, y1: Int, x2: Int, y2: Int, color: Color) -> Unit;
+gfx.rect : (x: Int, y: Int, w: Int, h: Int, color: Color) -> Unit;
+gfx.rectFill : (x: Int, y: Int, w: Int, h: Int, color: Color) -> Unit;
+gfx.circle : (x: Int, y: Int, radius: Int, color: Color) -> Unit;
+gfx.circleFill : (x: Int, y: Int, radius: Int, color: Color) -> Unit;
+
+// Color system (16-color palette like Pico-8)
+gfx.colors : {
+  black: 0, darkBlue: 1, darkPurple: 2, darkGreen: 3,
+  brown: 4, darkGray: 5, lightGray: 6, white: 7,
+  red: 8, orange: 9, yellow: 10, green: 11,
+  blue: 12, indigo: 13, pink: 14, peach: 15
+};
+```
+
+**Sprite System:**
+```baba
+// Sprite management
+gfx.sprite : (id: Int, x: Int, y: Int) -> Unit;
+gfx.spriteFlip : (id: Int, x: Int, y: Int, flipX: Bool, flipY: Bool) -> Unit;
+gfx.spriteScale : (id: Int, x: Int, y: Int, scale: Float) -> Unit;
+
+// Sprite sheet: 128x128 pixels, 8x8 sprites = 16x16 grid of sprites
+gfx.spriteSize : Int; // 8 pixels
+gfx.spriteSheet : {width: 128, height: 128, sprites: 256};
+```
+
+**Text Rendering:**
+```baba
+gfx.text : (text: String, x: Int, y: Int, color: Color) -> Unit;
+gfx.textCentered : (text: String, x: Int, y: Int, color: Color) -> Unit;
+gfx.textBox : (text: String, x: Int, y: Int, w: Int, h: Int, color: Color) -> Unit;
+gfx.font : {width: 4, height: 6}; // Fixed-width bitmap font
+```
+
+### Audio API (`sfx` namespace)
+
+```baba
+// Sound effects (64 slots)
+sfx.play : (id: Int) -> Unit;
+sfx.stop : (id: Int) -> Unit;
+sfx.volume : (id: Int, volume: Float) -> Unit; // 0.0 to 1.0
+
+// Music (8 tracks)
+music.play : (track: Int) -> Unit;
+music.stop : () -> Unit;
+music.pause : () -> Unit;
+music.resume : () -> Unit;
+music.volume : (volume: Float) -> Unit;
+
+// Simple sound synthesis
+sfx.beep : (frequency: Float, duration: Float) -> Unit;
+sfx.noise : (duration: Float) -> Unit;
+```
+
+### Input API (`input` namespace)
+
+```baba
+// Button states (8 buttons like a gamepad)
+input.buttons : {
+  up: 0, down: 1, left: 2, right: 3,
+  a: 4, b: 5, start: 6, select: 7
+};
+
+// Input checking
+input.pressed : (button: Int) -> Bool;   // Just pressed this frame
+input.held : (button: Int) -> Bool;      // Held down
+input.released : (button: Int) -> Bool;  // Just released this frame
+
+// Mouse/touch (for visual novels and UI)
+input.mouse : {x: Int, y: Int, pressed: Bool, held: Bool, released: Bool};
+
+// Keyboard (for text adventures)
+input.key : (keyCode: String) -> Bool;
+input.textInput : () -> String; // Text entered this frame
+```
+
+### Text/UI API (`ui` namespace)
+
+**For Text Adventures & Visual Novels:**
+```baba
+// Text display system
+ui.textBuffer : [String]; // Scrolling text buffer
+ui.print : (text: String) -> Unit;
+ui.println : (text: String) -> Unit;
+ui.clear : () -> Unit;
+ui.scroll : (lines: Int) -> Unit;
+
+// Choice system for branching narratives
+ui.choice : (prompt: String, options: [String]) -> Result Int String;
+ui.input : (prompt: String) -> String;
+
+// Dialog system
+ui.dialog : {
+  show: (speaker: String, text: String) -> Unit,
+  hide: () -> Unit,
+  isShowing: Bool
+};
+
+// Menu system
+ui.menu : (title: String, options: [String], selected: Int) -> Int;
+```
+
+### Storage API (`save` namespace)
+
+```baba
+// Persistent storage (like cartridge data)
+save.set : (key: String, value: any) -> Unit;
+save.get : (key: String) -> Result any String;
+save.has : (key: String) -> Bool;
+save.remove : (key: String) -> Unit;
+save.clear : () -> Unit;
+
+// High scores, progress, settings
+save.highScore : (score: Int) -> Unit;
+save.getHighScore : () -> Int;
+save.checkpoint : (data: any) -> Unit;
+save.loadCheckpoint : () -> Result any String;
+```
+
+### Scene API (`scene` namespace)
+
+```baba
+// Scene management for complex games
+scene.current : String;
+scene.switch : (name: String) -> Unit;
+scene.push : (name: String) -> Unit;  // For menus/overlays
+scene.pop : () -> Unit;
+
+// Scene registration
+scene.register : (name: String, init: () -> State, update: UpdateFn, draw: DrawFn) -> Unit;
+```
+
+## Game Types and Patterns
+
+### 2D Action/Platformer Games
+
+```baba
+// Example: Simple platformer
+GameState : {
+  player: {x: Float, y: Float, vx: Float, vy: Float},
+  enemies: [Enemy],
+  level: Level,
+  score: Int
+};
+
+init : () -> GameState ->
+  {
+    player: {x: 160, y: 120, vx: 0, vy: 0},
+    enemies: [],
+    level: loadLevel 1,
+    score: 0
+  };
+
+update : state input dt ->
+  with (
+    // Handle input
+    newVx : when (input.held input.buttons.left) is
+      true then -100
+      _ then when (input.held input.buttons.right) is
+        true then 100
+        _ then state.player.vx * 0.8; // Friction
+    
+    // Update player
+    newPlayer : updatePlayer state.player newVx dt;
+    
+    // Update enemies
+    newEnemies : map (enemy -> updateEnemy enemy dt) state.enemies;
+  ) ->
+    set state "player" newPlayer
+    |> set "enemies" newEnemies;
+
+draw : state ->
+  gfx.clear gfx.colors.darkBlue;
+  drawLevel state.level;
+  drawPlayer state.player;
+  map drawEnemy state.enemies;
+  gfx.text ("Score: " .. (str.concat "" state.score)) 4 4 gfx.colors.white;
+```
+
+### Text Adventure Games
+
+```baba
+// Example: Text adventure
+AdventureState : {
+  currentRoom: String,
+  inventory: [String],
+  gameText: [String],
+  gameOver: Bool
+};
+
+init : () -> AdventureState ->
+  {
+    currentRoom: "start",
+    inventory: [],
+    gameText: ["Welcome to the Adventure!", "You are in a dark room."],
+    gameOver: false
+  };
+
+update : state input dt ->
+  when (input.textInput != "") is
+    false then state
+    true then processCommand state (input.textInput);
+
+draw : state ->
+  gfx.clear gfx.colors.black;
+  drawTextBuffer state.gameText;
+  ui.print "> ";
+
+processCommand : state command ->
+  when (text.words command) is
+    ["go", direction] then movePlayer state direction
+    ["take", item] then takeItem state item
+    ["use", item] then useItem state item
+    ["inventory"] then showInventory state
+    _ then addText state "I don't understand that command.";
+```
+
+### Visual Novel Games
+
+```baba
+// Example: Visual novel
+NovelState : {
+  currentScene: String,
+  characterSprites: Table,
+  background: String,
+  textBox: {visible: Bool, speaker: String, text: String},
+  choices: [String],
+  flags: Table // Story flags
+};
+
+init : () -> NovelState ->
+  {
+    currentScene: "intro",
+    characterSprites: {},
+    background: "room",
+    textBox: {visible: false, speaker: "", text: ""},
+    choices: [],
+    flags: {}
+  };
+
+update : state input dt ->
+  when state.choices is
+    [] then // Regular dialog
+      when (input.pressed input.buttons.a) is
+        true then advanceDialog state
+        _ then state
+    _ then // Choice selection
+      when (input.pressed input.buttons.a) is
+        true then selectChoice state
+        _ then navigateChoices state input;
+
+draw : state ->
+  drawBackground state.background;
+  drawCharacterSprites state.characterSprites;
+  when state.textBox.visible is
+    true then drawTextBox state.textBox
+    _ then {};
+  when (length state.choices > 0) is
+    true then drawChoices state.choices
+    _ then {};
+```
+
+## Asset Management
+
+### File Structure
+```
+game/
+├── main.baba           # Entry point
+├── sprites.png         # 128x128 sprite sheet
+├── sounds/             # Audio files
+│   ├── sfx_001.wav
+│   └── music_001.wav
+├── scenes/             # Scene scripts
+│   ├── intro.baba
+│   └── gameplay.baba
+└── data/               # Game data
+    ├── levels.json
+    └── dialog.json
+```
+
+### Asset Loading
+```baba
+// Automatic asset loading based on file structure
+assets.sprites : SpriteSheet;  // sprites.png
+assets.sounds : [Sound];       // sounds/*.wav
+assets.music : [Music];        // sounds/music_*.wav
+assets.data : Table;           // data/*.json parsed as tables
+```
+
+## Development Tools Integration
+
+### Live Coding
+- **Hot Reload**: Changes to .baba files reload game state
+- **REPL Integration**: Debug console accessible during gameplay
+- **State Inspector**: View and modify game state in real-time
+
+### Built-in Editors
+- **Sprite Editor**: Pixel art editor for the 128x128 sprite sheet
+- **Sound Editor**: Simple sound effect generator and sequencer
+- **Map Editor**: Tile-based level editor for 2D games
+- **Dialog Editor**: Visual dialog tree editor for visual novels
+
+### Export and Sharing
+- **Web Export**: Single HTML file with embedded assets
+- **Standalone Export**: Desktop executables
+- **Cartridge Format**: .baba-cart files containing code and assets
+- **Online Sharing**: Upload and share games on web platform
+
+## Performance Constraints
+
+Following Pico-8's philosophy of creative constraints:
+
+### Technical Limits
+- **Display**: 320x240 pixels (or 640x480 for high-DPI)
+- **Colors**: 16-color fixed palette
+- **Sprites**: 256 sprites, 8x8 pixels each
+- **Code Size**: ~32KB of Baba Yaga source code
+- **Audio**: 64 sound effects, 8 music tracks
+- **Save Data**: 1KB persistent storage
+
+### Performance Targets
+- **60 FPS**: Smooth gameplay on modest hardware
+- **Low Latency**: <16ms input response time
+- **Fast Startup**: <2 seconds from launch to gameplay
+
+## Example Game Templates
+
+### Template 1: Arcade Game
+```baba
+// Minimal arcade game template
+init : () -> {score: 0, gameOver: false};
+
+update : state input dt ->
+  when state.gameOver is
+    true then 
+      when (input.pressed input.buttons.start) is
+        true then init
+        _ then state
+    _ then updateGameplay state input dt;
+
+draw : state ->
+  gfx.clear gfx.colors.black;
+  when state.gameOver is
+    true then drawGameOver state.score
+    _ then drawGameplay state;
+```
+
+### Template 2: Text Adventure
+```baba
+// Text adventure template with room system
+rooms : {
+  start: {
+    description: "A dark room with exits north and east.",
+    exits: {north: "hallway", east: "kitchen"},
+    items: ["flashlight"]
+  }
+  // ... more rooms
+};
+
+processCommand : state command ->
+  when (parseCommand command) is
+    Move direction then moveToRoom state direction
+    Take item then takeItem state item
+    _ then unknownCommand state;
+```
+
+### Template 3: Visual Novel
+```baba
+// Visual novel template with scene system
+scenes : {
+  intro: [
+    {type: "background", image: "school"},
+    {type: "character", name: "alice", position: "left"},
+    {type: "dialog", speaker: "Alice", text: "Hello there!"},
+    {type: "choice", options: ["Hello!", "Who are you?"]}
+  ]
+  // ... more scenes
+};
+
+playScene : state sceneData ->
+  reduce executeSceneAction state sceneData;
+```
+
+## Integration with Existing Baba Yaga Features
+
+### Leveraging Language Features
+- **Pattern Matching**: Perfect for game state transitions and input handling
+- **Immutability**: Clean game state management without side effects
+- **Result Type**: Robust error handling for asset loading and save/load
+- **Higher-Order Functions**: Flexible entity systems and behavior trees
+- **Debug Tools**: Built-in debugging for game development
+
+### Extended Standard Library
+- **Game Math**: Vector operations, collision detection, easing functions
+- **Random Enhanced**: Seeded random for reproducible gameplay
+- **Collections**: Spatial data structures for game entities
+- **Validation**: Input validation for save data and user input
+
+## Next Steps
+
+1. **Prototype Core Systems**: Start with basic graphics and input
+2. **Build Example Games**: Create reference implementations for each genre
+3. **Developer Tools**: Integrated sprite and sound editors
+4. **Community Platform**: Sharing and collaboration features
+5. **Documentation**: Comprehensive tutorials and API reference
+
+This architecture provides a solid foundation for a Baba Yaga-powered game development environment that can handle everything from simple arcade games to complex visual novels, all while maintaining the functional programming principles that make Baba Yaga unique.