 |
Cesium for Unity 1.15.2
|
|
Cesium for Unity 1.15.2
|
This is a summary of the setup and workflows for developers who want to modify the Cesium for Unity plugin. If you just want to use Cesium for Unity in your own applications, see the main README.
The built Cesium for Unity Assembly will run on much older versions of .NET, including the version of Mono included in Unity. However, these very recent versions are required for the C#<->C++ interop code generator (Reinterop).
To make sure things are set up correctly, open a command-prompt (PowerShell is a good choice on Windows) and run:
dotnet --version and verify that it reports 6.0 or latercmake --version and verify that it reports 3.18 or laterClone the cesium-unity-samples (game) project anywhere you like:
Then, clone the cesium-unity (plugin) project to a folder named com.cesium.unity inside its Packages folder:
Be sure to also clone the submodules. If you forgot the --recurse-submodules option when you cloned, run git submodule update --init --recursive inside the com.cesium.unity folder.
Reinterop is a Roslyn (C# compiler) source generator that is automatically invoked by Unity while compiling the Cesium for Unity C# code, and generates C# <-> C++ interop layer.
To build Reinterop and publish it to Cesium for Unity's directory, run the following from the Packages/com.cesium.unity directory:
This should be repeated if you modify Reinterop, or if you pull new changes that modify it.
For more details, see the Reinterop README.
A common mistake is to open Unity before doing this step, which will cause Unity to delete Reinterop.dll.meta file because the Reinterop.dll file does not yet exist. Then, even after you publish Reinterop.dll, the Reinterop.dll.meta that Unity creates will be missing important information, and you'll get errors when Unity attemps to compile Cesium for Unity. If this happens to you, executing git restore Reinterop.dll.meta should fix it.
To start the Cesium for Unity build process, open the cesium-unity-samples project in the Unity Editor. Unity will automatically compile the Cesium for Unity C# source code, invoking Reinterop along the way to generate the C# and C++ source code.
At this point, you can open the sample scene and you will see GameObjects with Cesium3DTileset and other Cesium behaviors attached to them. However, the Cesium functionality will not actually work yet. Instead, you'll see errors like this in the console:
This is because the C++ code has not yet been compiled. To compile the C++ code for use in the Editor, run:
The -j14 tells CMake to build using 14 threads. A higher or lower number may be more suitable for your system.
To build a release build, use these commands instead:
Once this build/install completes, Cesium for Unity should work the next time Unity loads Cesium for Unity. You can get it to do so by either restarting the Editor, or by making a small change to any Cesium for Unity script (.cs) file in Packages/com.cesium.unity/Runtime.
When you build and run a standalone game (i.e. with File -> Build Settings... or File -> Build and Run in the Unity Editor), Unity will automatically compile Cesium for Unity for the target platform. Then, by hooking into Unity build events, Cesium for Unity will build the corresponding native code for that platform by running CMake on the command-line. This can take a few minutes, and during that time Unity's progress bar will display a message stating the location of the build log file.
You can view build progress on Windows using the following PowerShell command:
Replace build-Standalone with the name of the log file from the progress window.
Or on Linux or macOS:
If the log indicates that CMake cannot be found, make sure it is installed and in your path. Restarting Unity to pick up path changes may help. If all else fails, change "cmake" in CompileCesiumForUnityNative.cs to the full path of your CMake executable.
The cesium-unity-samples project has several scenes that help you to quickly get running with Cesium for Unity. Go to File -> Open Scene, navigate to the Scenes directory, and select one of the sample scenes.
To create a release package of Cesium for Unity, suitable to be installed with the Unity Package Manager, do the following (adjust the Unity path for your system):
On success, the built .tar.gz package is found in the root directory of the project (e.g. c:\cesium\CesiumForUnityBuildProject).
In the Unity Editor, go to Window -> General -> Test Runner. Switch to the "Play Mode" tests and click "Run All".
You can also run the Cesium for Unity tests when the plugin is installed from the Package Manager. In this case, the tests won't show up in the Test Runner by default, though. To make them appear, edit the project's Packages/manifest.json file and add the following property to the JSON:
1.12.0