hytale-f2p-mirror/docs/CLIENT_BINARY_ANALYSIS.md

Hytale Client Binary Analysis

CSC_LINK="/Users/sanasol/Downloads/Certificates-hytale.p12" CSC_KEY_PASSWORD="YieocpBVP68Rih*" APPLE_ID="sanasol2008rs@gmail.com" APPLE_APP_SPECIFIC_PASSWORD="ihah-lbta-movj-iqni" APPLE_TEAM_ID="9WVL8YG95H" npm run build:mac CSC_LINK="/Users/sanasol/Downloads/Certificates-hytale.p12" CSC_KEY_PASSWORD="YieocpBVP68Rih*" APPLE_ID="sanasol2008rs@gmail.com" APPLE_APP_SPECIFIC_PASSWORD="ihah-lbta-movj-iqni" APPLE_TEAM_ID="9WVL8YG95H" npx electron-builder --mac --arm64

password ihah-lbta-movj-iqni team id 9WVL8YG95H cert pass YieocpBVP68Rih*

Overview

This document contains a comprehensive analysis of the HytaleClient binary, documenting all discovered URLs, API endpoints, service domains, patchable strings, and internal functionality.

Binary Analyzed: HytaleClient (macOS .NET AOT compiled) Analysis Date: 2026-01-27 String Encoding: UTF-16LE (Windows .NET string format)

---

Table of Contents

1. Service URLs
2. API Endpoints
3. World Tools & Builder Tools
4. External Service URLs
5. Patchable Strings
6. Sentry Error Tracking
7. Internal Class References
8. Binary Offsets Reference
9. Implementation Notes

---

1. Service URLs

1.1 Primary Hytale Services

The client connects to four main service subdomains:

Service	URL Pattern	Purpose	Status
Sessions	https://sessions.{domain}	Authentication, JWT tokens, session management	Implemented in auth-server
Account Data	https://account-data.{domain}	Player profiles, skins, account information	Implemented in auth-server
Telemetry	https://telemetry.{domain}	Analytics, error reporting, usage statistics	Implemented (accepts/discards)
Tools	https://tools.{domain}	Asset editor, prefab management, world tools	Not implemented

1.2 URL Construction

The client constructs URLs by combining:

1. Protocol: https://
2. Subdomain: sessions., account-data., telemetry., tools.
3. Base domain: hytale.com

Example: https:// + sessions. + hytale.com = https://sessions.hytale.com

The client patcher replaces these components to redirect traffic to the F2P auth server.

1.3 F2P Domain Routing

For F2P mode, all subdomains route to a single endpoint:

• sessions.{f2p_domain} → https://{f2p_domain}
• account-data.{f2p_domain} → https://{f2p_domain}
• telemetry.{f2p_domain} → https://{f2p_domain}
• tools.{f2p_domain} → https://{f2p_domain}

---

2. API Endpoints

2.1 Session Management Endpoints

POST /game-session/new

Create a new game session.

Request:

{
  "clientVersion": "string",
  "platform": "string"
}

Response:

{
  "token": "JWT token",
  "refreshToken": "refresh token",
  "expiresIn": 36000
}

POST /game-session/refresh

Refresh an existing session token.

Request:

{
  "refreshToken": "string"
}

Response:

{
  "token": "new JWT token",
  "refreshToken": "new refresh token",
  "expiresIn": 36000
}

POST /game-session/child

Create a child session (for server connections).

Request:

{
  "parentToken": "string",
  "audience": "server identifier"
}

DELETE /game-session

Notify server of session end (player disconnect).

2.2 Server Join Endpoints

POST /server-join/auth-grant

Request authorization grant for connecting to a game server.

Request:

{
  "serverAddress": "string",
  "serverPort": number
}

Response:

{
  "grant": "authorization grant string"
}

POST /server-join/auth-token

Exchange authorization grant for server-specific token with certificate binding.

Request:

{
  "grant": "authorization grant",
  "clientCertHash": "SHA256 hash of client certificate"
}

Response:

{
  "token": "server-specific JWT with cnf claim"
}

2.3 Account Endpoints

