1. 项目概述为什么需要Unity Native Scripting如果你在Unity开发中遇到过性能瓶颈比如处理海量数据、复杂物理模拟或者高频次的对象更新那么你肯定对C#脚本的局限性深有体会。虽然C#和Burst编译器已经很强但在某些需要直接操作内存、调用特定硬件指令或者与底层C/C库深度集成的场景下C依然是无可替代的选择。这就是Unity Native Scripting原生脚本的用武之地。它允许你在Unity项目中直接编写C代码编译成动态链接库DLL或SO然后在C#中通过P/Invoke调用从而将计算密集型任务从托管环境C#转移到非托管环境C实现性能的飞跃。很多人一听到“C”、“原生插件”就觉得头大认为配置复杂、门槛高。确实传统的Native Plugin开发涉及Visual Studio项目配置、平台宏定义、复杂的构建后处理足以劝退一大批开发者。但Unity近年来不断优化这一流程通过Unity Native Scripting在Unity 2021 LTS及更高版本中集成得更好它提供了更贴近Unity编辑器工作流的开发体验。我们今天要做的就是绕开那些繁琐的步骤在15分钟内利用你熟悉的工具主要是VSCode搭建一个最小化、可运行的C脚本环境并完成一次从C到C#的“Hello World”调用。这不仅是性能优化的钥匙更是你深入理解Unity引擎与硬件之间桥梁的第一步。2. 环境准备与工具选型在开始敲代码之前把“战场”打扫干净准备好顺手的“兵器”是高效开发的前提。这个环节的目标是用最小的配置代价获得一个能够编译C代码并让Unity识别的环境。2.1 核心工具清单与安装要点你需要准备以下三样东西它们构成了我们开发环境的核心三角Unity编辑器2021.3 LTS或更高版本这是我们的主战场。建议使用LTS长期支持版本稳定性有保障。确保安装时勾选了对应平台的开发模块如Windows Build Support下的“IL2CPP”和“Windows SDK”这对于后续的编译目标很重要。Visual Studio CodeVSCode我们将用它来编写C代码。它轻量、免费并且通过强大的扩展生态系统可以完美胜任C开发。去官网下载安装即可。C编译工具链MSVC或MinGW这是将C源代码变成Unity能调用的库文件的关键。在Windows上最推荐的是使用Microsoft Visual C Build Tools。你不需要安装完整的Visual Studio IDE。注意网络上很多教程会让你安装完整的Visual Studio但对于纯C库开发来说那过于臃肿。我们只需要它的编译器MSVC和构建工具。一个常见的错误是在安装某些软件时系统提示“error: microsoft visual c 14.0 or greater is required”这其实就是缺少了MSVC的运行时库或构建工具。如何安装MSVC构建工具访问Visual Studio官网找到“下载Visual Studio”下方的“所有下载”然后选择“Visual Studio 2022生成工具”。运行安装程序在“工作负载”选项卡中仅勾选“使用C的桌面开发”。在右侧的“安装详细信息”中确保“MSVC v143 - VS 2022 C x64/x86生成工具”和“Windows 10 SDK”被选中。然后安装即可。这样你就获得了纯净的C编译环境没有IDE的干扰。2.2 VSCode的C环境配置安装好VSCode后打开它进入扩展市场CtrlShiftX搜索并安装以下两个扩展C/C(由Microsoft发布)提供代码智能感知IntelliSense、调试、浏览等功能。CMake Tools(由Microsoft发布)虽然我们第一个简单项目可能用不上CMake但它是管理复杂C项目的标准工具提前安装以备后用。安装完成后你需要告诉VSCode编译器和构建工具在哪里。按下CtrlShiftP输入“C/C: Edit Configurations (UI)”并选择。这会打开一个图形化设置界面。在“编译器路径”一项你需要定位到MSVC的cl.exe。它通常位于类似C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\版本号\bin\Hostx64\x64\cl.exe的路径下。你可以使用Everything等工具搜索cl.exe来找到确切路径。在“IntelliSense 模式”选择windows-msvc-x64。将“配置名称”设置为“MSVC”。这个配置会生成一个c_cpp_properties.json文件保存在项目根目录的.vscode文件夹下它确保了VSCode能正确识别你的C语法和头文件。2.3 创建Unity项目与规划目录结构打开Unity Hub创建一个新的3D核心模板项目命名为“NativeScriptingDemo”。项目创建好后在Assets目录下我们创建一个清晰的文件夹结构来管理原生代码这能有效避免后续的混乱Assets/ ├── Plugins/ # Unity会自动识别此文件夹下的原生插件 │ └── MyNativeCode/ │ ├── Source/ # 存放C源代码文件(.cpp, .h) │ ├── Libs/ # 存放编译好的.dll文件Windows │ └── Build/ # 存放构建脚本或临时文件 └── Scripts/ # 存放调用原生插件的C#脚本Plugins文件夹是Unity的特殊文件夹其下的原生库文件会根据平台自动加载。我们将C源码放在Source下将编译生成的DLL手动或自动拷贝到Libs下对应平台的子文件夹例如x86_64中。3. 编写第一个C原生函数环境就绪现在让我们切入正题编写第一个C函数。这个函数将非常简单但会包含Native Scripting的几个关键要素。3.1 头文件.h的编写定义接口契约在Assets/Plugins/MyNativeCode/Source/下创建一个名为NativeCalculator.h的头文件。头文件的作用是声明函数接口供C#端调用。// NativeCalculator.h #pragma once // 防止头文件被重复包含 // 使用 extern C 来禁止C的名称修饰name mangling // 确保C#能通过一个简单的函数名找到它。 extern C { // 声明一个简单的加法函数。 // __declspec(dllexport) 是Windows特有的关键字用于导出这个函数 // 使其在生成的DLL中可见。其他平台如macOS、Linux有不同语法。 __declspec(dllexport) int Add(int a, int b); // 声明一个返回字符串的函数。注意在C和C#间传递字符串需要小心内存管理。 // 这里我们返回一个指向常量字符的指针。 __declspec(dllexport) const char* GetGreeting(); }关键点解析extern C这是最关键的一步。C编译器为了支持函数重载会对函数名进行“修饰”例如Add可能变成_Z3Addii。extern C告诉编译器按C语言的方式处理函数名保持名称不变C#才能通过[DllImport]按名称正确链接。__declspec(dllexport)这是Windows平台MSVC编译器导出动态库函数的语法。如果你要为macOSClang编译则需要使用__attribute__((visibility(default)))。为了简化我们首攻Windows平台。函数签名使用C语言风格的基本数据类型int,float,char*等它们与C#的类型有明确的映射关系简化了交互。3.2 源文件.cpp的实现编写具体逻辑在同一个目录下创建NativeCalculator.cpp源文件实现头文件中声明的函数。// NativeCalculator.cpp #include NativeCalculator.h #include string // 用于std::string // 实现加法函数 int Add(int a, int b) { return a b; } // 实现获取问候语函数 const char* GetGreeting() { // 注意这里返回了一个字面量字符串的指针它在程序的整个生命周期内有效是安全的。 // 但如果你需要动态构建字符串并返回则需要考虑内存分配和释放策略 // 通常由C分配内存并提供一个专门的“释放内存”函数供C#调用。 static std::string greeting Hello from Native C!; return greeting.c_str(); // c_str()返回一个指向字符串内容的只读指针 }这个实现非常简单。Add函数就是普通的加法。GetGreeting函数稍微需要注意我们使用了一个静态的std::string来存储字符串然后返回其C风格字符串指针c_str()。因为静态变量在程序生命周期内存在所以这个指针在DLL被加载期间始终有效。这是一种安全的返回字符串方式。4. 编译C代码生成动态链接库DLL有了源代码下一步就是把它变成Unity能加载的.dll文件。我们将使用命令行手动编译这能让你最清楚地理解整个过程。4.1 使用MSVC命令行编译打开**“开始”菜单**找到“Visual Studio 2022”文件夹下面有一个“x64 Native Tools Command Prompt for VS 2022”或者x86版本根据你的目标平台选择。务必使用这个命令行因为它已经设置好了所有MSVC编译所需的环境变量如cl.exe、link.exe的路径。在打开的命令行中使用cd命令导航到你的C源代码目录cd D:\YourUnityProject\Assets\Plugins\MyNativeCode\Source然后执行编译命令cl /LD /EHsc NativeCalculator.cpp /FeNativeCalculator.dll命令拆解clMSVC C编译器。/LD告诉编译器生成一个动态链接库DLL。/EHsc指定C异常处理模型。NativeCalculator.cpp要编译的源文件。/FeNativeCalculator.dll指定输出的DLL文件名。如果一切顺利你会在当前目录下看到新生成的NativeCalculator.dll动态库和NativeCalculator.lib导入库静态链接时用我们暂时不用管它。4.2 将DLL放置到Unity可识别的位置编译成功后需要将NativeCalculator.dll放到Unity项目的正确位置。根据我们之前规划的目录在Assets/Plugins/MyNativeCode/下创建一个名为x86_64的文件夹对应64位Windows平台然后将NativeCalculator.dll复制进去。最终的路径应该是Assets/Plugins/MyNativeCode/x86_64/NativeCalculator.dllUnity在构建Windows平台项目时会自动将Plugins文件夹下对应平台子目录如x86_64中的DLL文件打包到最终的游戏数据包中并在运行时加载。5. 在C#中调用C原生函数DLL就位现在轮到C#脚本上场了。我们将创建一个C#脚本来充当“桥梁”调用我们刚刚编写的C函数。5.1 使用DllImport特性声明外部函数在Assets/Scripts/文件夹下创建一个新的C#脚本命名为NativeCaller.cs。// NativeCaller.cs using System; using System.Runtime.InteropServices; // 必须引入此命名空间 using UnityEngine; public class NativeCaller : MonoBehaviour { // 1. 使用DllImport特性声明C函数 // NativeCalculator 对应我们DLL的文件名不含扩展名。 // EntryPoint Add 指定了DLL中确切的函数名。如果C#方法名与之一致可省略。 [DllImport(NativeCalculator)] private static extern int Add(int a, int b); [DllImport(NativeCalculator)] private static extern IntPtr GetGreeting(); // 注意字符串返回类型是IntPtr // 2. 一个辅助方法将IntPtr安全地转换为C#字符串 private static string PtrToStringUtf8(IntPtr ptr) { if (ptr IntPtr.Zero) return string.Empty; // 使用Marshal.PtrToStringUTF8 (在.NET 5/Unity 2021.2 可用) // 对于旧版本可以使用 Marshal.PtrToStringAnsi但需确保编码一致。 return Marshal.PtrToStringUTF8(ptr); } void Start() { // 3. 调用C函数并打印结果 int sum Add(5, 3); Debug.Log($C Add(5, 3) {sum}); IntPtr greetingPtr GetGreeting(); string greeting PtrToStringUtf8(greetingPtr); Debug.Log($C Says: {greeting}); } }关键点解析[DllImport(NativeCalculator)]这是连接C#和C的桥梁。特性中的字符串是DLL的名称不需要.dll扩展名。Unity会在特定路径如Plugins文件夹下查找这个DLL。static extern声明的方法必须是静态static和外部extern的表明其实现存在于外部DLL中。数据类型映射int映射int这很直接。但const char*在C#中需要映射为IntPtr一个代表指针或句柄的结构。我们不能直接映射为string因为C#的string是托管对象内存管理方式与C不同。字符串处理我们通过GetGreeting()拿到一个IntPtr然后使用Marshal.PtrToStringUTF8将其转换为C#的string。Marshal类提供了在托管和非托管代码之间转换数据的一系列方法。5.2 在Unity中测试运行在Unity编辑器的场景中创建一个空的GameObject。将NativeCaller脚本拖拽到该GameObject上作为组件。点击运行按钮。如果一切配置正确你将在Unity的Console窗口中看到两条日志C Add(5, 3) 8 C Says: Hello from Native C!恭喜你已经成功完成了从C#到C的第一次调用。这个过程虽然简单但包含了Native Scripting的所有核心步骤环境配置、C编码、编译、部署和C#调用。6. 进阶处理复杂数据与内存管理简单的整数和字符串返回只是开始。在实际项目中我们经常需要传递数组、结构体或者需要在C中分配内存并在C#中释放。这里涉及到更复杂但至关重要的内存管理问题。6.1 传递和返回数组假设我们需要一个C函数来计算一个浮点数数组的总和。直接传递托管数组的指针是危险的因为垃圾回收器GC可能会移动内存。更安全的做法是在C#中将数组复制到一块非托管内存中将指针传给C计算完毕后再将结果复制回来。C端 (NativeCalculator.cpp):extern C { __declspec(dllexport) float SumArray(float* array, int length) { if (array nullptr || length 0) return 0.0f; float sum 0.0f; for (int i 0; i length; i) { sum array[i]; } return sum; } // 一个修改传入数组的函数原地操作 __declspec(dllexport) void ScaleArray(float* array, int length, float scale) { for (int i 0; i length; i) { array[i] * scale; } } }C#端 (NativeCaller.cs):[DllImport(NativeCalculator)] private static extern float SumArray(IntPtr arrayPtr, int length); [DllImport(NativeCalculator)] private static extern void ScaleArray(IntPtr arrayPtr, int length, float scale); void TestArrayOperations() { float[] managedArray { 1.0f, 2.0f, 3.0f, 4.0f, 5.0f }; int size managedArray.Length; // 1. 在非托管堆上分配内存 int totalSize Marshal.SizeOf(typeof(float)) * size; IntPtr unmanagedArrayPtr Marshal.AllocHGlobal(totalSize); // 2. 将托管数组的数据复制到非托管内存 Marshal.Copy(managedArray, 0, unmanagedArrayPtr, size); // 3. 调用C函数 float sum SumArray(unmanagedArrayPtr, size); Debug.Log($Sum of array: {sum}); ScaleArray(unmanagedArrayPtr, size, 2.0f); // 4. 将结果从非托管内存复制回托管数组 Marshal.Copy(unmanagedArrayPtr, managedArray, 0, size); Debug.Log($Scaled array: [{string.Join(, , managedArray)}]); // 5. 务必释放非托管内存 Marshal.FreeHGlobal(unmanagedArrayPtr); }核心要点Marshal.AllocHGlobal在非托管堆上分配一块内存返回其指针IntPtr。Marshal.Copy用于在托管数组和非托管内存指针之间复制数据。Marshal.FreeHGlobal释放分配的非托管内存。这是必须的否则会导致内存泄漏。这种方式C#分配、C#释放将内存管理的责任完全放在C#端是最清晰、最不容易出错的方式。另一种方式是由C分配内存并返回指针但那样就需要C#在拿到数据后再调用一个C函数去释放内存流程更复杂。6.2 传递和返回结构体当需要传递多个相关数据时使用结构体比传递多个单独参数更高效、更清晰。需要确保C和C#中的结构体布局完全一致。定义共同的结构体首先在C头文件和C#代码中定义内存布局完全一致的结构体。可以使用[StructLayout(LayoutKind.Sequential)]特性来强制C#使用顺序布局并可以用[MarshalAs]特性来指定字符串等成员的编码。C端 (NativeCalculator.h):#pragma pack(push, 1) // 确保1字节对齐防止编译器插入填充字节导致布局不一致 struct Vector3Data { float x; float y; float z; }; #pragma pack(pop) extern C { __declspec(dllexport) Vector3Data NormalizeVector(Vector3Data vec); }C#端 (NativeCaller.cs):[StructLayout(LayoutKind.Sequential)] // 顺序布局 public struct Vector3Data { public float x; public float y; public float z; } [DllImport(NativeCalculator)] private static extern Vector3Data NormalizeVector(Vector3Data vec); void TestStruct() { Vector3Data myVec new Vector3Data { x 3.0f, y 4.0f, z 0.0f }; Vector3Data normalized NormalizeVector(myVec); Debug.Log($Normalized: ({normalized.x}, {normalized.y}, {normalized.z})); // 预期输出: (0.6, 0.8, 0) }对齐Alignment与填充Padding这是传递结构体时最常见的坑。不同的编译器和平台可能有不同的默认对齐规则。使用#pragma pack(push, 1)和[StructLayout(LayoutKind.Sequential, Pack 1)]可以强制使用1字节对齐即无填充确保双方布局一致。对于包含指针或复杂类型的结构体处理起来会更加复杂。7. 构建自动化与跨平台考量手动编译和拷贝DLL在开发初期可以接受但随着项目迭代这会变得非常低效且容易出错。我们需要引入自动化。7.1 使用CMake管理C项目CMake是一个跨平台的构建系统生成器。我们可以编写一个CMakeLists.txt文件来描述如何构建我们的C库然后让CMake为我们生成Visual Studio项目文件、Makefile等并执行编译。在Assets/Plugins/MyNativeCode/Source/目录下创建CMakeLists.txtcmake_minimum_required(VERSION 3.10) project(NativeCalculator LANGUAGES CXX) # 设置C标准 set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED ON) # 创建动态库 add_library(NativeCalculator SHARED NativeCalculator.cpp NativeCalculator.h) # 针对Windows平台设置导出宏避免在头文件中写死__declspec(dllexport) if(WIN32) target_compile_definitions(NativeCalculator PRIVATE NATIVE_CALCULATOR_EXPORTS) set_target_properties(NativeCalculator PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${CMAKE_SOURCE_DIR}/../Libs/$CONFIG_$PLATFORM_NAME LIBRARY_OUTPUT_DIRECTORY ${CMAKE_SOURCE_DIR}/../Libs/$CONFIG_$PLATFORM_NAME ) endif()这个CMake脚本做了几件事定义了项目名称和语言。设置了C11标准。将NativeCalculator.cpp和.h文件编译成一个名为NativeCalculator的动态库SHARED。在Windows上定义了一个预处理器宏NATIVE_CALCULATOR_EXPORTS。这样我们可以修改头文件使其在编译DLL时导出函数在引用DLL时导入函数。将输出目录设置为../Libs/下的一个子目录该子目录包含构建配置Debug/Release和平台名称。对应的我们需要修改NativeCalculator.h使其更通用// NativeCalculator.h #pragma once #ifdef _WIN32 #ifdef NATIVE_CALCULATOR_EXPORTS #define NATIVE_API __declspec(dllexport) #else #define NATIVE_API __declspec(dllimport) #endif #else #define NATIVE_API __attribute__((visibility(default))) #endif extern C { NATIVE_API int Add(int a, int b); NATIVE_API const char* GetGreeting(); // ... 其他函数 }现在你可以使用CMake命令行工具在Source目录下创建一个构建目录如build然后运行cmake ..和cmake --build .来编译项目。编译好的DLL会自动输出到Libs文件夹下对应的子目录中。7.2 编写Unity Editor脚本实现自动拷贝为了让Unity在编译前自动触发C项目的构建和DLL拷贝我们可以编写一个Editor脚本利用[InitializeOnLoadMethod]特性或[PostProcessBuild]属性。一个更简单的方案是在C#脚本中使用DllImport时如果DLL不在默认位置我们可以监听Unity的PlayModeStateChange事件在进入播放模式前将最新编译的DLL从Libs目录拷贝到Plugins下的正确平台文件夹。或者你可以使用更强大的构建后处理脚本在构建玩家版本Build Player时确保正确的DLL被包含在构建中。这通常涉及到操作BuildPipeline和检查PluginImporter的设置。7.3 跨平台编译宏与条件编译一个成熟的原生插件需要支持多平台Windows, macOS, Android, iOS等。我们的头文件已经通过#ifdef _WIN32做了初步的平台判断。在CMake或构建脚本中你需要为每个平台调用对应的编译工具链如Android NDK、Xcode。在Unity项目中你需要为每个平台准备对应的二进制文件Windows用.dll macOS用.bundle Linux用.so Android用.so iOS用.a静态库或.framework并放置在Plugins文件夹下对应的子目录中如Assets/Plugins/x86_64/,Assets/Plugins/Android/,Assets/Plugins/iOS/。Unity在构建时会自动选择正确的文件。在C#的DllImport中你可以使用条件编译来指定不同平台的库名#if UNITY_EDITOR_WIN || UNITY_STANDALONE_WIN private const string DllName NativeCalculator; #elif UNITY_EDITOR_OSX || UNITY_STANDALONE_OSX private const string DllName __Internal; // macOS上有时需要这样写 #elif UNITY_ANDROID private const string DllName nativecalculator; // Android的.so库名 #else private const string DllName NativeCalculator; #endif [DllImport(DllName)] private static extern int Add(int a, int b);8. 调试C Native Plugin调试是开发过程中不可或缺的一环。调试运行在Unity进程内的C代码需要将Unity编辑器或播放器作为调试目标附加到C调试器上。8.1 使用Visual Studio附加调试使用Visual Studio非VSCode虽然我们开发用VSCode但调试C DLLVisual Studio的调试器更强大。打开包含你C项目的Visual Studio解决方案可以由CMake生成。编译Debug版本的DLL确保你的C项目编译的是Debug配置它包含了完整的符号信息.pdb文件。启动Unity并加载场景运行你的Unity项目进入播放模式。在Visual Studio中附加到进程在Visual Studio的菜单中选择“调试” - “附加到进程”。在进程列表中找到Unity.exe编辑器模式或你的游戏进程名独立构建模式选择它并将“附加到”选项设置为“本机代码”。在C代码中设置断点在Visual Studio中打开你的C源文件在你感兴趣的函数如Add内部设置断点。在Unity中触发调用在Unity中执行调用该C函数的操作例如点击一个按钮或Start函数中自动调用。命中断点如果一切设置正确Unity进程会暂停Visual Studio会跳转到断点处你可以查看变量、调用堆栈进行单步调试。8.2 使用VSCode进行调试配置更复杂VSCode也可以配置为调试器但配置过程相对复杂。你需要创建一个launch.json配置文件指定调试类型为cppvsdbgWindows或cppdbg其他并提供正确的程序路径Unity编辑器路径和符号路径。对于刚上手Native Scripting的开发者建议先从Visual Studio的图形化调试开始待流程熟悉后再研究VSCode的配置。8.3 日志输出与错误处理在无法方便断点调试时如在某些最终构建版本中日志是重要的排错手段。在C代码中不能直接使用printf或std::cout因为Unity控制台看不到这些输出。有几种替代方案输出到系统调试器在Windows上可以使用OutputDebugStringA()函数输出信息可以被Visual Studio的“输出”窗口或专门的调试工具如DebugView捕获。#include Windows.h // 仅Windows void DebugLog(const char* message) { OutputDebugStringA(message); OutputDebugStringA(\n); }将日志传回C#定义一个C函数接受字符串参数然后在C#端实现这个函数将字符串转发到Unity的Debug.Log。这需要C#端先注册一个回调函数给C。// C端声明一个函数指针类型和设置函数 typedef void (*LogCallback)(const char*); extern C { __declspec(dllexport) void SetDebugLogCallback(LogCallback callback); } // 在C内部调用这个callback来发送日志。// C#端 [UnmanagedFunctionPointer(CallingConvention.Cdecl)] public delegate void DebugLogCallback(string message); [DllImport(NativeCalculator)] private static extern void SetDebugLogCallback(DebugLogCallback callback); [MonoPInvokeCallback(typeof(DebugLogCallback))] private static void OnNativeLog(string message) { Debug.Log($[Native]: {message}); } // 在Start中调用SetDebugLogCallback(OnNativeLog);这种方式更复杂但能实现最统一的日志体验。错误处理在C函数中对于非法参数或内部错误不要直接崩溃如访问空指针。应该设计错误码返回机制或者通过上述日志回调将错误信息传递回C#由C#决定如何处理如抛出异常、显示错误提示。良好的错误处理是稳定性的基石。从环境搭建到第一个函数调用再到处理复杂数据、自动化构建和调试这条路径上的每一步都充满了细节。Native Scripting确实比纯C#开发更复杂但它带来的性能提升和对底层系统的控制力是解决特定高性能需求场景的终极武器。花时间掌握它意味着你打开了Unity高端应用开发的一扇新大门。