# Unity Exposed Bindings ### High-Performance Unity Internal Bindings for Zero-Allocation Operations

## Overview `com.cosminb.unity-internals` is a high-performance Unity library that exposes internal bindings to enable zero-allocation operations using `Span` and `NativeArray`. This package allows direct interaction with Unity's native code methods, eliminating managed array overhead for critical performance-sensitive operations. ## How It Works This library uses a sophisticated build pipeline to safely expose Unity's internal methods: ``` Runtime~/ (Source Code) → ProcessAssembly.sh → Compilation → Cecil IL Injection → ExposedBindings.dll ``` 1. **Source Code** (`Runtime~/`): Contains C# extension methods and stub implementations 2. **ProcessAssembly.sh**: Orchestrates the build process 3. **Compilation**: Creates a standard .NET assembly 4. **Cecil Processing**: Injects IL code to call Unity's internal `_Injected` methods 5. **Final DLL**: The processed assembly with direct native bindings The `Runtime~` folder (with `~` suffix) prevents Unity from compiling the source directly, as the code requires Cecil processing to function properly. ## Key Features - **Zero-Allocation Image Loading**: Load textures directly from `Span` or `NativeArray` - **Optimized AssetBundle Loading**: Load asset bundles without unnecessary memory allocations - **Cross-Platform Compatibility**: Tested on Android, WebGL, macOS, Windows, Linux, and iOS - **IL2CPP Support**: Seamless integration with development and release builds - **Minimal Performance Overhead**: Utilizes Mono.Cecil for efficient method exposure ## Requirements - Unity 6000.0.31f1 or later - .NET 6.0 SDK (for Cecil processing) - Mono.Cecil NuGet package ## Installation ### Option 1: Install via Git URL (Recommended) Unity Package Manager supports installing packages from Git subfolders using the `?path=` parameter: 1. Open Unity Package Manager (Window > Package Manager) 2. Click the `+` button and select "Add package from git URL" 3. Enter: ``` https://github.com/Cosmin-B/unity-native-exposed-bindings.git?path=Assets/Packages/com.cosminb.unity-internals ``` Alternatively, add directly to your `Packages/manifest.json`: ```json { "dependencies": { "com.cosminb.unity-internals": "https://github.com/Cosmin-B/unity-native-exposed-bindings.git?path=Assets/Packages/com.cosminb.unity-internals" } } ``` ### Option 2: Local Installation #### Via Package Manager: 1. Clone or download this repository 2. Open Unity Package Manager 3. Click `+` → "Add package from disk" 4. Navigate to `Assets/Packages/com.cosminb.unity-internals/package.json` #### Manual Copy: 1. Clone or download this repository 2. Copy `Assets/Packages/com.cosminb.unity-internals` to either: - Your project's `Packages/` folder (recommended) - Your project's `Assets/` folder ### Post-Installation: Processing the Assembly **Note:** The package includes a pre-built `ExposedBindings.dll` that works with Unity 6000.0.31f1+. If you need to rebuild for a different Unity version: 1. Copy `ProcessAssembly.sh` and `CecilProcessor/` from this repository to your project root 2. Run: ```bash chmod +x ProcessAssembly.sh ./ProcessAssembly.sh ``` ## Usage Examples ```csharp using Unity.Collections; using ExposedBindings; // Load texture from NativeArray NativeArray imageData = ...; Texture2D texture = new Texture2D(2, 2); bool success = texture.LoadImageNative(imageData); // Load AssetBundle from Span Span bundleData = ...; var request = AssetBundleExtensions.LoadFromMemoryAsyncSpan(bundleData); ``` ## Technical Implementation The library uses Mono.Cecil to: - Recreate Unity's internal `ManagedSpanWrapper` - Replace stub method bodies - Enable direct access to Unity's internal methods - Minimize runtime performance impact ## Compatibility - **Platforms**: Android, WebGL, macOS, Windows, Linux, iOS - **Build Types**: Mono and IL2CPP - **Unity Version**: 6000.0.31f1 and later ## Performance Benefits - Reduced GC pressure - Eliminated array copying overhead - Direct NativeArray usage in Jobs - Potential Burst compatibility ## Why Cecil Over Reflection? Unlike reflection-based approaches, this library uses Mono.Cecil for IL injection because: - **Zero Runtime Overhead**: IL injection happens at build time, not runtime - **No Allocations**: Direct method calls without boxing/unboxing - **Burst Compatible**: Potential for Burst compilation (reflection blocks this) - **IL2CPP Safe**: Works seamlessly with IL2CPP builds - **Performance**: Direct native calls without reflection overhead ## Limitations - **Unity Version Dependency**: Internal method signatures can change between Unity versions - **Cecil Processing Required**: Must run ProcessAssembly.sh after package updates - **Blittable Types Only**: Only supports types that can be directly mapped to memory - **No Multi-dimensional Arrays**: Limited to single-dimensional arrays - **Platform Testing Required**: Test on each target platform before shipping ## Safety & Compatibility ⚠️ **Important: Unity's internal layouts can change between major AND minor versions!** - Always test thoroughly after Unity updates - Rebuild the assembly when upgrading Unity versions - The CecilProcessor may need adjustments for new Unity versions - Consider maintaining version-specific branches for different Unity releases ## Building from Source (For Contributors) If you want to modify the library or rebuild for a different Unity version: ### Prerequisites 1. Clone this repository 2. Ensure you have .NET 6.0 SDK installed 3. Unity 6000.0.31f1 or your target version installed ### Building the Assembly ```bash # Make the script executable chmod +x ProcessAssembly.sh # Run the processor ./ProcessAssembly.sh ``` This will: - Build the CecilProcessor from source - Compile the source code from `Runtime~/` - Process the assembly with Cecil to inject IL code - Output `ExposedBindings.dll` to the `Plugins/` folder ### Customizing for Different Unity Versions 1. Update Unity path in `ProcessAssembly.sh` if needed 2. Modify `CecilProcessor/Program.cs` if internal signatures changed 3. Test thoroughly on your target Unity version ### Build and Distribution (For Maintainers) 1. Process assembly with Cecil 2. Include processed assembly in `Plugins/` 3. Update `package.json` version 4. Create GitHub release 5. Publish to UPM registry (optional) ## Credits & Inspiration This project is inspired by Sebastian Schöner's excellent blog post: [Unmanaging Unity](https://blog.s-schoener.com/2024-11-02-unmanaging-unity/) **Key insights from Sebastian's work:** - Unity's internal `ManagedSpanWrapper` structure for zero-copy operations - The existence of `_Injected` methods that accept spans directly - How Unity's internal marshalling works with native code **Our improvements:** - Using Mono.Cecil for compile-time IL injection instead of runtime reflection - Full IL2CPP compatibility without runtime overhead - Cleaner API with extension methods - Comprehensive platform testing ## Extending the Library Want to expose more Unity internal methods? Check out our [guide on extending internals](https://github.com/Cosmin-B/unity-native-exposed-bindings/blob/main/Docs/extending-internals.md) which covers: - Finding Unity's internal methods - Understanding IL injection with Cecil - Adding new exposed methods - Testing and compatibility ## License MIT License - See LICENSE file for details ## Author Cosmin Bararu