hytale-claude-npc/README.md

Claude NPC Plugin for Hytale

An AI-controlled NPC for Hytale that responds to player chat via LiteLLM.

Overview

This plugin creates an ethereal NPC named "Claude" that:

• Listens to nearby player chat and responds contextually via AI (GLM-4.7-Flash)
• Can be controlled via HTTP API endpoints
• Provides world perception data for external AI control

Architecture

                                  ┌─────────────────────┐
                                  │   LiteLLM Proxy     │
                                  │ (llm01:4000)        │
                                  └──────────┬──────────┘
                                             │
Claude Code ──HTTP──> WebServer Plugin ──> Claude NPC Plugin ──> NPC Entity
                      (port 5523)          (this plugin)         (in-game)

API Endpoints

All endpoints are prefixed with /SubNet/ClaudeNpc/.

Method	Endpoint	Description
POST	/spawn	Spawn NPC at coordinates
POST	/move	Move to coordinates or follow player
POST	/chat	Send chat message as NPC
POST	/look	Look at coordinates or player
POST	/emote	Play an animation/emote
GET	/status	Get NPC position, state, nearby info
GET	/world	Get full world perception data

Examples

Spawn the NPC:

curl -X POST https://hytale01:5523/SubNet/ClaudeNpc/spawn \
  -u 'serviceaccount.claude:<password>' \
  -H 'Content-Type: application/json' \
  -d '{"x": 0, "y": 64, "z": 0}'

Send a chat message:

curl -X POST https://hytale01:5523/SubNet/ClaudeNpc/chat \
  -u 'serviceaccount.claude:<password>' \
  -H 'Content-Type: application/json' \
  -d '{"message": "Hello, adventurers!"}'

Get status:

curl https://hytale01:5523/SubNet/ClaudeNpc/status \
  -u 'serviceaccount.claude:<password>'

Follow a player:

curl -X POST https://hytale01:5523/SubNet/ClaudeNpc/move \
  -u 'serviceaccount.claude:<password>' \
  -H 'Content-Type: application/json' \
  -d '{"follow": "PlayerName"}'

Configuration

Configuration is stored in data/mods/SubNet_ClaudeNpc/config.json:

{
  "litellmEndpoint": "http://llm01.corp.sub-net.at:4000/v1/chat/completions",
  "litellmApiKey": "",
  "litellmModel": "glm-flash",
  "npcName": "Claude",
  "npcDisplayName": "§b✧ Claude ✧",
  "glowEffect": true,
  "chatRange": 32.0,
  "respondToAllChat": false,
  "maxResponseLength": 256,
  "systemPrompt": "You are Claude, a friendly AI spirit..."
}

Building

Requires Java 25 and Maven:

mvn clean package

The plugin JAR will be in target/SubNet_ClaudeNpc.jar.

Deployment

The plugin is deployed via Ansible alongside other Hytale plugins.

1. Build the JAR (or use TeamCity)
2. Upload to artifact storage
3. Run the Hytale playbook to deploy

Permissions

The plugin defines these WebServer permissions:

Permission	Description
subnet.claudenpc.web.spawn	Spawn/despawn NPC
subnet.claudenpc.web.move	Move NPC
subnet.claudenpc.web.chat	Send chat as NPC
subnet.claudenpc.web.look	Control NPC look dir
subnet.claudenpc.web.emote	Trigger emotes
subnet.claudenpc.web.status	Read NPC status
subnet.claudenpc.web.world	Read world perception

Chat Behavior

The NPC automatically responds to nearby players when:

• A player says "Claude" in their message
• A player starts with "hey", "hi", or "hello"
• respondToAllChat is enabled in config

Responses are generated via LiteLLM using the configured model (default: glm-flash).

Dependencies

• Hytale Server (tested with latest)
• Nitrado WebServer Plugin (for HTTP API)
• LiteLLM (for AI responses)