Integrating Rust Plugins in Unity

1. What Are Native Plugins in Unity?

Before we begin, let's quickly clarify what a native plugin is in the context of Unity.

As the video explains, Unity can load libraries of native code compiled from languages like C++ or, in our case, Rust. The key requirement is that the library must expose a C-style interface, which is precisely what we achieved in the last lesson with extern "C" and #[no_mangle].

2. Setting Up Your Unity Project

First, you'll need a Unity project to host our game. Since you have experience with Unity, this should be straightforward.

1. Open the Unity Hub.
2. Create a new project using Unity 2022.3.6f1 (or a compatible 2022.3 version).
3. Select the 3D (URP) template for a modern rendering pipeline, which will be useful for visuals later.
4. Name your project something like LifeSimGame and choose a location for it.

Once the project is created and opened, you can proceed to the next step.

3. Importing the Rust Library

Unity has a special folder for native plugins. For Unity to automatically find and load our Rust library, we must place it inside a folder named Plugins located in the Assets directory.

Step 1: Create the Plugins Folder

In your Unity project window, navigate to the Assets folder. Right-click and select Create > Folder, then name it Plugins. Your project structure should now look like this: Assets/Plugins.

Step 2: Copy the Library File

Now, locate the dynamic library file you compiled in the last lesson. You'll find it in your Rust project's target/debug/ directory.

• On Windows: game_engine_core.dll
• On macOS: libgame_engine_core.dylib
• On Linux: libgame_engine_core.so

Copy the appropriate file from that directory and paste it into the Assets/Plugins folder you just created in Unity.

An Important Note for macOS Users:
As mentioned in the "Getting started with FFI: Rust & Unity" guide, Unity on macOS expects native library files to have a .bundle extension. After copying libgame_engine_core.dylib into your Plugins folder, you should rename it to game_engine_core.bundle. Unity will handle the rest. This step is not necessary for Windows or Linux.

4. Configuring the Plugin in the Inspector

After you copy the library file into the Plugins folder, Unity will import it. Click on the library file inside the Unity Editor to open its Import Settings in the Inspector window. This is where you tell Unity how and on which platforms to use your plugin.

Here are the key settings to configure:

1. Select platforms for plugin:

   • Uncheck "Any Platform". If you're building on and for a 64-bit Windows machine, you should only check "Editor" and "Standalone".
   • Under the platform settings (e.g., the Windows logo tab), ensure the CPU is set to x86_64 (for 64-bit). The debug build you created is likely for your current machine's architecture.

2. Platform-specific settings:

   • Click on the tab corresponding to your operating system (e.g., the Windows icon, the Apple icon).
   • Make sure the "Editor" and "Standalone" platforms are checked, and the CPU architecture matches your build (x86_64).

3. Load on startup:

   • Ensure this option is checked. This tells Unity to load your Rust library into memory as soon as the game starts.

4. The "Restart Required" Warning:

   • You will see a warning that native plugins are not unloaded until the editor is restarted. This is extremely important. If you make changes to your Rust code and recompile the library, you must close and reopen the Unity Editor for the changes to take effect. Forgetting this step is a very common source of confusion.

After configuring the settings, click the Apply button at the bottom of the Inspector.

Conclusion

That's it! You have successfully imported your Rust-based game engine as a native plugin into your Unity project. Unity is now aware of your library and will load it on startup.

Key Takeaways:

• Unity loads native libraries from the Assets/Plugins folder.
• You must copy your compiled .dll, .so, or .dylib file into this folder. On macOS, you should rename .dylib files to .bundle.
• The Import Settings in the Inspector are used to specify target platforms (e.g., Windows x64) and load behavior for the plugin.
• Crucially, any changes to the Rust library require a full restart of the Unity Editor to be loaded.

While the plugin is loaded, our C# scripts don't yet know how to communicate with it. In our next lesson, "Call Rust functions from C# scripts in Unity using P/Invoke," we will bridge this final gap. We'll create a C# script and use the DllImport attribute to call the create_game_state, level_up, and get_level functions we defined in Rust, seeing the two halves of our application communicate for the very first time.