1 files changed, 321 insertions, 0 deletions
diff --git a/template/README.md b/template/README.md
new file mode 100644
index 0000000..e46a3cf
--- /dev/null
+++ b/template/README.md
@@ -0,0 +1,321 @@
+# ReiLua-Enhanced Game Template
+
+A complete game template for rapid development with ReiLua-Enhanced.
+
+## 📁 Structure
+
+```
+template/
+├── main.lua              # Entry point
+├── lib/                  # Core libraries
+│   ├── classic.lua       # OOP class system
+│   ├── gamestate.lua     # State management
+│   └── animation.lua     # Sprite animation system
+├── states/               # Game states
+│   ├── menu.lua          # Menu screen
+│   └── game.lua          # Main gameplay
+└── assets/               # Game assets (images, sounds, etc.)
+```
+
+## 🚀 Quick Start
+
+### Development
+
+1. **Copy template to your game folder:**
+   ```bash
+   xcopy /E /I template MyGame
+   cd MyGame
+   ```
+
+2. **Run your game:**
+   ```bash
+   path\to\ReiLua.exe --log --no-logo
+   ```
+
+3. **Start coding!**
+   - Edit `states/menu.lua` for your menu
+   - Edit `states/game.lua` for gameplay
+   - Add assets to `assets/` folder
+
+### Release Build
+
+1. **Copy files to build directory:**
+   ```bash
+   cd ReiLua-Enhanced\build
+   xcopy /E /I ..\MyGame\*.lua .
+   xcopy /E /I ..\MyGame\lib lib
+   xcopy /E /I ..\MyGame\states states
+   mkdir assets
+   xcopy /E /I ..\MyGame\assets assets
+   ```
+
+2. **Build release:**
+   ```bash
+   cd ..
+   scripts\build_release.bat
+   ```
+
+3. **Your game is ready!**
+   - `build/ReiLua.exe` (or your custom name)
+   - Everything embedded in one executable
+
+## 📚 Libraries Included
+
+### Classic (OOP)
+Object-oriented class system by rxi.
+
+```lua
+local Object = require("lib.classic")
+local Player = Object:extend()
+
+function Player:new(x, y)
+  self.x = x
+  self.y = y
+end
+
+function Player:update(dt)
+  -- Update logic
+end
+
+local player = Player(100, 100)
+```
+
+### GameState
+State management system inspired by hump.gamestate.
+
+```lua
+local GameState = require("lib.gamestate")
+local menu = require("states.menu")
+
+-- Register callbacks
+GameState.registerEvents()
+
+-- Switch state
+GameState.switch(menu)
+
+-- Push state (with return)
+GameState.push(pauseMenu)
+GameState.pop()  -- Returns to previous state
+```
+
+**State Callbacks:**
+- `state:enter(previous, ...)` - Entering state
+- `state:leave()` - Leaving state
+- `state:resume(previous, ...)` - Returning via pop()
+- `state:update(dt)` - Frame update
+- `state:draw()` - Rendering
+- `state:event(event)` - Input events
+
+### Animation
+Sprite sheet animation system.
+
+```lua
+local Animation = require("lib.animation")
+
+-- Load texture
+local playerTexture = RL.LoadTexture("assets/player.png")
+
+-- Create animation (32x32 frame size)
+local anim = Animation.new(playerTexture, 32, 32, {
+  idle = {frames = {1, 2, 3, 4}, fps = 8, loop = true},
+  walk = {frames = {5, 6, 7, 8, 9, 10}, fps = 12, loop = true},
+  jump = {frames = {11, 12, 13}, fps = 10, loop = false}
+})
+
+-- Play animation
+anim:play("idle")
+
+-- In update loop
+anim:update(dt)
+
+-- In draw loop
+anim:draw(x, y)
+
+-- Or simple draw (no rotation/scale)
+anim:drawSimple(x, y)
+
+-- Advanced features
+anim:setFlip(true, false)  -- Flip horizontally
+anim:setScale(2, 2)        -- Scale 2x
+anim:setTint(RL.RED)       -- Color tint
+anim:pause()               -- Pause animation
+anim:resume()              -- Resume
+anim:stop()                -- Stop and reset
+```
+
+## 🎮 Example States
+
+### Menu State (states/menu.lua)
+- Keyboard navigation (Up/Down)
+- Start game / Options / Exit
+- Clean UI rendering
+
+### Game State (states/game.lua)
+- Player movement (WASD/Arrows)
+- Pause menu (ESC/P)
+- Animation integration example
+- Basic game loop
+
+## 🎨 Adding Assets
+
+### Sprite Sheets
+Place sprite sheets in `assets/` folder:
+
+```
+assets/
+├── player.png      # Player sprite sheet (grid-based)
+├── enemy.png       # Enemy sprites
+├── explosion.png   # Explosion animation
+└── background.png  # Background image
+```
+
+**Sprite Sheet Format:**
+- Grid-based (equal-sized frames)
+- Frames read left-to-right, top-to-bottom
+- Example: 32x32 frames in 256x256 texture = 8x8 grid (64 frames)
+
+### Sounds & Music
+```lua
+-- In state:enter()
+self.music = RL.LoadMusicStream("assets/music.ogg")
+self.jumpSound = RL.LoadSound("assets/jump.wav")
+
+-- In state:update()
+RL.UpdateMusicStream(self.music)
+
+-- Play sound
+RL.PlaySound(self.jumpSound)
+```
+
+## 🔧 Configuration
+
+### Window Settings (main.lua)
+```lua
+local GAME_TITLE = "My Awesome Game"
+local WINDOW_WIDTH = 1280
+local WINDOW_HEIGHT = 720
+local TARGET_FPS = 60
+local START_FULLSCREEN = false  -- Start in fullscreen?
+```
+
+For complete window configuration (fullscreen, resizable, etc.), see [WINDOW_CONFIG.md](WINDOW_CONFIG.md).
+
+### Exit Key Behavior
+By default, the template disables ESC as an exit key so you can use it for pause menus:
+```lua
+RL.SetExitKey(0)  -- 0 = No exit key
+```
+
+To change this behavior, see [COMMON_ISSUES.md](COMMON_ISSUES.md#esc-key-closes-the-game).
+
+### Global Hotkeys
+- **F1 / F11** - Toggle fullscreen
+- **ESC** - Pause game (in game state)
+
+## 📖 State Management Patterns
+
+### Simple State Switch
+```lua
+-- From menu to game
+GameState.switch(gameState)
+```
+
+### State Stack (Pause Menu)
+```lua
+-- Push pause menu (game continues in background)
+GameState.push(pauseMenu)
+
+-- Return to game
+GameState.pop()
+```
+
+### Passing Data Between States
+```lua
+-- Pass score to game over screen
+GameState.switch(gameOverState, score, highScore)
+
+-- In game over state:
+function gameOverState:enter(previous, score, highScore)
+  self.score = score
+  self.highScore = highScore
+end
+```
+
+## 🎯 Best Practices
+
+### Performance
+- Load assets in `state:enter()`, not `update()`
+- Unload assets in `state:leave()`
+- Use object pooling for bullets/particles
+- Profile with `--log` flag
+
+### Organization
+- One file per state
+- Keep states small and focused
+- Use OOP for game entities (Player, Enemy, etc.)
+- Separate rendering from logic
+
+### Asset Loading
+```lua
+function state:enter()
+  -- Show loading if needed
+  local assets = {"player.png", "enemy.png", "music.ogg"}
+  RL.BeginAssetLoading(#assets)
+  
+  for _, asset in ipairs(assets) do
+    RL.UpdateAssetLoading(asset)
+    -- Load asset...
+  end
+  
+  RL.EndAssetLoading()
+end
+```
+
+## 🐛 Debugging
+
+### Development Mode
+```bash
+ReiLua.exe --log --no-logo
+```
+- Shows console output
+- Skips splash screens
+- Fast iteration
+
+### Common Issues
+
+**Animation not showing:**
+- Check texture loaded: `if not texture then print("Failed!") end`
+- Verify frame size matches sprite sheet
+- Check animation is playing: `anim:play("idle")`
+
+**State not switching:**
+- Verify `GameState.registerEvents()` called in `RL.init()`
+- Check state has required functions (`:update()`, `:draw()`)
+- Use `print()` in `:enter()` to verify state switch
+
+**Assets not loading:**
+- Use relative paths: `"assets/player.png"` not `"C:/..."`
+- Check file exists with `RL.FileExists()`
+- View console with `--log` flag
+
+## 📦 Building for Release
+
+See main ReiLua-Enhanced documentation:
+- [EMBEDDING.md](../docs/EMBEDDING.md) - Embedding guide
+- [BUILD_SCRIPTS.md](../docs/BUILD_SCRIPTS.md) - Build automation
+- [CUSTOMIZATION.md](../docs/CUSTOMIZATION.md) - Branding/icons
+
+## 📄 License
+
+- **classic.lua** - MIT License (rxi)
+- **gamestate.lua** - Inspired by hump (MIT)
+- **animation.lua** - MIT License
+- **Template** - Free to use for any project
+
+## 🎮 Ready to Make Games!
+
+This template gives you everything needed to start building games immediately. Focus on gameplay, not boilerplate!
+
+For more examples and documentation, see the main ReiLua-Enhanced repository.
+
+Happy game jamming! 🚀