florian.berthold
814e2ca73a
Creates an AI-controlled NPC named "Claude" that: - Listens to nearby player chat and responds via LiteLLM (GLM-4.7-Flash) - Can be controlled via HTTP API endpoints - Provides world perception data for external AI control Components: - ClaudeNpcPlugin: Main plugin entry point - ClaudeNpc: NPC entity management - ClaudeController: Behavior state machine - LiteLlmClient: HTTP client for LiteLLM API - WorldView: Perception system - ClaudeApiHandler: HTTP endpoint handlers API endpoints: - POST /spawn, /move, /chat, /look, /emote - GET /status, /world Includes Ansible role updates for deployment.
135 lines
4.1 KiB
Markdown
135 lines
4.1 KiB
Markdown
# 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:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
curl -X POST https://hytale01:5523/SubNet/ClaudeNpc/chat \
|
|
-u 'serviceaccount.claude:<password>' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"message": "Hello, adventurers!"}'
|
|
```
|
|
|
|
**Get status:**
|
|
```bash
|
|
curl https://hytale01:5523/SubNet/ClaudeNpc/status \
|
|
-u 'serviceaccount.claude:<password>'
|
|
```
|
|
|
|
**Follow a player:**
|
|
```bash
|
|
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`:
|
|
|
|
```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:
|
|
|
|
```bash
|
|
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)
|