# UnityUDP

A small and simple Tool to send UDP packages over custom ports to control logic in Unity projects.

## Storage

All projects and packages are stored in a **JSON file** located in your Documents folder:
- **Windows**: `C:\Users\<YourUsername>\Documents\unityudp_projects.json`
- **macOS**: `~/Documents/unityudp_projects.json`
- **Linux**: `~/Documents/unityudp_projects.json`

Click the folder icon in the app to see the exact file location on your system.

## Getting Started

### Prerequisites

- Flutter SDK (^3.8.1)
- Dart SDK

### Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd unityudp
```

2. Install dependencies:
```bash
flutter pub get
```

3. Generate JSON serialization code:
```bash
dart run build_runner build --delete-conflicting-outputs
```

4. Run the app:
```bash
flutter run -d windows  # For Windows
flutter run -d macos    # For macOS
flutter run -d linux    # For Linux
```

## Example

Check out the `Example/` folder for a complete Unity integration example! It includes:

- **UDPCommandListener.cs**: A Unity C# script that listens for UDP commands and executes them
- **unityudp_projects.json**: Sample project with 12 ready-to-use commands (toggle objects, timers, scene control, rotation, colors)
- **README.md**: Detailed setup instructions for Unity

### Quick Start with Example

1. Copy `Example/UDPCommandListener.cs` to your Unity project's `Assets/Scripts/` folder
2. Attach it to a GameObject in your scene
3. Copy `Example/unityudp_projects.json` to your Documents folder (see Storage section above)
4. Run your Unity game and start sending commands!

The example demonstrates simple but practical commands like enabling/disabling objects, starting timers, rotating objects, changing colors, and resetting scenes.

## Usage

### Creating a Project

1. Tap the **"New Project"** button on the home screen
2. Enter a project name and UDP port number (1-65535)
3. Tap **"Save"**

### Adding UDP Packages

1. Select a project from the home screen
2. Tap the **"New Package"** button
3. Enter:
   - Package name (for identification)
   - **Broadcast Mode** (toggle on to broadcast to all devices on network)
   - **IP addresses** (add one or more target IPs, not required for broadcast)
   - Data (the content to send)
4. Tap **"Save"**

#### Broadcast Mode
Enable broadcast mode to send UDP packets to all devices on your local network. This is useful for controlling multiple Unity instances simultaneously without specifying individual IP addresses.

#### Multiple IP Addresses
Add multiple IP addresses to send the same packet to specific targets. The app will show you how many addresses received the packet successfully.

### Sending UDP Packages

1. Navigate to a project
2. Find the package you want to send
3. Tap the **"Send"** button
4. The package will be sent to:
   - All devices on the network (if broadcast mode is enabled)
   - Multiple specific IP addresses (if multiple IPs are configured)
   - A single IP address (standard mode)
5. Check the feedback message to confirm successful delivery

### Managing Projects and Packages

- **Edit Port**: Use the settings card at the top of the project screen to change the port
- **Copy Package**: Tap the menu icon (⋮) on a package and select "Copy"
- **Edit**: Tap the menu icon (⋮) and select "Edit"
- **Delete**: Tap the menu icon (⋮) and select "Delete"

## Platform Support

- ✅ Windows (Recommended)
- ✅ macOS
- ✅ Linux
- ✅ Android
- ✅ iOS
- ⚠️ Web (Storage works, but UDP is not supported in browsers)

**Note:** For full UDP functionality, run the app on desktop (Windows/macOS/Linux) or mobile platforms. Web browsers do not support raw UDP sockets due to security restrictions.

### Broadcast Mode Requirements

To use broadcast mode effectively:
- All target devices must be on the same local network (subnet)
- Your firewall must allow outbound UDP broadcast traffic
- Receiving applications must be listening on the specified port
- Some routers may block broadcast packets - check your router settings if needed

## Architecture

The app follows a clean architecture pattern with:

- **Models**: Data classes for Project and UdpPackage with JSON serialization
- **Services**: 
  - `StorageService`: Handles local persistence using SharedPreferences
  - `UdpService`: Manages UDP packet transmission
- **Screens**: 
  - `HomeScreen`: Project listing and management
  - `ProjectScreen`: Package listing, editing, and sending
- **Widgets**: Reusable dialog components for creating/editing items

## Dependencies

- `udp: ^5.0.3` - UDP networking functionality
- `shared_preferences: ^2.2.2` - Local data persistence
- `json_annotation: ^4.9.0` - JSON serialization annotations
- `build_runner: ^2.4.8` - Code generation
- `json_serializable: ^6.7.1` - JSON serialization code generation