Quick Start Guide

Get your first AI NPC running in under 5 minutes

Prerequisites

Before you begin, make sure you have:

  • A Hytale server running (version X.X or later)
  • A OpenRouter API Key (obtained from openrouter.ai)

💡 What is OpenRouter? OpenRouter is a service that provides access to multiple AI models (like Claude, GPT-4, etc.) through a single API. You only pay for what you use.

Step 1: Create Your Account

  1. Create an account using your email (or Google Account) on app.hycompanion.dev
  2. Verify your email address

Step 2: Install the Plugin

  1. Download the latest hycompanion-hytale.jar from the dashboard
  2. Stop your Hytale server
  3. Copy hycompanion-hytale.jar to your server's mods/ folder
  4. Start the server to generate the config file
  5. The plugin creates its data folder at mods/dev.hycompanion_Hycompanion/

Step 3: Register Your API Key

You have two ways to configure your API key:

Option A: In-game command (Recommended)

This saves the key and immediately connects to the backend.

/hycompanion register <your-api-key>

Option B: Edit config.yml manually

Open mods/dev.hycompanion_Hycompanion/config.yml:

config.yml 
connection:
  url: "https://api.hycompanion.dev"
  api_key: "your-api-key-here"

Then run restart the server.

Step 4: Create Your First NPC

  1. Go to the Hycompanion Dashboard
  2. Select your server and click "Create NPC"
  3. Fill in the NPC details:
    • External ID: Unique identifier (e.g., merchant_bob)
    • Name: Display name (e.g., Bob the Merchant)
    • Personality: Describe how the NPC should behave
    • Greeting: What the NPC says when a player approaches
    • Other Settings: LLM and Hytale Role configuration
    • Behavior & Appearance: Keep Inheritance -> Variant -> Hycompanion Role for now. In Behavior section, choose Idle, Wander and Follow. In Appearance section, choose the Appearance of your choice.
  4. Save the NPC
  5. Spawn the NPC in-game using the command /hycompanion spawn <external-id>. For example /hycompanion spawn merchant_bob. If it doesn't work, restart the server, and try again or run /hycompanion rediscover

The plugin will automatically sync the NPC from the dashboard.

Note: Due to Hytale's plugin architecture, custom NPC roles requires the plugin to scan existing spawned NPCs to detect them and apply the new role / update. This process of updating a NPC on the dashboard will take a few seconds to apply in-game and may slow down NPCs temporarily.

Commands

Command Description
/hycompanion register <api-key> Register your API key and connect
/hycompanion spawn <external-id> Spawn an NPC in-game
/hycompanion despawn <uuid> Despawn an NPC in-game. Uuid comes from the /hycompanion list command.
/hycompanion status Show connection status and NPC count
/hycompanion sync Force sync NPCs from backend
/hycompanion list List all loaded Hycompanion NPCs and display their UUID.
/hycompanion rediscover Rediscover existing NPCs and apply their configuration
/hycompanion help Show help message

File Structure

After installation, the plugin creates the following structure:

mods/
├── hycompanion-hytale.jar          # The plugin JAR
└── dev.hycompanion_Hycompanion/    # Plugin data folder
    ├── config.yml                  # Configuration file
    ├── data/
    │   └── npcs/                   # Cached NPC configurations
    │       └── bob_merchant.json
    ├── role_cache/                 # Cached Hytale role files
    │   └── hycompanion_bob_merchant.json
    └── assets/
        └── NPC/
            └── Roles/              # Active role files (copied from cache)
                └── hycompanion_bob_merchant.json

What's Next?

Now that you have your first AI NPC running, explore these topics: