# Claude NPC Plugin - TODO

## Phase 1: Build System Setup

- [ ] **Obtain Hytale Server API JAR**
  - Contact Hypixel or check official modding documentation
  - Add as local Maven dependency or find Maven repository
  - Update `pom.xml` with correct artifact coordinates

- [ ] **Obtain Nitrado WebServer Plugin API**
  - Check if Nitrado publishes an API JAR for plugin development
  - May need to extract interfaces from the WebServer plugin JAR
  - Update `pom.xml` dependency

- [ ] **Create TeamCity Build Configuration**
  - Add build in `Gameserver` project
  - Maven build step: `mvn clean package`
  - Artifact: `target/SubNet_ClaudeNpc.jar`
  - Trigger: VCS changes to `Exiles/hytale-claude-npc`

## Phase 2: Hytale API Integration

These are placeholder implementations that need real Hytale API calls:

- [ ] **ClaudeNpcPlugin.java**
  - Implement proper plugin lifecycle (`onLoad`, `onEnable`, `onDisable`)
  - Register with WebServer plugin API for HTTP endpoints
  - Register chat event listener with Hytale event system

- [ ] **ClaudeNpc.java**
  - Implement NPC entity creation using Hytale NPC API
  - Implement pathfinding via Hytale's A* system
  - Implement particle effects for ethereal appearance
  - Implement chat broadcast to nearby players

- [ ] **ClaudeController.java**
  - Hook into Hytale tick system for behavior loop
  - Query actual player positions from server

- [ ] **WorldView.java**
  - Query nearby players from Hytale server API
  - Query nearby entities
  - Query terrain/block data
  - Query environment (time, weather, biome)

- [ ] **ClaudeApiHandler.java**
  - Register routes with WebServer plugin
  - Implement proper request/response handling per WebServer API

## Phase 3: Deployment

- [ ] **Build and Upload Plugin JAR**
  - Build with Maven
  - Upload to Gitea releases or artifact storage
  - Update `hytale_plugin_claude_url` in Ansible defaults

- [ ] **Create LiteLLM API Key**
  ```bash
  curl -X POST 'http://llm01.corp.sub-net.at:4000/key/generate' \
    -H "Authorization: Bearer $(bao kv get -field=master_key secret/ansible/litellm)" \
    -H 'Content-Type: application/json' \
    -d '{"key_alias": "hytale-claude-npc", "models": ["glm-flash"]}'
  ```
  - Store in OpenBao: `bao kv put secret/ansible/hytale litellm_apikey="sk-..."`

- [ ] **Run Ansible Playbook**
  ```bash
  ansible-playbook playbooks/setup_hytale.yml -l device_roles_hytale_server
  ```

- [ ] **Verify Deployment**
  ```bash
  # Check plugin loaded
  ssh hytale01 "grep -i claude /srv/hytale/logs/latest.log"

  # Test API endpoint
  curl -u 'serviceaccount.claude:<password>' \
    http://hytale01.corp.sub-net.at:5523/SubNet/ClaudeNpc/status
  ```

## Phase 4: Testing

- [ ] **Unit Tests**
  - Add JUnit tests for LiteLlmClient
  - Add tests for WorldView data structures
  - Add tests for ApiHandler request parsing

- [ ] **Integration Testing**
  - Test spawn/despawn cycle
  - Test movement and pathfinding
  - Test chat response generation
  - Test follow player behavior

- [ ] **In-Game Testing**
  - Join server and verify NPC appears
  - Test chat interactions
  - Test API control from Claude Code

## Phase 5: MCP Integration (Optional)

- [ ] **Create MCP Server**
  - Wrap HTTP endpoints as MCP tools
  - Tools: `hytale_spawn`, `hytale_move`, `hytale_chat`, `hytale_look`, `hytale_status`, `hytale_world`

- [ ] **Add to Claude Code MCP Config**
  ```json
  {
    "hytale": {
      "command": "node",
      "args": ["path/to/hytale-mcp/index.js"],
      "env": {
        "HYTALE_API_URL": "http://hytale01:5523",
        "HYTALE_API_USER": "serviceaccount.claude",
        "HYTALE_API_PASS": "..."
      }
    }
  }
  ```

## Notes

### Hytale Plugin API Reference
- Official docs: https://support.hytale.com/hc/en-us/articles/... (check for modding section)
- Nitrado plugins: https://github.com/nitrado (WebServer, Query, PerformanceSaver)
- ApexHosting plugins: https://github.com/apexhosting (PrometheusExporter)

### Key Unknowns
1. Exact Hytale server plugin API structure
2. How to register HTTP routes with WebServer plugin
3. How to create/manage NPC entities
4. How to access pathfinding system
5. Event system for chat messages

### Credentials Location
- LiteLLM: `secret/ansible/litellm` (master_key)
- Hytale service accounts: `secret/ansible/hytale` (prometheus_*, claude_*)