# Unity-AI Bridge SDK Specification
## 1. Introduction
The Unity-AI Bridge SDK provides a clean, consistent API for bidirectional communication between Unity games and AI assistants. This SDK enables any Unity code to communicate with AI assistants by writing to named results, which can then be retrieved by the AI through the MCP interface.
## 2. Design Goals
The SDK is designed with the following goals in mind:
1. **Simplicity**: Provide a simple, intuitive API for Unity developers
2. **Flexibility**: Allow any Unity code to communicate with AI assistants
3. **Consistency**: Use consistent terminology and patterns throughout
4. **Discoverability**: Make it easy to discover available results
5. **Persistence**: Ensure results are persisted across sessions
6. **Performance**: Minimize overhead and resource usage
7. **Thread Safety**: Ensure thread-safe operation in Unity's environment
## 3. Core Concepts
### 3.1 Results
The central concept in the SDK is the " result\. A result can be:
1. **Operation Result**: Generated by executing code or queries through MCP
2. **Named Result**: Created by Unity code using the SDK
Results are identified by either:
- A unique ID (for operation results)
- A name (for named results)
### 3.2 Result Operations
The SDK supports the following operations on results:
1. **Write**: Replace the current value of a result
2. **Append**: Add data to a result (useful for logs or progress updates)
3. **Read**: Retrieve the current value of a result
4. **Clear**: Remove a result's data
5. **List**: Discover available results
### 3.3 Persistence
Results are persisted to disk to ensure they survive:
- Unity Editor restarts
- Game restarts
- Crashes
This persistence ensures that AI assistants can retrieve results even if Unity has been restarted.
## 4. SDK Structure
The SDK consists of the following components:
1. **AI Static Class**: The main entry point for the SDK
2. **Result Class**: Represents a named result that can be manipulated
3. **ResultStorage Class**: Handles storage and retrieval of results
4. **MCP Integration**: Connects the SDK to the Model Context Protocol
These components work together to provide a seamless experience for both Unity developers and AI assistants.
## 5. Related Documents
- [API Reference](./02-api-reference.md): Detailed documentation of the SDK's API
- [Usage Examples](./03-usage-examples.md): Examples of how to use the SDK in Unity code
- [MCP Integration](./04-mcp-integration.md): How the SDK integrates with the Model Context Protocol
- [Implementation Details](./05-implementation-details.md): Technical details of the SDK's implementation