# CLAUDE.md

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

## Build & Run Commands

```bash
# Build
go build -o blockyserver.exe .

# Run (default port 8080)
./blockyserver.exe
./blockyserver.exe -port 3000

# Dependencies
go mod tidy
```

## Architecture

BlockyServer is an HTTP API for rendering Hytale character models. It wraps the `github.com/hytale-tools/blockymodel-merger` library to provide web endpoints.

### Request Flow

```
HTTP Request → api.Handlers → service.MergeService → blockymodel-merger pkg
                                    ↓
                              render.RenderPNG/GIF/MP4 (for image/video endpoints)
                                    ↓
                              HTTP Response (GLB/PNG/GIF/MP4)
```

### Package Structure

- **main.go** - Entry point, flag parsing, server startup
- **internal/api/** - HTTP layer (chi router, handlers, OpenAPI spec)
- **internal/service/** - Business logic wrapping blockymodel-merger
- **internal/render/** - Software 3D rendering using fauxgl (GLB→PNG/GIF)

### Key Dependencies

- `github.com/hytale-tools/blockymodel-merger` - Core model merging, texture atlas, GLB export
- `github.com/fogleman/fauxgl` - Software 3D renderer for PNG/GIF output
- `github.com/go-chi/chi/v5` - HTTP router

### Runtime Data

Server requires these directories at runtime (relative to working directory):
- `assets/` - Character models (.blockymodel), textures
- `data/` - JSON registry files (accessories, colors, gradients)

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `BLOCKY_DISABLE_GLB` | `false` | Disable `/render/glb` endpoint (returns 403) |
| `BLOCKY_DISABLE_PNG` | `false` | Disable `/render/png` endpoint (returns 403) |
| `BLOCKY_DISABLE_GIF` | `false` | Disable `/render/gif` endpoint (returns 403) |
| `BLOCKY_DISABLE_MP4` | `false` | Disable `/render/mp4` endpoint (returns 403) |

Set to `true`, `1`, or `yes` to disable an endpoint.

### API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/render/glb` | POST | Character JSON → GLB binary |
| `/render/png` | POST | Character JSON + options → PNG image |
| `/render/gif` | POST | Character JSON + options → Animated GIF |
| `/render/mp4` | POST | Character JSON + options → MP4 video (requires FFmpeg) |
| `/docs` | GET | Swagger UI |
| `/openapi.json` | GET | OpenAPI spec |
| `/health` | GET | Health check |

### Character JSON Format

Accessory format: `"AccessoryId.Color.Variant"` (e.g., `"Scavenger_Hair.PitchBlack"`)

Key fields: `bodyCharacteristic`, `haircut`, `eyes`, `pants`, `undertop`, `overtop`, `shoes`