# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a LÖVE2D game development playground using Fennel (a Lisp dialect that compiles to Lua). The repository contains multiple game/project experiments:

- **hello_world**: Basic LÖVE2D + Fennel template with REPL support
- **hello_world_lua**: Basic LÖVE2D in pure Lua (reference implementation)
- **one_line**: A pixel drawing application demonstrating canvas manipulation
- **two_player_cleaning_game**: Two-player game (primary focus for development)

## Key Architecture

### Fennel + LÖVE2D Setup

Fennel is a Lisp-like language that compiles to Lua at runtime. Each project directory shares common bootstrap files via symlinks:

- **fennel-1.5.3.lua** (root): The Fennel compiler itself
- **fennel_bootstrap.lua** (root): Sets up Fennel module loading and compiles `.fnl` files on-the-fly

Each project directory contains:
- **main.fnl**: The Fennel source code (user-editable)
- **main.lua** → symlink to `../fennel_bootstrap.lua`: Entry point that Lua/LÖVE2D loads
- **fennel.lua** → symlink to `../fennel-1.5.3.lua`: Fennel compiler reference

### How It Works

1. LÖVE2D loads `main.lua` (the bootstrap file)
2. Bootstrap loads the Fennel compiler and sets up a custom module loader
3. Module loader intercepts `require("main.fnl")` and compiles it via Fennel at runtime
4. Compiled Fennel code executes with full LÖVE2D API access

### LÖVE2D Lifecycle

Games define lifecycle callbacks (all optional):
- **love.load()**: Called once at startup
- **love.update()**: Called every frame (~60fps by default)
- **love.draw()**: Called every frame after update, render graphics here
- **love.keypressed(key)**: Keyboard input handler
- **love.handlers.stdin(line)**: REPL input for live evaluation (used in hello_world template)

## Development Workflow

### Running a Game

```bash
love ./two_player_cleaning_game
```

LÖVE2D must be installed and in your PATH. See [Getting Started](https://love2d.org/wiki/Getting_Started) for installation.

### Live Coding / REPL

The hello_world template includes stdin REPL support. While a game is running:
- Type Fennel code at the terminal
- Code is evaluated via `fennel.eval()` and results printed

To enable in other projects, add this to `love.load()`:

```fennel
(: (love.thread.newThread "require('love.event')
while 1 do love.event.push('stdin', io.read('*line')) end") :start)

(fn love.handlers.stdin [line]
  (let [(ok val) (pcall fennel.eval line)]
    (print (if ok (fennel.view val) val))))
```

## Fennel Language Basics

### Syntax Patterns

```fennel
; Variables
(local name "value")
(var counter 0)

; Functions
(fn my-func [arg1 arg2]
  (+ arg1 arg2))

; Tables/Objects
(local person {
  :name "Alice"
  :age 30
  :greet (fn [self] (print (.. self.name " says hello")))
})

; Common control flow
(when condition
  (do-something))

(if condition
  (then-branch)
  (else-branch))

(match value
  "a" (handle-a)
  "b" (handle-b))

; Iteration
(each [k v (pairs table)]
  (print k v))

(for [i 1 10]
  (print i))
```

### Interop with Lua

Call Lua functions naturally:

```fennel
(love.graphics.setColor 1 0 0) ; red
(love.window.getMode)          ; returns width, height, flags table
```

Access nested Lua objects with colon `:` syntax:

```fennel
(: canvas-obj :setFilter "nearest" "nearest")  ; equivalent to canvas_obj:setFilter(...)
```

## Project-Specific Notes

### two_player_cleaning_game

Currently uses the hello_world template structure. Development focus:
- Extend main.fnl with game logic (player movement, cleanup mechanics, etc.)
- Reference one_line/main.fnl for canvas/graphics patterns if needed
- Use LÖVE2D physics (love.physics) or collision detection as needed

### Symlink Pattern

Do **not** modify symlinked files (main.lua, fennel.lua) — modify main.fnl instead. If adding new modules, create them as separate .fnl files in the project directory.

## Common Development Tasks

### Adding a new module/file

1. Create `my_module.fnl` in the project directory
2. Require it: `(local my-module (require "my_module"))`
3. The bootstrap module loader will auto-compile it

### Debugging

- Use `(print (fennel.view value))` to inspect tables and complex values
- stdin REPL (hello_world template) allows live evaluation for quick tests
- LÖVE2D console output is visible in the terminal where you ran `love`

### Working with Graphics

LÖVE2D graphics API examples:

```fennel
(love.graphics.setColor 1 0 0)               ; set color to red
(love.graphics.rectangle "fill" x y w h)    ; draw filled rectangle
(love.graphics.circle "line" x y radius)    ; draw circle outline
(love.graphics.print text x y)               ; draw text
(love.graphics.draw drawable x y)           ; draw canvas/image
```

## References

- **LÖVE2D API**: https://love2d.org/wiki/Main_Page
- **Fennel Language**: https://fennel-lang.org/
- **Fennel Plugin**: The compiler is shipped in this repo; no external install needed beyond LÖVE2D