79 lines
2.7 KiB
Markdown
79 lines
2.7 KiB
Markdown
# 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`
|