Poidex 🗺️

Poidex is your personal atlas of discovery. A Hytale server mod for managing named waypoints with HUD compass tracking.

Important

This mod requires a valid Hytale server installation. The build uses HytaleServer.jar from your local install (see Configuration). It does not provide game binaries.

---

✨ Features

• 📍 Named waypoints – Save locations with custom names (/atlas add "Home")
• 🧭 Multi-POI compass tracking – Track multiple locations simultaneously on your HUD compass
• 🎨 Custom marker icons – Choose from Home, Spawn, Death, Portal, Warp, or Player icons
• 🖥️ Visual UI – Manage POIs in-game with search, track/untrack, and icon selection (/atlas ui)
• 🌍 Per-world storage – POIs are per-player, per-world with automatic restore on rejoin
• ⚡ Warp support – Operators can teleport to saved locations

🚀 Quick Start

1. Prerequisites

• JDK 25
• Gradle 9.2.0 (wrapper included)
• Hytale server JAR – Expected at %APPDATA%/Hytale/install/release/package/game/latest/Server/HytaleServer.jar on Windows (override in build.gradle.kts if needed)

2. Build and deploy

# Build the mod (fat JAR)
./gradlew shadowJar

# Build and copy to Hytale mods folder
./gradlew deployToMods

3. Run the server (optional)

./gradlew runServer

Deploys the mod and starts the Hytale server (port 5520, 2GB heap).

---

📋 Commands

Command	Description
/atlas add "name"	Save your current position with a name
/atlas list	List all saved locations in the current world
/atlas enable "name"	Track a location on your HUD compass (can track multiple)
/atlas disable [name|--all]	Stop tracking one entry by name, or --all to clear all
/atlas remove "name"	Delete a saved location
/atlas warp "name"	Teleport to a location (requires poidex.atlas.warp)
/atlas ui	Open the POI management UI

🔐 Permissions

Permission	Description
poidex.atlas.warp	Use /atlas warp and the Warp button in the UI

Example:

/perm user add <player-uuid> poidex.atlas.warp

Or grant operator (all permissions):

/op <player-name>

---

⚙️ Configuration

Build and paths are configured in build.gradle.kts. Defaults:

• Hytale base path (Windows): %APPDATA%/Hytale/install/release/package/game/latest
• Mods directory: %APPDATA%/Hytale/UserData/Mods

Ensure the APPDATA environment variable is set. To use a different install path, adjust the appData / hytaleBase values in build.gradle.kts.

Custom UI and asset pack

This mod uses Custom UI (.ui files) and has IncludesAssetPack: true. The game client must be able to load those assets:

• Put the built mod JAR in the same Mods folder the game uses: %APPDATA%/Hytale/UserData/Mods. deployToMods copies the JAR there so both server and client use it if they share that path.
• If you see "Failed to load CustomUI documents" when starting the game or connecting:
  1. Rebuild the mod: ./gradlew shadowJar then copy the JAR from build/libs/ to your Mods folder (or run ./gradlew deployToMods).
  2. Ensure the mod is enabled in the game’s mod list (New World → Options).
  3. Enable Diagnostic Mode in Hytale (Settings → General) for more detailed errors.

---

🤖 MCP integration (AI-assisted development)

This project is developed with hytale-docs-mcp, an MCP server that decompiles and indexes HytaleServer.jar and exposes tools for searching the Hytale API. Use it with Cursor, Windsurf, or other MCP clients for accurate API lookups.

Option A: HTTP transport (remote MCP server)

If hytale-docs-mcp is already running (e.g. on port 8080), add to your MCP config (e.g. .mcp.json or Cursor MCP settings):

{
  "mcpServers": {
    "hytale-docs": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Option B: Stdio transport (run from repo)

From the hytale-docs-mcp repository:

{
  "mcpServers": {
    "hytale-docs": {
      "command": "cargo",
      "args": ["run", "--release", "--", "stdio"],
      "cwd": "/absolute/path/to/hytale-docs-mcp"
    }
  }
}

Tip

Prefer hytale-docs-mcp over generic web docs for Hytale: it indexes the real decompiled source and stays accurate.

---

📚 Documentation

• CLAUDE.md – Context for AI assistants: project structure, patterns, and workflow for using hytale-docs-mcp when editing Poidex.
• hytale-docs-mcp docs – MCP guide, configuration, and architecture.

---

📁 Project structure

src/main/kotlin/dev/bitflipped/plugin/
├── Poidex.kt           # Entry point, extends JavaPlugin
├── AtlasCommand.kt     # Command handlers and action helpers
├── AtlasStorage.kt     # JSON file persistence
├── AtlasData.kt        # Data model for player atlas
├── AtlasEntry.kt       # Single waypoint entry model
└── ui/
    ├── AtlasPage.kt          # Interactive UI page
    └── AtlasPageEventData.kt # UI event codec

src/main/resources/
├── manifest.json
└── Common/UI/Custom/
    ├── AtlasPage.ui
    └── AtlasEntryRow.ui

💾 Data storage

Player atlas data is stored under the mod data directory:

<mod-data>/data/<world-name>/<player-uuid>-atlas.json

Storage is per-player, per-world.

---

🛠️ Tech stack

• Kotlin 2.3.0 / JDK 25
• Gradle 9.2.0 with Shadow plugin (fat JAR)
• Hytale Server API (compileOnly, from local JAR)
• kotlinx-serialization-json 1.9.0

---

🤝 Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

📄 License

This project is licensed under the MIT License – see LICENSE for details.

🙏 Acknowledgments

• Claude Code – AI-assisted development
• Cursor – AI editor and agentic development platform
• hytale-docs-mcp – MCP server for decompiled Hytale API (AI-assisted development)
• Hytale – The game this mod is built for
• hytalemodding.dev – Community modding documentation