ark-infographic-worker

This codebase was entirely generated by Claude (Anthropic). No human authorship is claimed over the generated code.

A Cloudflare Worker that serves ARK: Survival Ascended / Evolved creature stat infographics as SVG or PNG images. Thin HTTP wrapper around ark-infographic-ts.

Architecture

POST /api/infographic
  → Validate request
  → Look up species metadata (bundled)
  → Check Cloudflare cache (SHA-256 of request body)
  → Fetch base.png + mask.png from R2
  → Colorize sprite + render infographic (via ark-infographic-ts)
  → Cache result (24h TTL)
  → Return SVG or PNG

Bundled at build time: species metadata (448 species), color table (126 colors), Arial fonts, resvg WASM binary.

Fetched at runtime: creature sprites from R2 (one base + one mask PNG per species).

API

POST /api/infographic

Generates a creature infographic.

Request body:

{
  "creature": {
    "speciesName": "Rex",
    "levelsWild": [40, 30, 25, 20, 35, 0, 0, 30, 45, 0, 0, 0],
    "levelsDom": [10, 5, 0, 0, 8, 0, 0, 5, 12, 0, 0, 0],
    "sex": 1,
    "colors": [14, 0, 28, 0, 0, 43],
    "tamingEffectiveness": 0.95,
    "creatureName": "Rex-012A",
    "isBred": false,
    "isNeutered": false,
    "isMutagenApplied": false,
    "imprintingBonus": 0,
    "mutations": 0,
    "generation": 0,
    "levelsMutated": null
  },
  "game": "ASA",
  "options": {
    "format": "png"
  }
}

Field	Required	Description
creature.speciesName	Yes	Must match a known species name
creature.levelsWild	Yes	12-element array of wild stat levels
creature.levelsDom	Yes	12-element array of domesticated stat levels
creature.sex	No	0 = Unknown, 1 = Male, 2 = Female
creature.colors	No	6 ARK color region IDs (0 = no color)
creature.tamingEffectiveness	No	0.0–1.0, -1 if unknown
creature.creatureName	No	Display name on the infographic
creature.levelsMutated	No	12-element array or null
creature.isBred	No	Default false
creature.isNeutered	No	Default false
creature.isMutagenApplied	No	Default false
creature.imprintingBonus	No	0.0–1.0, default 0
creature.mutations	No	Mutation count, default 0
creature.generation	No	Generation number, default 0
game	No	"ASA" or "ASE", default "ASA"
options.format	No	"svg" or "png", default "svg"
options.*	No	Any InfoGraphicConfig field (e.g., height, foreColor, backColor)

Response: image/svg+xml or image/png with Cache-Control: public, max-age=86400.

Errors: 400 JSON { "error": "..." } for validation failures. 404 if species sprites not found in R2.

GET /api/species

Returns all supported species names.

Response: 200 JSON array of strings.

GET /api/health

Response: 200 OK

Prerequisites

• Node.js 18+
• Wrangler CLI (npm install -g wrangler)
• Cloudflare account with Workers and R2 enabled
• ark-infographic-ts cloned as a sibling directory

Setup

1. Install dependencies

npm install

The library dependency (ark-infographic) is referenced via file:../ark-infographic-ts. Both repos must be cloned as siblings.

2. Generate bundled data

Extract species metadata and color table from ARK's values.json:

npx tsx scripts/extract-data.ts [path-to-values.json]

This writes src/data/colors.json and src/data/species-meta.json.

3. Create R2 bucket and upload sprites

npx wrangler login
npx wrangler r2 bucket create ark-creature-sprites
npm run upload-sprites -- <species-images-directory>

The upload script expects flat-directory naming conventions:

• {Species}.png → ASE base sprite
• {Species}_m.png → ASE mask
• {Species}_ASA.png → ASA base sprite
• {Species}_ASA_m.png → ASA mask

Uploaded to R2 as {game}/{species}/base.png and {game}/{species}/mask.png.

4. Add font files

Place Arial TrueType fonts in assets/fonts/:

• Arial-Regular.ttf
• Arial-Bold.ttf

These are bundled into the Worker for SVG-to-PNG rasterization.

Development

npm run dev        # Start local dev server (remote mode)
npm run typecheck  # Type-check without emitting
npm run build      # Dry-run build to dist/

Deployment

npm run deploy

Configuration

wrangler.toml

Setting	Value	Purpose
name	ark-infographic	Worker name on Cloudflare
compatibility_flags	nodejs_compat	Required for Buffer/crypto APIs
SPRITES R2 binding	ark-creature-sprites	Creature sprite storage
ENVIRONMENT var	production	Environment identifier

Bundle Size

~4.2 MB total (1.8 MB gzipped):

• resvg WASM binary: ~1.5 MB
• Arial fonts: ~300 KB
• Species metadata + colors: ~500 KB
• Application code + library: remainder