Unity TCP Bridge

Unity TCP Bridge is a lightweight TCP socket server implementation for Unity Editor that provides networking capabilities with port management and client handling.

Features

🚀 TCP Socket Server

• Modern Architecture: Built with async/await patterns for Unity Editor
• Automatic Port Management: Smart port allocation with project-specific persistence
• Client Connection Handling: Multi-client support with proper connection management
• Socket Configuration: Optimized socket options for reliable connections

⚙️ Port Management

• Dynamic Port Allocation: Automatically finds available ports starting from default (25916)
• Project-Specific Storage: Remembers port settings per Unity project
• Port Conflict Resolution: Handles port conflicts gracefully with fallback options
• Cross-Platform Support: Works on Windows, macOS, and Linux

🔧 TCP Features

• Keep-Alive Support: Configurable socket keep-alive for stable connections
• Connection Timeout: Prevents hanging connections with configurable timeouts
• Multi-Client Support: Handles multiple simultaneous client connections
• Graceful Shutdown: Proper cleanup on Unity Editor shutdown or assembly reload

🎛️ Unity Editor Integration

• Control Window: Full-featured TCP bridge management interface (Tools > Unity TCP Bridge > Control Window)
• Status Window: Compact dockable status monitor (Tools > Unity TCP Bridge > Status Window)
• Menu Items: Quick actions via Unity menu (Tools > Unity TCP Bridge)
• Real-time Status: Live server status updates and port information
• Debug Controls: Toggle debug logging and port management tools

Installation

Requirements

• Unity 2021.3 or later

Setup

1. Add this package to your Unity project
2. The TCP server will start automatically when Unity loads
3. Check Unity Console for server startup confirmation and port information

Usage

Basic TCP Server

The TCP server starts automatically when Unity loads and listens for client connections. By default:

• Default Port: 25916 (automatically managed)
• Protocol: Basic TCP with welcome message
• Echo Server: Currently configured as an echo server (sends received data back to client)

Using the Unity Editor UI

Access the TCP Bridge controls through Unity's menu system:

1. Control Window: Tools > Unity TCP Bridge > Control Window

   • Complete server management interface
   • Real-time status monitoring
   • Server start/stop/restart controls
   • Port management and configuration
   • Debug logging controls

2. Status Window: Tools > Unity TCP Bridge > Status Window

   • Compact status display (can be docked)
   • Quick start/stop buttons
   • Shows current port and connection status

3. Menu Actions: Tools > Unity TCP Bridge > [Action]

   • Quick server operations
   • Port discovery and management
   • Debug logging toggle

Connecting to the Server

# Example using telnet (replace 25916 with actual port shown in Unity Console or UI)
telnet localhost 25916

Customizing the Protocol

The current implementation includes a basic echo server. To customize for your needs:

1. Modify the HandleClientAsync method in UnityTcpBridge.cs
2. Replace the echo logic with your custom protocol handling
3. Update the welcome message format if needed

Port Management

// Get the current port
int port = UnityTcpBridge.GetCurrentPort();

// Check if server is running
bool isRunning = UnityTcpBridge.IsRunning;

// Manually start/stop (usually automatic)
UnityTcpBridge.Start();
UnityTcpBridge.Stop();

Architecture

TCP Server Implementation

External TCP Client → Unity TCP Server → Custom Protocol Handler

Key Components

• UnityTcpBridge: Main TCP server with lifecycle management
• PortManager: Dynamic port allocation and persistence
• TcpLog: Logging utility for TCP operations

Performance Features

• Async Operations: Non-blocking I/O operations
• Connection Pooling: Efficient client connection management
• Resource Cleanup: Automatic cleanup on Unity lifecycle events

Configuration

Debug Logging

Enable detailed logging for troubleshooting:

// In Unity Editor, set this EditorPref:
EditorPrefs.SetBool("UnityTcp.DebugLogs", true);

Port Configuration

The server automatically manages ports, but you can access port management:

// Check if a port is available
bool available = PortManager.IsPortAvailable(25916);

// Get port with fallback
int port = PortManager.GetPortWithFallback();

// Discover a new port
int newPort = PortManager.DiscoverNewPort();

Development

Building from Source

1. Clone this repository
2. Open in Unity 2021.3 or later
3. The TCP server will start automatically
4. Check Unity Console for server status

Customizing the Protocol

To implement your custom TCP protocol:

1. Modify HandleClientAsync: Replace the echo server logic
2. Update Welcome Message: Change the initial handshake
3. Add Message Parsing: Implement your message format
4. Error Handling: Add appropriate error handling for your protocol

Example customization:

// In HandleClientAsync method, replace echo logic with:
while (!token.IsCancellationRequested && client.Connected)
{
    // Read client message
    int bytesRead = await stream.ReadAsync(buffer, 0, buffer.Length, token);
    if (bytesRead == 0) break;
    
    // Parse your custom message format
    string message = Encoding.UTF8.GetString(buffer, 0, bytesRead);
    
    // Process the message according to your protocol
    string response = ProcessCustomMessage(message);
    
    // Send response
    byte[] responseBytes = Encoding.UTF8.GetBytes(response);
    await stream.WriteAsync(responseBytes, 0, responseBytes.Length, token);
}

Troubleshooting

Common Issues

Port Already in Use

• The server will automatically find an alternative port
• Check Unity Console for the actual port being used
• Use PortManager.DiscoverNewPort() to force a new port

Server Won't Start

• Verify Unity project is loaded properly
• Check Unity Console for error messages
• Ensure no firewall is blocking the port

Client Can't Connect

• Verify the server is running (check Unity Console)
• Use the correct port number shown in Unity Console
• Ensure localhost connectivity

Connection Drops

• Check if client is sending data within timeout period (60 seconds default)
• Enable debug logging to see connection details
• Verify client is properly handling the welcome message

Debug Logging

Enable detailed logging to get comprehensive information about:

• Server startup and port allocation
• Client connections and disconnections
• Data transmission and errors
• Port management decisions

License

This project is licensed under the MIT License.