cat-haven/README.md

# 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