GET /my-account/game-profile

Get the player's game profile.

Response:

{
  "uuid": "player UUID",
  "username": "display name",
  "createdAt": "timestamp"
}

POST /my-account/game-profile

Update the player's game profile.

Request:

{
  "username": "new display name"
}

GET /my-account/cosmetics

Get list of unlocked cosmetics for the player.

Response:

{
  "cosmetics": [
    {
      "id": "cosmetic_id",
      "category": "category_name",
      "unlockedAt": "timestamp"
    }
  ]
}

POST /my-account/skin

Save player's skin/character customization preferences.

Request:

{
  "skinTone": "SkinTone_01",
  "bodyType": "Default",
  "parts": {
    "haircut": "Haircut_ShortMessy.Blue",
    "eyes": "Eyes_Default.Green",
    "eyebrows": "Eyebrows_Default",
    "face": "Face_Default"
  }
}

2.4 JWKS Endpoint

GET /.well-known/jwks.json

Get JSON Web Key Set for JWT verification.

Response:

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "base64url-encoded-public-key",
      "kid": "key-id",
      "use": "sig",
      "alg": "EdDSA"
    }
  ]
}

2.5 Profile Lookup Endpoints

GET /profile/uuid/{uuid}

Lookup player profile by UUID.

GET /profile/username/{username}

Lookup player profile by username (server-scoped).

---

3. World Tools & Builder Tools

3.1 World Tools (worldtools.*)

These are in-game tools for world creation and editing in builder/creative mode.

Tool	Command	Description
Change Model	worldtools.changeModel	Change the model of an entity in the world
Import Image	worldtools.importImage	Import image files into the world as textures
Import OBJ	worldtools.importObj	Import 3D OBJ model files into the world
Instance	worldtools.instance	Manage world instances and copies
Play Sound	worldtools.playSound	Play sound effects in the world
Prefab Editor	worldtools.prefabEditor	Open the prefab editor interface
Prefab List	worldtools.prefabList	List and manage saved prefabs
Spawn Entity	worldtools.spawnEntity	Spawn entities at specified locations
Spawn Particle	worldtools.spawnParticle	Spawn particle effects
Tint Chunk	worldtools.tintChunk	Apply color tinting to world chunks

3.2 Builder Tools (buildertools.*)

Additional tools for the asset editor and builder mode.

Tool	Class	Description
Image Import	buildertools.imageimport.ImageImportPage	UI page for importing images
OBJ Import	buildertools.objimport.ObjImportPage	UI page for importing OBJ models
Prefab Editor	buildertools.prefabeditor.ui.PrefabEditorLoadSettings	Prefab editor with load/save
Prefab List	buildertools.prefablist.PrefabPage	Prefab listing and management

3.3 Machinima Tool

• Purpose: In-game cinematic/video recording tool
• Access: Available via hotbar slot
• Message: "Hotbar is full. Clear a slot to receive the Machinima tool."

3.4 Asset Editor

The client includes an asset editor with these features:

• AssetEditorDownload - Download assets from tools service
• assetEditor.exportModal - Export modal for assets
• assetEditor.fileSaveState - File save state management
• assetEditor.property.tooltip - Property tooltips

3.5 tools.hytale.com API Requirements

To fully support builder mode, the tools service would need:

POST /assets/upload
  - Upload asset files (images, models, sounds)
  - Returns asset ID/URL

GET /assets/{assetId}
  - Download asset by ID
  - Returns asset binary data

POST /prefabs/save
  - Save prefab definition
  - Returns prefab ID

GET /prefabs/{prefabId}
  - Load prefab by ID
  - Returns prefab JSON

GET /prefabs/list
  - List user's saved prefabs
  - Returns array of prefab metadata

DELETE /prefabs/{prefabId}
  - Delete a prefab

Note: The game functions without tools.hytale.com - it's only needed for cloud-based asset sharing in builder mode.

---

4. External Service URLs

4.1 Hytale Official URLs

URL	Purpose	Patchable
https://store.hytale.com/?upgrade=	In-game store for purchases	Yes
https://hytale.com/help/joining-friends	Help documentation	Yes
https://discord.gg/hytale	Official Discord invite	Yes

