hytale-f2p-mirror/local-dev/README.md

Hytale F2P Local Development Environment

Local development setup for researching and testing the Hytale client. Uses the full hytale-auth-server with a debug wrapper for capturing all requests.

Quick Start

# 1. Start the local auth server
cd local-dev
chmod +x start.sh
./start.sh

# 2. In another terminal, start the launcher
cd ..
HYTALE_AUTH_DOMAIN=localhost:3000 npm start

That's it! The auth server will capture all requests for analysis.

What's Included

Full Auth Server with Debug Wrapper

• Uses the complete hytale-auth-server (not a minimal implementation)
• All endpoints work exactly as in production
• Debug wrapper captures ALL requests with full details
• Web-based debug dashboard at /debug
• Requests logged to data/auth/debug-requests.jsonl
• Unknown endpoints captured for research

Services

• Auth Server (port 3000) - Full hytale-auth-server with debug
• Kvrocks (port 6666) - Redis-compatible storage for sessions

Debug Dashboard

Access at http://localhost:3000/debug

Features:

• Real-time request viewer with auto-refresh
• Filter by subdomain (sessions, account-data, telemetry, tools)
• View full request/response details (headers, body, timing)
• Subdomain summary statistics
• Color-coded by request type and status

Directory Structure

local-dev/
├── docker-compose.yml      # Docker services config
├── Dockerfile.debug        # Dockerfile using debug entry point
├── debug-wrapper.js        # Debug wrapper for auth server
├── start.sh               # Start script
├── README.md              # This file
└── data/
    ├── auth/
    │   ├── jwt_keys.json       # Generated JWT keys
    │   └── debug-requests.jsonl # Request log
    └── kvrocks/                # Redis data

Endpoints

Debug Endpoints

Endpoint	Method	Description
/debug	GET	Web-based debug dashboard
/debug/requests	GET	JSON list of captured requests
/debug/requests?subdomain=X	GET	Filter by subdomain
/debug/subdomains	GET	Request summary by subdomain
/debug/requests	DELETE	Clear captured requests

Auth Server Endpoints

All standard hytale-auth-server endpoints work:

Endpoint	Method	Description
/health	GET	Health check
/.well-known/jwks.json	GET	JWT public keys
/game-session/new	POST	Create session
/game-session/refresh	POST	Refresh token
/game-session/child	POST	Child session
/game-session	DELETE	End session
/server-join/auth-grant	POST	Auth grant
/server-join/auth-token	POST	Token exchange
/my-account/game-profile	GET/POST	Profile
/my-account/cosmetics	GET	Cosmetics
/my-account/skin	POST	Save skin
/profile/uuid/:uuid	GET	Profile lookup
/profile/username/:username	GET	Username lookup
/avatar/:uuid	GET	Avatar viewer
/customizer/:uuid	GET	Avatar customizer
/admin	GET	Admin dashboard (password: localdev)

Catch-All

Unknown endpoints return a debug response with tokens for research.

Researching tools.hytale.com

The tools. subdomain is used for cloud-based asset management in builder/editor modes.

How to Trigger Tools API

Method 1: Builder Mode

1. Start local dev environment
2. Launch game
3. Look for Creative/Builder mode in game menu
4. Use asset import/export features
5. Check debug dashboard for captured tools. requests

Method 2: Server Configuration Builder mode may need server-side enablement:

• Server config for builderToolsEnabled
• Game mode settings
• Player permissions

Method 3: Console Commands Try these worldtools commands in-game:

worldtools.changeModel
worldtools.importImage
worldtools.importObj
worldtools.prefabEditor
worldtools.prefabList
worldtools.spawnEntity

Expected tools.hytale.com Endpoints

Based on binary analysis:

POST /assets/upload         - Upload asset files
GET  /assets/{id}           - Download asset by ID
POST /prefabs               - Save prefab
GET  /prefabs/{id}          - Load prefab
GET  /prefabs               - List prefabs

Commands

Start Services

./start.sh

View Logs

docker compose logs -f auth-server

Stop Services

docker compose down

View Captured Requests (CLI)

# All requests
curl http://localhost:3000/debug/requests | jq

# Filter by subdomain
curl "http://localhost:3000/debug/requests?subdomain=tools" | jq

# Subdomain summary
curl http://localhost:3000/debug/subdomains | jq

# From log file
cat data/auth/debug-requests.jsonl | jq -s '.'

Clear Request Log

curl -X DELETE http://localhost:3000/debug/requests

Environment Variables

Variable	Default	Description
HYTALE_AUTH_DOMAIN	-	Set to localhost:3000 for local dev
PORT	3000	Auth server port
DATA_DIR	/app/data	Data directory
DEBUG_MODE	true	Enable debug features
ADMIN_PASSWORD	localdev	Admin dashboard password

Troubleshooting

Client won't connect

1. Verify auth server is running: curl http://localhost:3000/health
2. Check environment variable: echo $HYTALE_AUTH_DOMAIN
3. Check Docker logs: docker compose logs auth-server

JWT/Token errors

1. Check JWKS endpoint: curl http://localhost:3000/.well-known/jwks.json
2. Ensure data/auth/jwt_keys.json exists
3. Try restarting: docker compose restart auth-server

Port 3000 in use

Change the port in docker-compose.yml:

ports:
  - "3001:3000"

Then use HYTALE_AUTH_DOMAIN=localhost:3001

Server won't start

Check for build errors:

docker compose logs auth-server
docker compose build --no-cache auth-server

Request Log Format

Each line in debug-requests.jsonl is a JSON object:

{
  "timestamp": "2026-01-27T12:00:00.000Z",
  "method": "POST",
  "path": "/game-session/new",
  "host": "localhost:3000",
  "subdomain": null,
  "headers": {"content-type": "application/json", ...},
  "query": {},
  "body": {"uuid": "...", "name": "Player"},
  "response": {
    "statusCode": 200,
    "duration": 15,
    "body": {"identityToken": "...", ...}
  }
}

How It Works

1. Docker Compose starts Kvrocks (Redis) and the auth server

2. Dockerfile.debug builds the auth server with debug-wrapper.js as entry point

3. debug-wrapper.js wraps the original server:

   • Intercepts all requests before they reach handlers
   • Captures request details (headers, body, timing)
   • Intercepts responses to capture response body
   • Stores everything in memory and log file
   • Adds /debug/* routes for the dashboard

4. When DEBUG_MODE=true:

   • All requests are logged to console with colors
   • Debug dashboard available at /debug
   • Unknown endpoints return debug info with valid tokens

5. When DEBUG_MODE=false:

   • Server runs normally (no debug overhead)
   • Same as production auth server