From c8532815f3fac9f79c76e82eae4a42fbcefbb750 Mon Sep 17 00:00:00 2001
From: Florian Berthold <florian.berthold@sub-net.at>
Date: Sat, 24 Jan 2026 23:12:29 +0100
Subject: [PATCH] Add TODO list for remaining implementation work

---
 TODO.md | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 136 insertions(+)
 create mode 100644 TODO.md

diff --git a/TODO.md b/TODO.md
new file mode 100644
index 0000000..3632579
--- /dev/null
+++ b/TODO.md
@@ -0,0 +1,136 @@
+# 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_*)