diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..0e4ff135 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,65 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +LiveKit Unity SDK — a C# wrapper around LiveKit's Rust SDK using FFI (Foreign Function Interface) for real-time audio/video communication. Status: Developer Preview. Unity package name: `io.livekit.livekit-sdk`. + +## Build & Development Commands + +### Build FFI locally from Rust source +```bash +# Requires the client-sdk-rust~ submodule and Rust toolchain +BuildScripts~/build_ffi_locally.sh [build_type] +# Platforms: macos, android, ios +# Build types: debug (default), release +``` +- **macOS**: requires `aarch64-apple-darwin` target +- **Android**: requires `cargo-ndk` and Android NDK +- **iOS**: builds static lib (`liblivekit_ffi.a`) +- After macOS builds, Unity must be restarted to load the new dylib + +### Run tests +Tests require a local LiveKit server running: +```bash +# Install and run LiveKit server +curl -sSL https://get.livekit.io | bash +livekit-server --dev & +``` +Tests run via Unity Test Framework (game-ci/unity-test-runner in CI). Tested against Unity 6000.0.49f1 and 2023.2.20f1. Tests are in `Tests/EditMode/` and `Tests/PlayMode/`. + +## Architecture + +### FFI Bridge Pattern +The SDK wraps a Rust native library (`liblivekit_ffi`) via P/Invoke. The communication flow: + +1. **C# public API** (`Runtime/Scripts/*.cs`) — `Room`, `Participant`, `Track`, audio/video sources, data streams, RPC +2. **FFI layer** (`Runtime/Scripts/Internal/`) — serializes requests via Protocol Buffers, sends through P/Invoke to Rust +3. **Native library** (`Runtime/Plugins/ffi-*/liblivekit_ffi.*`) — Rust implementation per platform/arch + +Key internal files: +- `FFIClient.cs` — singleton managing request/response lifecycle with Rust via protobuf +- `FFIBridge.cs` — request factory +- `NativeMethods.cs` — P/Invoke declarations (`DllImport`) +- `YieldInstruction.cs` — custom awaitables for async FFI operations (coroutine-based) + +### Proto/Generated Code +`Runtime/Scripts/Proto/` contains auto-generated C# from protobuf definitions in the Rust SDK. Do not edit these files manually. + +### Native Plugins +10 platform/arch combinations in `Runtime/Plugins/ffi-{platform}-{arch}/`. These are large binary files tracked with Git LFS. The `.meta` files configure Unity platform targeting. + +### Samples +- `Samples~/Basic` — minimal connection example, also used as the CI build target +- `Samples~/Meet` — more complete multi-participant example + +### Rust Submodule +`client-sdk-rust~/` is a git submodule pointing to the shared Rust SDK. The `~` suffix tells Unity to ignore the directory. + +## Key Conventions + +- Minimum Unity version: 2021.3 +- Unsafe code is enabled via `csc.rsp` +- Assembly definitions: `livekit.unity.Runtime.asmdef`, `livekit.unity.Editor.asmdef`, plus test asmdefs +- Dependencies: `Google.Protobuf.dll` and `System.Runtime.CompilerServices.Unsafe.dll` shipped as managed plugins diff --git a/CLAUDE.md.meta b/CLAUDE.md.meta new file mode 100644 index 00000000..62f67b7d --- /dev/null +++ b/CLAUDE.md.meta @@ -0,0 +1,7 @@ +fileFormatVersion: 2 +guid: 868f1e7bf0b6845dcb5739dda687929c +TextScriptImporter: + externalObjects: {} + userData: + assetBundleName: + assetBundleVariant: diff --git a/Runtime/Scripts/Internal/FFIClient.cs b/Runtime/Scripts/Internal/FFIClient.cs index 5f83ee7b..f12ce889 100644 --- a/Runtime/Scripts/Internal/FFIClient.cs +++ b/Runtime/Scripts/Internal/FFIClient.cs @@ -143,7 +143,8 @@ private static void InitializeSdk() #endif var sdkVersion = PackageVersion.Get(); - NativeMethods.LiveKitInitialize(FFICallback, captureLogs, "unity", sdkVersion); + var deviceModel = UnityEngine.SystemInfo.deviceModel; + NativeMethods.LiveKitInitialize(FFICallback, captureLogs, "unity", sdkVersion, deviceModel); Utils.Debug("FFIServer - Initialized"); initialized = true; diff --git a/Runtime/Scripts/Internal/NativeMethods.cs b/Runtime/Scripts/Internal/NativeMethods.cs index 96a70fbd..da2dbdd9 100644 --- a/Runtime/Scripts/Internal/NativeMethods.cs +++ b/Runtime/Scripts/Internal/NativeMethods.cs @@ -24,6 +24,6 @@ internal static class NativeMethods internal extern static unsafe FfiHandleId FfiNewRequest(byte* data, int len, out byte* dataPtr, out UIntPtr dataLen); [DllImport(Lib, CallingConvention = CallingConvention.Cdecl, EntryPoint = "livekit_ffi_initialize")] - internal extern static FfiHandleId LiveKitInitialize(FFICallbackDelegate cb, bool captureLogs, string sdk, string sdkVersion); + internal extern static FfiHandleId LiveKitInitialize(FFICallbackDelegate cb, bool captureLogs, string sdk, string sdkVersion, string deviceModel); } } \ No newline at end of file diff --git a/client-sdk-rust~ b/client-sdk-rust~ index 243ed261..5a7a8a0b 160000 --- a/client-sdk-rust~ +++ b/client-sdk-rust~ @@ -1 +1 @@ -Subproject commit 243ed2611604d822a4b6765458f6394272a35b69 +Subproject commit 5a7a8a0b58862746c38642673fa1ae003c3da043