initial commit

2026-07-23 21:23:01 +00:00
commit c6c309f941
25 changed files with 6825 additions and 0 deletions
@@ -0,0 +1,268 @@
+# Cat Haven - README
+
+## Testing
+
+Cat Haven includes a comprehensive test suite using a custom testing framework with TAP-style output and XML report generation.
+
+### Test Structure
+
+```
+test/
+├── test_helper.lua      # LOVR mocks and test utilities
+├── run_tests.lua        # Test runner script
+├── spec/                # Unit tests (per module)
+│   ├── core_spec.lua
+│   ├── json_spec.lua
+│   ├── voxel_spec.lua
+│   ├── cat_spec.lua
+│   ├── house_spec.lua
+│   ├── ui_spec.lua
+│   └── audio_spec.lua
+├── integration/         # Integration tests
+│   └── game_flow_spec.lua
+└── e2e/                 # End-to-end tests
+    └── edge_cases_spec.lua
+```
+
+### Test Coverage
+
+#### Unit Tests (spec/)
+- **JSON Module**: Encoding/decoding, edge cases, round-trip validation
+- **Voxel Module**: Texture generation, mesh creation, rendering, raycast
+- **Cat Module**: Creation, AI behavior, needs, serialization, animation
+- **House Module**: Furniture placement, collision detection, upgrades
+- **UI Module**: HUD rendering, interaction, state management
+- **Audio Module**: Sound generation, playback, properties
+- **Core Module**: Game state, spawn, save/load, happiness calculation
+
+#### Integration Tests (integration/)
+- Full game flow initialization
+- Module interactions
+- Save/load round-trip
+- Cat-house interactions
+- UI-cat interactions
+- Voxel-cat interactions
+- JSON serialization round-trips
+
+#### End-to-End Tests (e2e/)
+- Empty cat list handling
+- Zero distance edge cases
+- Nil value handling
+- Invalid JSON handling
+- Max capacity limits
+- Furniture at bounds
+- Low happiness departures
+- Furniture upgrades
+- Personality compatibility
+- Audio generation
+- Serialization edge cases
+- Stress tests (many cats, many furniture)
+- Complete game session simulation
+
+### Running Tests
+
+```bash
+# Run all tests
+lua test/run_tests.lua
+
+# Run tests with LuaJIT (faster)
+luajit test/run_tests.lua
+
+# Run specific test file
+lua test/spec/json_spec.lua
+```
+
+### Test Output
+
+Tests output TAP (Test Anything Protocol) format to stdout and generate an XML report:
+
+```
+cat_game/
+├── test-report.xml      # JUnit-compatible XML report
+```
+
+The XML report can be used with CI/CD tools like Jenkins, GitHub Actions, etc.
+
+### Writing Tests
+
+Use the `describe` and `it` functions for test organization:
+
+```lua
+describe('Module Name', function()
+  it('should do something', function()
+    -- Test code here
+    assert.equals(expected, actual)
+    assert_truthy(value)
+    assert_falsy(value)
+  end)
+end)
+```
+
+### Mocking LOVR
+
+The test helper provides a complete LOVR mock:
+
+```lua
+local helper = require('test.test_helper')
+local lovr = helper.lovr
+
+-- Use lovr in tests
+lovr.graphics.box('fill', 0, 0, 0, 1, 1, 1, { 1, 0, 0 })
+```
+
+### Assertions
+
+- `assert.equals(a, b)` - Check equality
+- `assert_truthy(val)` - Check truthiness
+- `assert_falsy(val)` - Check falsiness
+- `assert_matches(str, pattern)` - Check regex match
+- `assertDeepEqual(a, b)` - Deep table comparison
+
+## Project Overview
+
+Cat Haven is a cozy voxel-styled management game for LOVR (Lua Open Virtual Reality). Players manage a virtual cat shelter, placing furniture, welcoming new cats, and maintaining their happiness.
+
+## Features
+
+### Core Gameplay
+- **Cat Management**: Welcome new cats with 5 unique personalities (Lone Wolf, Social Butterfly, Playful Clown, Greedy Eater, Lazy Sleeper)
+- **Furniture System**: Place and upgrade furniture (Cat Tree, Scratching Post, Cozy Bed, Window Seat, Food Bowl)
+- **Happiness System**: Monitor cat happiness based on comfort, social needs, hunger, and fun
+- **Save/Load**: JSON-based save system to preserve game state
+
+### Technical Features
+- **Voxel Rendering**: Procedural textures for all game objects
+- **Procedural Audio**: Generated sounds for purring, meowing, ambient room noise
+- **Grid-based Placement**: Collision detection for furniture placement
+- **AI Behavior**: Cats seek comfort, social interaction, and entertainment
+- **Headless Environment**: Designed for VR but functional in 2D mode
+
+## Project Structure
+
+```
+cat_game/
+├── main.lua              # LOVR entry point
+├── README.md             # This file
+├── BUILD_NOTES.md        # Implementation status
+├── src/
+│   ├── core.lua          # Game state, configuration, save/load
+│   ├── json.lua          # Custom JSON encoder/decoder
+│   ├── voxel/init.lua    # Voxel rendering, procedural textures
+│   ├── cat/init.lua      # Cat AI, behavior, state machine
+│   ├── house/init.lua    # Grid system, furniture placement
+│   ├── ui/init.lua       # HUD, inventory, cat log
+│   └── audio/init.lua    # Procedural audio generation
+├── test/                 # Test suite
+│   ├── test_helper.lua   # LOVR mocks and utilities
+│   ├── run_tests.lua     # Test runner
+│   ├── spec/             # Unit tests
+│   ├── integration/      # Integration tests
+│   └── e2e/              # End-to-end tests
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+lua test/run_tests.lua
+
+# Run tests with LuaJIT (faster)
+luajit test/run_tests.lua
+```
+
+### Test Coverage
+
+- **JSON Encoding/Decoding**: All data types, edge cases, round-trip validation
+- **Cat Creation**: All 5 personalities, AI behavior, serialization
+- **Furniture Placement**: Grid system, collision detection, upgrades
+- **Happiness Calculation**: All weights, edge cases, empty lists
+- **Save/Load Round-trip**: Complete state preservation
+- **UI Rendering**: HUD, inventory, cat log, interaction
+- **Audio Generation**: Purr, meow, click, ambient sounds
+
+### Test Structure
+
+```
+test/
+├── test_helper.lua      # LOVR mocks and utilities
+├── run_tests.lua        # Test runner
+├── spec/                # Unit tests (per module)
+│   ├── core_spec.lua
+│   ├── json_spec.lua
+│   ├── voxel_spec.lua
+│   ├── cat_spec.lua
+│   ├── house_spec.lua
+│   ├── ui_spec.lua
+│   └── audio_spec.lua
+├── integration/         # Integration tests
+│   └── game_flow_spec.lua
+└── e2e/                 # End-to-end tests
+    └── edge_cases_spec.lua
+```
+
+## Controls
+
+- **RThumb + S**: Save game
+- **RThumb + L**: Load game
+- **ESC**: Pause game
+- **Mouse**: Interact with UI elements
+
+## Game Mechanics
+
+### Cat Spawn
+- New cats arrive every 30 seconds (if under max capacity)
+- Each cat has a random personality affecting behavior and compatibility
+
+### Happiness Formula
+```
+Total Happiness = 
+  (Avg Comfort × 0.3) +
+  (Avg Social × 0.2) +
+  (Avg Hunger × 0.2) +
+  (Avg Fun × 0.3)
+```
+
+### Cat Departure
+Cats leave automatically when:
+- Comfort drops below 10%
+- Hunger drops below 10%
+
+### Furniture Upgrades
+- Furniture can be upgraded 3 levels
+- Each upgrade increases happiness contribution by 80%
+
+## Technical Details
+
+### Dependencies
+- LOVR 2023 (v1.4)
+- Lua 5.4
+
+### Audio Format
+Audio is generated procedurally using `lovr.audio.newSource()` with 'static' buffer type.
+
+### Texture Generation
+Textures are created at runtime using `lovr.graphics.newImage()` with RGBA8 format.
+
+## Building
+
+The game runs directly in LOVR. No compilation required.
+
+```bash
+lovr ./
+```
+
+## Status
+
+All phases complete:
+- ✅ MVP setup
+- ✅ Core systems
+- ✅ Polish
+- ✅ Neverending loop
+
+See BUILD_NOTES.md for implementation details.
+
+## License
+
+MIT License