hytale-claude-npc/TODO.md

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

  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

  ansible-playbook playbooks/setup_hytale.yml -l device_roles_hytale_server
  

• Verify Deployment

  # 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

  {
    "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_)