4.2 Third-Party Service URLs

URL	Purpose	Notes
https://blockbench.net/downloads	Blockbench download page	3D model editor
https://blockbench.net/plugins/hytale_plugin	Hytale Blockbench plugin	For asset creation
https://docs.sentry.io/platforms/dotnet/*	Sentry documentation	Error tracking docs
https://aka.ms/*	Microsoft .NET documentation	Runtime docs
https://learn.microsoft.com/*	Microsoft Learn	.NET API docs
https://go.microsoft.com/*	Microsoft redirects	Various docs

4.3 Graphics/Rendering References

URL	Purpose
https://www.khronos.org/opengl/wiki/Interface_Block_(GLSL)	GLSL interface blocks
https://www.khronos.org/opengl/wiki/Sampler_(GLSL)	GLSL texture samplers
https://www.shadertoy.com/view/Xd23Dh	Shader reference
https://www.shadertoy.com/view/ltlSRj	Shader reference
https://aras-p.info/texts/CompactNormalStorage.html	Normal map compression
https://mynameismjp.wordpress.com/2009/03/10/reconstructing-position-from-depth/	Depth reconstruction
https://briansharpe.files.wordpress.com/2018/07/moment-transparency-supp-av.pdf	Transparency rendering
https://www.pmavridis.com/research/fbcompression/	Frame buffer compression
https://jcgt.org/published/0002/02/09/	Graphics technique
https://jcgt.org/published/0006/01/03/	Graphics technique
https://graphics.cs.williams.edu/papers/CSSM/	Graphics paper
http://www.humus.name/Articles/Persson_LowLevelThinking.pdf	Low-level graphics

4.4 GitHub References

URL	Purpose
https://github.com/NLog/NLog.git	Logging framework
https://github.com/Noesis/Managed/tree/master/Src/Noesis/Core	NoesisGUI core
https://github.com/Noesis/Managed/tree/master/Src/NoesisApp/Core	NoesisGUI app
https://github.com/dotnet/dotnet	.NET runtime
https://github.com/ektrah/nsec.git	NSec cryptography
https://github.com/getsentry/sentry-dotnet	Sentry .NET SDK

---

5. Patchable Strings

5.1 Domain Strings

Original	Replacement	Purpose
hytale.com	{f2p_domain}	Base domain (4-16 chars)
sessions.	Stripped or replaced	Session service subdomain
account-data.	Stripped or replaced	Account service subdomain
telemetry.	Stripped or replaced	Telemetry subdomain
tools.	Stripped or replaced	Tools service subdomain

5.2 URL Strings

Original	Can Replace With	Notes
https://store.hytale.com/?upgrade=	Custom store URL	In-game purchases
https://discord.gg/hytale	Custom Discord	Community link
https://hytale.com/help/joining-friends	Custom help docs	Help system
sentry.hytale.com	Own Sentry or disable	Error tracking

5.3 String Encoding Details

.NET UTF-16LE Format:

• Each character is 2 bytes (little-endian)
• Example: "hytale" = 68 00 79 00 74 00 61 00 6c 00 65 00
• Strings are length-prefixed in the binary

Length Prefix Format:

• 1 byte for strings < 128 chars
• 2 bytes (varint) for longer strings
• Followed by UTF-16LE character data

5.4 Current Patcher Behavior

The clientPatcher.js patches:

1. sessions.hytale.com → {f2p_domain} (single endpoint)
2. account-data.hytale.com → {f2p_domain}
3. telemetry.hytale.com → {f2p_domain}

Not currently patched:

• tools.hytale.com (builder mode assets)
• store.hytale.com (in-game store)
• sentry.hytale.com (error tracking)

---

6. Sentry Error Tracking

6.1 Sentry Configuration

DSN Found in Binary:

https://ca900df42fcf57d4dd8401a86ddd7da2@sentry.hytale.com/

DSN Components:

• Protocol: https
• Public Key: ca900df42fcf57d4dd8401a86ddd7da2
• Host: sentry.hytale.com
• Project ID: (after trailing slash)

