npc-clients-unity/Documentation/README.md

# GumYum NPC SDK for Unity

Welcome to the GumYum NPC SDK for Unity! This SDK allows you to integrate AI-powered NPCs with deterministic spawning and dynamic dialogue into your Unity games.

## Features

- **API Key Authentication**: Simple setup with API keys from the GumYum dashboard
- **Deterministic NPC Spawning**: Spawn the same NPCs with the same seed
- **Filtered Spawning**: Spawn NPCs based on profession, location, personality type, and more
- **OpenAI-Compatible Chat**: Use familiar chat completion APIs
- **Mood System**: NPCs have dynamic moods that change based on conversations
- **Streaming Support**: Real-time streaming of NPC responses
- **Unity Coroutine Support**: Seamless integration with Unity's async patterns
- **Conversation History**: Maintain context across multiple interactions

## Quick Start

### 1. Installation

1. Import the GumYum NPC package from the Unity Asset Store
2. The package will be installed in `Assets/GumYumNPC/`

### 2. Get API Credentials

1. Sign up at https://npc.gumyum.com
2. Navigate to your dashboard
3. Create a new API key pair
4. Copy your public and secret keys

### 3. Basic Setup

Add the GumYumUnityClient to your scene:

```csharp
using GumYum.NPC.Unity;

public class GameManager : MonoBehaviour
{
    private GumYumUnityClient client;
    
    void Start()
    {
        // Get the singleton instance
        client = GumYumUnityClient.Instance;
        
        // Set your API credentials
        client.SetCredentials("your-public-key", "your-secret-key");
        
        // Start spawning NPCs!
        StartCoroutine(SpawnMyFirstNPC());
    }
    
    IEnumerator SpawnMyFirstNPC()
    {
        // Spawn a random NPC from the "blade-runner" universe
        yield return client.SpawnNPCCoroutine("blade-runner", 42, null, npc =>
        {
            if (npc != null)
            {
                Debug.Log($"Spawned {npc.Name} the {npc.Profession}!");
            }
        });
    }
}
```

### 4. Chat with NPCs

```csharp
IEnumerator ChatWithNPC(NPC npc, string message)
{
    yield return client.SimpleChatCoroutine(npc, message, response =>
    {
        if (response != null)
        {
            Debug.Log($"{npc.Name}: {response}");
        }
    });
}
```

## Examples

The SDK includes several example scenes in the `Samples~` folder:

1. **Basic Chat**: Simple NPC spawning and chat interface
2. **Advanced Features**: Filtered spawning, mood transitions, and streaming

To import samples:
1. Open Package Manager (Window > Package Manager)
2. Find GumYum NPC SDK
3. Click on "Samples" and import the examples you want

## Advanced Usage

### Filtered NPC Spawning

```csharp
// Spawn a female warrior or knight from the barracks
var filters = new Dictionary<string, object>
{
    ["profession"] = new[] { "warrior", "knight" },
    ["location"] = new[] { "barracks" },
    ["sex"] = new[] { "female" }
};

yield return client.SpawnFilteredNPCCoroutine("kingdom", 12345, filters, npc =>
{
    if (npc != null)
    {
        Debug.Log($"Spawned filtered NPC: {npc.GetInfo()}");
    }
});
```

### Mood Transitions

NPCs have dynamic moods that change based on conversations:

```csharp
// Check mood before conversation
string previousMood = npc.GetMood();

// Have a conversation...
yield return ChatWithNPC(npc, "I have terrible news!");

// Check if mood changed
if (npc.HasMoodChanged())
{
    Debug.Log($"Mood changed from {npc.GetPreviousMood()} to {npc.GetMood()}");
    Debug.Log($"Reason: {npc.GetLastMoodChangeReason()}");
}
```

### Streaming Responses

For real-time chat experiences:

```csharp
var messages = new List<ChatMessage>
{
    new ChatMessage { Role = "user", Content = "Tell me a story" }
};

// Enable streaming in the chat call
yield return client.ChatCoroutine(npc, messages, response =>
{
    // Final response received
}, temperature: 0.8, maxTokens: 2000);

// Listen to streaming events
npc.DialogueChunkReceived += (sender, chunk) =>
{
    // Update UI with each chunk as it arrives
    chatText.text += chunk;
};
```

### Async/Await Support

The SDK also supports modern C# async patterns:

```csharp
async Task SpawnAndChatAsync()
{
    var npc = await client.NPCs.SpawnAsync("blade-runner", 42);
    
    var messages = new List<ChatMessage>
    {
        new ChatMessage { Role = "user", Content = "Hello!" }
    };
    
    var response = await npc.Chat.CompletionsAsync(messages);
    Debug.Log(response.Choices[0].Message.Content);
}
```

## API Reference

### GumYumUnityClient

- `SetCredentials(apiKey, apiSecret)`: Set API credentials
- `SpawnNPCCoroutine(universeId, seed, npcId, callback)`: Spawn an NPC
- `SpawnFilteredNPCCoroutine(universeId, seed, filters, callback)`: Spawn filtered NPC
- `ChatCoroutine(npc, messages, callback, temperature, maxTokens)`: Chat with NPC
- `SimpleChatCoroutine(npc, message, callback, temperature, maxTokens)`: Simple chat helper

### NPC Class

- `Name`, `Profession`, `PersonalityType`: NPC properties
- `GetMood()`, `GetStressLevel()`: Current state
- `Chat.CompletionsAsync(messages)`: Chat with the NPC
- `ChatWithHistoryAsync(message)`: Chat with conversation history
- `SaveToServerAsync(customName)`: Save NPC for later retrieval

## Best Practices

1. **Singleton Usage**: Use `GumYumUnityClient.Instance` for a single client across your game
2. **Error Handling**: Always check if NPCs are null after spawning
3. **API Keys**: Never commit API keys to source control. Use environment variables or Unity's secret management
4. **Coroutines**: Use coroutines for better Unity integration, especially for UI updates
5. **Mood Awareness**: Design conversations considering NPC mood states

## Troubleshooting

### NPCs not spawning
- Check your API credentials are correct
- Ensure you have an active internet connection
- Check the Unity console for error messages

### Mood not changing
- Not all messages trigger mood changes
- Mood transitions depend on NPC personality and context
- Check `HasMoodChanged()` after conversations

### Performance issues
- Use appropriate max_tokens limits
- Consider implementing response caching
- Use streaming for long responses

## Support

- Documentation: https://docs.gumyum.com/sdk/unity
- Discord: https://discord.gg/gumyum
- Email: support@gumyum.com

## License

This SDK is licensed under the MIT License. See LICENSE file for details.