UnityUDP/README.md

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:

git clone <repository-url>
cd unityudp

2. Install dependencies:

flutter pub get

3. Generate JSON serialization code:

dart run build_runner build --delete-conflicting-outputs

4. Run the app:

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