6.2 Sentry Integration

The client uses the official Sentry .NET SDK:

• Package: sentry-dotnet
• Documentation refs found in binary

6.3 Patching Options

Option 1: Disable Sentry

• Replace DSN with invalid string
• Errors won't be reported

Option 2: Redirect to Own Sentry

• Replace sentry.hytale.com with own Sentry host
• Requires same-length domain or binary patching

Option 3: Leave As-Is

• Errors still report to Hypixel
• May expose F2P server information

6.4 Sentry Environment Variables

Found configuration references:

• SENTRY_DSN - DSN override
• SENTRY_ENVIRONMENT - Environment name
• Docs: https://docs.sentry.io/platforms/dotnet/configuration/environments

---

7. Internal Class References

7.1 Package Structure

com.hypixel.hytale/
├── builtin/
│   ├── buildertools/
│   │   ├── imageimport/
│   │   │   └── ImageImportPage
│   │   ├── objimport/
│   │   │   └── ObjImportPage
│   │   ├── prefabeditor/
│   │   │   └── ui/PrefabEditorLoadSettings
│   │   └── prefablist/
│   │       └── PrefabPage
│   ├── instances/
│   │   └── page/InstanceListPage
│   └── model/
│       └── pages/ChangeModelPage
├── server/
│   └── core/
│       └── asset/
│           └── type/
│               └── particle/
│                   └── pages/ParticleSpawn*
└── Creation/
    └── navigation/
        ├── buildertools/
        └── worldtools/
            ├── changeModel
            ├── importImage
            ├── importObj
            ├── instance
            ├── playSound
            ├── prefabEditor
            ├── prefabList
            ├── spawnEntity
            ├── spawnParticle
            └── tintChunk

7.2 UI Components

Component	Path	Purpose
GameLoading	/GameLoading.u	Loading screen
GamePageNavigation	/GamePageNavigation.u	Main navigation
ServerButton	/ServerButton.u	Server list button
ServerModal	/ServerModal.u	Server details modal
ServersPage	/Servers/ServersPage.u	Server browser
DirectConnectPopup	/Servers/DirectConnectPopup.u	Direct connect dialog
EditServerPopup	/Servers/EditServerPopup.u	Edit server dialog
JoinViaCodePopup	/Servers/JoinViaCodePopup.u	Join via code dialog
MinigamesPage	/Minigames/MinigamesPage.u	Minigames browser

7.3 Configuration Files

File	Purpose
/GameplayConfigs/Default.json	Default gameplay settings
hytale_plugin.js	Blockbench plugin script
hytale_assets	Asset reference

---

8. Binary Offsets Reference

8.1 URL String Offsets (macOS binary)

Offset	Content	Length
0x1bf0098	https://account-data	~21 chars
0x1bf00c9	https://aka.ms/dotnet-warnings/{0}	~35 chars
0x1bf0114	https://blockbench.net/downloads	~33 chars
0x1bf015d	https://blockbench.net/plugins/hytale_plugin	~45 chars
0x1bf01bc	https://...@sentry.hytale.com/	~60 chars
0x1bf023b	https://discord.gg/hytale	~26 chars
0x1bf0274	https://hytale.com/help/joining-friends	~40 chars
0x1bf02c9	https://sessions	~17 chars
0x1bf02f2	https://store.hytale.com/?upgrade=	~35 chars
0x1bf033d	https://telemetry	~18 chars
0x1bf0368	https://tools	~14 chars

8.2 API Endpoint Offsets

Offset	Endpoint
0x1b115d2	/game-session/child
0x1b115ff	/game-session/refresh
0x1b117c2	/server-join/auth-grant
0x1b117f7	/server-join/auth-token
0x1b11689	/my-account/cosmetics
0x1b116ba	/my-account/game-profile
0x1b116f1	/my-account/skin
0x1b10d8c	/.well-known/jwks.json

8.3 Notes on Offsets

• Offsets are for the macOS binary
• Windows/Linux binaries will have different offsets
• Offsets may change between game versions
• Always verify offsets before patching

---

9. Implementation Notes

