blockyserver/CLAUDE.md

CLAUDE.md

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

Build & Run Commands

# 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