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

```bash
# 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
```bash
./start.sh
```

### View Logs
```bash
docker compose logs -f auth-server
```

### Stop Services
```bash
docker compose down
```

### View Captured Requests (CLI)
```bash
# 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
```bash
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:
```yaml
ports:
  - "3001:3000"
```
Then use `HYTALE_AUTH_DOMAIN=localhost:3001`

### Server won't start
Check for build errors:
```bash
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:

```json
{
  "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