9.1 Current Auth Server Implementation

The auth server (hytale-auth-server) currently implements:

Fully Implemented:

• /game-session/new - Session creation
• /game-session/refresh - Token refresh
• /server-join/auth-grant - Auth grants
• /server-join/auth-token - Token exchange with cert binding
• /my-account/cosmetics - Cosmetic list
• /my-account/game-profile - Profile get/update
• /my-account/skin - Skin save
• /.well-known/jwks.json - JWKS endpoint
• /profile/uuid/{uuid} - UUID lookup
• /profile/username/{username} - Username lookup
• Telemetry endpoints (accept and discard)

Not Implemented:

• tools.hytale.com API (asset upload/download)
• Prefab cloud storage
• Asset sharing between players

9.2 Tools Service Implementation (Future)

If implementing tools.hytale.com functionality:

// Suggested endpoints for auth-server

// Asset upload
app.post('/tools/assets/upload', async (req, res) => {
  // Handle multipart file upload
  // Store in local filesystem or S3
  // Return asset ID
});

// Asset download
app.get('/tools/assets/:assetId', async (req, res) => {
  // Retrieve asset by ID
  // Stream file to client
});

// Prefab operations
app.post('/tools/prefabs', async (req, res) => {
  // Save prefab JSON
  // Associate with user
});

app.get('/tools/prefabs/:prefabId', async (req, res) => {
  // Get prefab by ID
});

app.get('/tools/prefabs', async (req, res) => {
  // List user's prefabs
});

app.delete('/tools/prefabs/:prefabId', async (req, res) => {
  // Delete prefab
});

9.3 Patching Recommendations

Essential (Already Done):

1. Patch sessions.hytale.com → F2P domain
2. Patch account-data.hytale.com → F2P domain
3. Patch telemetry.hytale.com → F2P domain (or disable)

Optional Enhancements:

1. Patch tools.hytale.com → F2P domain (if implementing tools API)
2. Patch sentry.hytale.com → Own Sentry or disable
3. Patch discord.gg/hytale → Community Discord
4. Patch store.hytale.com → Custom store (if applicable)

Not Recommended to Patch:

• Blockbench URLs (useful for modding)
• Microsoft documentation URLs
• Graphics reference URLs

9.4 Security Considerations

1. Sentry DSN Exposure

   • Current: Errors report to Hypixel's Sentry
   • Risk: May expose F2P server details
   • Recommendation: Disable or redirect

2. Telemetry Data

   • Current: Accepted but discarded
   • Alternative: Log for analytics
   • Risk: Privacy concerns

3. Asset Upload (if implemented)

   • Validate file types
   • Limit file sizes
   • Scan for malicious content
   • Rate limit uploads

---

Appendix A: String Extraction Commands

Extract UTF-16LE Strings

python3 << 'EOF'
with open("HytaleClient", "rb") as f:
    data = f.read()

pattern = b'h\x00t\x00t\x00p\x00s\x00:\x00/\x00/\x00'
idx = 0
while True:
    idx = data.find(pattern, idx)
    if idx == -1:
        break
    end = idx
    chars = []
    while end < len(data) - 1:
        char = data[end] | (data[end+1] << 8)
        if 0x20 <= char <= 0x7e:
            chars.append(chr(char))
            end += 2
        else:
            break
    print(f"{hex(idx)}: {''.join(chars)}")
    idx += 2
EOF

Search for Specific Pattern

xxd HytaleClient | grep "h.y.t.a.l.e"

Extract Context Around Offset

dd if=HytaleClient bs=1 skip=$((0x1bf0000)) count=2048 | xxd

---

Appendix B: Version History

Date	Changes
2026-01-27	Initial analysis of macOS client binary

---

Appendix C: Related Documentation

• CLAUDE.md - Project overview and architecture
• DUAL_AUTH_FLOW.md - Dual authentication flow diagrams
• STEAMDECK_CRASH_INVESTIGATION.md - libzstd crash fix
• PLAYER_PASSWORD_FEATURE.md - Planned password authentication
• backend/utils/clientPatcher.js - Client patcher implementation