# 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)