Fix community link order: TG Group > TG Channel > Chat

Consistent order across all files. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-26 14:51:48 -03:00 · 2026-02-25 01:11:17 +01:00
parent 89b9135523
commit 66493d35ca
47 changed files with 18884 additions and 0 deletions
--- a/local-dev/README.md
+++ b/local-dev/README.md
@@ -0,0 +1,252 @@
+# 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