the-island/unity-client/SETUP.md

The Island - Unity Client Setup Guide

Prerequisites

• Unity 6000.3.2f1 or later
• Python backend running (python run.py)
• NativeWebSocket package installed

---

Step 1: Install NativeWebSocket

Option A: Via Package Manager (Recommended)

1. Open Unity
2. Go to Window > Package Manager
3. Click + > Add package from git URL
4. Enter: https://github.com/endel/NativeWebSocket.git#upm
5. Click Add

Option B: Via manifest.json

Add to Packages/manifest.json:

{
  "dependencies": {
    "com.endel.nativewebsocket": "https://github.com/endel/NativeWebSocket.git#upm"
  }
}

---

Step 2: Import Scripts

1. Copy the Assets/Scripts folder into your Unity project
2. Unity will auto-compile the scripts

---

Step 3: Create the Agent Prefab

3.1 Create Base Structure

1. Create > 3D Object > Capsule (or import your character model)
2. Rename to AgentPrefab
3. Add Box Collider component (for click detection)

3.2 Create World Space Canvas (for UI)

1. Right-click on AgentPrefab > UI > Canvas
2. Set Canvas Render Mode to World Space
3. Scale Canvas: 0.01, 0.01, 0.01
4. Position above character: Y = 2

3.3 Add UI Elements to Canvas

AgentPrefab
├── Capsule (or Model)
├── Canvas (World Space)
│   ├── NameLabel (TextMeshPro)
│   │   └── Position: (0, 50, 0)
│   │   └── Text: "Agent Name"
│   │   └── Font Size: 24
│   │   └── Alignment: Center
│   │
│   ├── PersonalityLabel (TextMeshPro)
│   │   └── Position: (0, 30, 0)
│   │   └── Font Size: 16
│   │
│   ├── HPBar (Slider)
│   │   └── Position: (0, 10, 0)
│   │   └── Width: 100, Height: 10
│   │   └── Min: 0, Max: 1, Value: 1
│   │
│   ├── EnergyBar (Slider)
│   │   └── Position: (0, -5, 0)
│   │   └── Width: 100, Height: 10
│   │
│   └── SpeechBubble (Panel)
│       └── Position: (0, 80, 0)
│       └── Set Active: false (hidden by default)
│       ├── Background (Image)
│       │   └── Color: White with alpha
│       └── SpeechText (TextMeshPro)
│           └── Font Size: 14
│           └── Color: Black

3.4 Attach AgentController Script

1. Select AgentPrefab
2. Add Component > AgentController
3. Drag UI elements to the corresponding slots:
   • Name Label → NameLabel object
   • HP Bar → HPBar slider
   • Energy Bar → EnergyBar slider
   • Speech Bubble → SpeechBubble panel
   • Speech Text → SpeechText TextMeshPro

3.5 Create Prefab

1. Drag AgentPrefab from Hierarchy to Assets/Prefabs folder
2. Delete the instance from scene

---

Step 4: Setup Scene Hierarchy

Create the following structure in your main scene:

Scene
├── Main Camera
├── Directional Light
├── NetworkManager (Empty GameObject)
│   └── Attach: NetworkManager.cs
│
├── GameManager (Empty GameObject)
│   └── Attach: GameManager.cs
│
├── AgentContainer (Empty GameObject)
│   └── This will hold spawned agents
│
└── UI Canvas (Screen Space - Overlay)
    ├── ConnectionStatus (TextMeshPro)
    ├── TickInfo (TextMeshPro)
    ├── GoldDisplay (TextMeshPro)
    ├── ResetButton (Button)
    ├── CommandInput (TMP InputField)
    ├── SendButton (Button)
    └── NotificationPanel (Panel)
        └── NotificationText (TextMeshPro)

---

Step 5: Configure Components

NetworkManager Configuration

1. Select NetworkManager object
2. In Inspector:
   • Server URL: ws://localhost:8080/ws
   • Auto Connect: ✓ (checked)
   • Username: Your player name

GameManager Configuration

1. Select GameManager object
2. In Inspector:
   • Agent Prefab: Drag your AgentPrefab
   • Agent Container: Drag AgentContainer object
   • Spawn Positions: Set positions for agents
     • Element 0: (-3, 0, 0)
     • Element 1: (0, 0, 0)
     • Element 2: (3, 0, 0)
   • Drag all UI references

---

Step 6: Test the Setup

1. Start Python Backend:

   cd the-island
   python run.py
   

2. Play Unity Scene:

   • Press Play in Unity Editor
   • Check Console for connection messages
   • Agents should spawn when data arrives

3. Test Commands:

   • Click on an agent to feed them
   • Use the command input to send check or feed Jack
   • Watch speech bubbles appear when agents talk

---

Troubleshooting

"NativeWebSocket not found"

• Ensure the package is installed correctly
• Check Package Manager for errors

"No agents spawning"

• Verify Python backend is running on port 8080
• Check NetworkManager server URL
• Look for connection errors in Console

"Speech bubbles not showing"

• Ensure SpeechBubble reference is assigned
• Check that the agent is alive (dead agents don't speak)

"Click not working on agents"

• Add Collider component to agent prefab
• Ensure Main Camera has Physics Raycaster component

---

Script API Reference

NetworkManager

// Send commands
NetworkManager.Instance.FeedAgent("Jack");
NetworkManager.Instance.CheckStatus();
NetworkManager.Instance.ResetGame();
NetworkManager.Instance.SendCommand("custom command");

// Events
NetworkManager.Instance.OnAgentsUpdate += (agents) => { };
NetworkManager.Instance.OnAgentSpeak += (data) => { };

GameManager

// Get agent by ID or name
AgentController agent = GameManager.Instance.GetAgent(1);
AgentController jack = GameManager.Instance.GetAgentByName("Jack");

// Properties
int gold = GameManager.Instance.PlayerGold;
int alive = GameManager.Instance.AliveAgentCount;

AgentController

// Update stats
agent.UpdateStats(agentData);

// Show speech
agent.ShowSpeech("Hello!");

// Properties
bool isAlive = agent.IsAlive;
AgentData data = agent.CurrentData;