FAQ - Hycompanion

The plugin follows a specific lifecycle to ensure seamless integration:

Setup Phase Name: Loads configuration and checks API key before assets are loaded.
Asset Loading: Hytale loads NPC roles, including those cached from previous sessions.
Start Phase: Connects to the backend via WebSocket, authenticates, and syncs NPCs from the dashboard.
Runtime: Listens for events, routes messages to nearby NPCs, and executes AI actions.

NPCs are managed on the dashboard and synced automatically:

Create/Update: You make changes on the Dashboard (app.hycompanion.dev).
Backend Event: The backend sends a WebSocket event to your running server.
Plugin Action: The plugin receives the data, registers the NPC in-game, and caches the role file for the next startup.

When a player talks near an NPC:

Detection: The plugin detects a chat message within range.
Context Building: It gathers context (time, location, player info).
Backend Request: Sends everything to the AI backend via WebSocket.
AI Response: The AI generates a reply and optional actions (emotes, etc.) via AI tools.
Execution: The plugin displays the message and performs the actions in-game.

BYOK means you use your own API key to access AI models. Instead of us charging you for AI usage, you pay the AI provider (OpenRouter) directly. This keeps costs transparent and gives you full control over:

Which AI models to use
Your spending limits
Your API rate limits

Your actual AI conversations are stored for NPC memory.

LLM costs vary based on the model you choose and how much your NPCs chat. Here are some estimates:

Claude 3 Haiku: ~$0.25 per 1M input tokens, ~$1.25 per 1M output tokens
Claude 3.5 Sonnet: ~$3 per 1M input tokens, ~$15 per 1M output tokens
GPT-4o Mini: ~$0.15 per 1M input tokens, ~$0.60 per 1M output tokens

For a typical NPC conversation (a few back-and-forth messages), expect costs around $0.001-$0.01 depending on the model. A server with moderate chat activity might spend $5-20/month on AI.

Getting an OpenRouter key is easy:

Go to openrouter.ai
Sign up for a free account
Navigate to Keys in your dashboard
Create a new API key
(Optional): Add credits to your account ($5 minimum)

Your key will look like: sk-or-v1-xxxxxxxxxxxx

Hycompanion supports most of the models available through OpenRouter, including:

Claude 3.5 Sonnet, Claude 3 Haiku (Anthropic)
GLM 4.5, GLM 4.7

We recommend Claude 3 Haiku for the best balance of quality and cost.

NPC memory is stored securely on our servers. Here's how it works:

Each conversation is summarized and stored as a memory
Memories are linked to the NPC and player UUID
When a player returns, relevant memories are loaded into context
Old memories expire based on your plan (7 days for Spark, 90 days for Flame)

We never share your data with third parties. Memories are encrypted at rest.

Yes! We take privacy seriously:

All data is encrypted in transit
We never sell or share your data
You can request data deletion at any time

Check OpenRouter's privacy policy for how they handle AI requests.

Currently, we only support models through OpenRouter. However, OpenRouter provides access to many "self-hosted" models like Llama 3 (not tested) that you can use at very low cost.

In the future, we plan to add support for custom API endpoints so you can connect to your own AI infrastructure.

If you reach your limits:

NPC limit: You won't be able to create new NPCs until you upgrade or delete existing ones
Server limit: You won't be able to create new Servers until you upgrade or delete existing ones
Conversation limit: Oldest conversations will be archived when you hit the limit
Memory retention: Memories older than your limit will be automatically deleted