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

# 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:

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:

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

# 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.

lovr ./

Status

All phases complete:

• ✅ MVP setup
• ✅ Core systems
• ✅ Polish
• ✅ Neverending loop

See BUILD_NOTES.md for implementation details.

License

MIT License