-
Notifications
You must be signed in to change notification settings - Fork 295
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1213 from CesiumGS/install-instructions
Add install instructions for normal releases and for pre-releases
- Loading branch information
Showing
2 changed files
with
70 additions
and
38 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,61 @@ | ||
# Using Pre-Release Packages | ||
|
||
Cesium for Unreal has a continous integration (CI) system that automatically builds an installable version of the plugin for every commit in every branch. You can download and install these yourself to try out new features before they're released. | ||
|
||
_Before you begin, **back up your project**. Cesium for Unreal can not guarantee that levels saved with a pre-release version will be loadable in other versions of the plugin._ | ||
|
||
* [Download a pre-release version from a Pull Request](#download-a-pre-release-version-from-a-pull-request) | ||
* [Download a pre-release version from a Branch or Commit](#download-a-pre-release-version-from-a-branch-or-commit) | ||
|
||
## Download a pre-release version from a Pull Request | ||
|
||
To download a pre-release version built from a pull request, click the "Checks" tab at the top of the pull request: | ||
|
||
<img width="601" alt="image" src="https://github.com/CesiumGS/cesium-unreal/assets/130494071/ff3bd8fd-3990-4f4c-93b2-7127fee1633b"> | ||
|
||
Then click the "Cesium for Unreal on: push" link: | ||
|
||
<img width="320" alt="image" src="https://github.com/CesiumGS/cesium-unreal/assets/130494071/a75fa7bf-bb2b-4fa7-ada7-7d1a894817be"> | ||
|
||
And scroll down to the Artifacts section: | ||
|
||
<img width="387" alt="image" src="https://github.com/CesiumGS/cesium-unreal/assets/924374/f2e57962-2bdf-4623-9856-a969378ceca2"> | ||
|
||
If there is no Artifacts section on that page, it's probably because the CI run is still in progress. Artifacts don't appear until the build is complete. | ||
|
||
Find the appropriate ZIP file for your version of Unreal Engine. For example, `CesiumForUnreal-52-*.zip` is for Unreal Engine 5.2. Note that artifacts that name a platform will _only_ work on that platform, while artifacts without any platform in the name will work on _all_ platforms that Cesium for Unreal supports. So in most cases you should download an artifact without any platform in its name. | ||
|
||
Once you've downloaded the appropriate ZIP, move on to [installing a Cesium for Unreal ZIP](#installing-a-cesium-for-unreal-zip). | ||
|
||
## Download a pre-release version from a branch or commit | ||
|
||
To download a pre-release version built from a branch (or a commit), click the green check ✔️ at the top of the list of files in the branch: | ||
|
||
<img width="706" alt="image" src="https://github.com/CesiumGS/cesium-unreal/assets/130494071/e072f73d-3405-4f00-b2c9-f22872d8e93f"> | ||
|
||
Click any of the Details links that appear: | ||
|
||
<img width="394" alt="image" src="https://github.com/CesiumGS/cesium-unreal/assets/130494071/7dd341c6-87dd-45f5-8a93-562e5bc27c6e"> | ||
|
||
Then click the Summary link: | ||
|
||
<img width="420" alt="image" src="https://github.com/CesiumGS/cesium-unreal/assets/130494071/8b4a238d-514d-45e3-8954-13a869d67b56"> | ||
|
||
And scroll down to the Artifacts section: | ||
|
||
<img width="387" alt="image" src="https://github.com/CesiumGS/cesium-unreal/assets/924374/f2e57962-2bdf-4623-9856-a969378ceca2"> | ||
|
||
If there is no Artifacts section on that page, it's probably because the CI run is still in progress. Artifacts don't appear until the build is complete. | ||
|
||
Find the appropriate ZIP file for your version of Unreal Engine. For example, `CesiumForUnreal-52-*.zip` is for Unreal Engine 5.2. Note that artifacts that name a platform will _only_ work on that platform, while artifacts without any platform in the name will work on _all_ platforms that Cesium for Unreal supports. So in most cases you should download an artifact without any platform in its name. | ||
|
||
Once you've downloaded the appropriate ZIP, move on to [installing a Cesium for Unreal ZIP](#installing-a-cesium-for-unreal-zip). | ||
|
||
## Installing a Cesium for Unreal ZIP | ||
|
||
Once you've download a pre-release ZIP file using one of the methods above, you can install it into your Unreal Engine as follows: | ||
|
||
1. If you previously installed the Cesium for Unreal plugin via the Unreal Engine Marketplace, uninstall it first. | ||
2. Find Unreal Engine's `Engine/Plugins/Marketplace` directory. For example, on Unreal Engine 5.2 on Windows, this is typically `C:\Program Files\Epic Games\UE_5.2\Engine\Plugins\Marketplace`. You may need to create the `Marketplace` directory yourself. | ||
3. If the `CesiumForUnreal` subdirectory already exists in this `Marketplace` directory, delete it first to make sure you're getting a clean installation. | ||
4. Extract the release ZIP into this `Marketplace` directory. If you've done this correctly, you'll find a `CesiumForUnreal` sub-directory inside the `Marketplace` directory. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -41,47 +41,18 @@ Cesium for Unreal is tightly integrated with Unreal Engine making it possible to | |
|
||
[Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0.html). Cesium for Unreal is free for both commercial and non-commercial use. | ||
|
||
### :package: Accessing Packaged Plugin | ||
### :package: Installing Cesium for Unreal | ||
|
||
The easiest way to access Cesium for Unreal is by downloading officially released versions from the [Unreal Engine Marketplace](https://cesium.com/unreal-marketplace?utm_source=cesium-unreal&utm_medium=github&utm_campaign=unreal). | ||
The easiest way to install Cesium for Unreal is by downloading the officially released version from the [Unreal Engine Marketplace](https://cesium.com/unreal-marketplace?utm_source=cesium-unreal&utm_medium=github&utm_campaign=unreal). | ||
|
||
If you would like to access pre-release, development versions of the plugin, Cesium for Unreal has Travis CI integration that prepares packages with each CI build. To access these packages, click the ✔️ icon on the GitHub branch or commit and click the `Details` next to `plugin-package-combined`. You can extract the downloaded plugin package into your Unreal project's `Plugins` directory. | ||
You can also find all releases on the [Releases](https://github.com/CesiumGS/cesium-unreal/releases) page. This is useful if you want an older version, or if you can't or don't want to use the Unreal Engine Marketplace. In particular, if you're using Linux, the Releases page is a better option. To install any of these releases: | ||
|
||
### :computer: Developing with Unreal Engine | ||
|
||
See the [Developer Setup Guide](Documentation/developer-setup.md) to learn how to set up a development environment for Cesium for Unreal, allowing you to compile it, customize it, and contribute to its development. | ||
|
||
<!-- #### :hammer_and_wrench: Compiling Cesium for Unreal | ||
The following steps detail how to build the plugin and use it as part of your projects. You can also compile Cesium for Unreal as part of the [`cesium-unreal-samples`](https://github.com/CesiumGS/cesium-unreal-samples.git). | ||
Cesium for Unreal depends on Cesium's high-precision geospatial C++ library - [Cesium Native](https://github.com/CesiumGS/cesium-native), which is included as a submodule. | ||
1. Clone the repository using `git clone --recursive [email protected]:CesiumGS/cesium-unreal.git`. | ||
2. From the `cesium-unreal/extern` directory, run the following commands to build `cesium-native`. | ||
1. If you previously installed the Cesium for Unreal plugin via the Unreal Engine Marketplace, uninstall it. | ||
2. Extract the release ZIP to Unreal Engine's `Engine/Plugins/Marketplace` directory. For example, on Unreal Engine 5.2 on Windows, this is typically `C:\Program Files\Epic Games\UE_5.2\Engine\Plugins\Marketplace`. You may need to create the `Marketplace` directory yourself. | ||
3. If you've done this correctly, you'll find a `CesiumForUnreal` sub-directory inside the `Marketplace` directory, and the plugin is ready to use. | ||
|
||
* CMake configuration and build on Windows platform: | ||
You can also [use pre-release packages](Documentation/using-prerelease-packages.md). | ||
|
||
```cmd | ||
cmake -B build -S . -G "Visual Studio 15 2017 Win64" # Optionally use "Visual Studio 16 2019" | ||
cmake --build build --config Release --target install # Can optionally compile with --config RelWithDebInfo or MinSizeRel. | ||
cmake --build build --config Debug --target install # Optional, recommended for debugging | ||
``` | ||
* CMake configuration and build on Linux platform: | ||
```cmd | ||
export UNREAL_ENGINE_DIR=<path_to_unreal_engine> | ||
export UNREAL_ENGINE_COMPILER_DIR=$UNREAL_ENGINE_DIR/Engine/Extras/ThirdPartyNotUE/SDKs/HostLinux/Linux_x64/v17_clang-10.0.1-centos7/x86_64-unknown-linux-gnu | ||
export UNREAL_ENGINE_LIBCXX_DIR=$UNREAL_ENGINE_DIR/Engine/Source/ThirdParty/Linux/LibCxx | ||
# Release build | ||
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE="unreal-linux-toolchain.cmake" -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DCMAKE_BUILD_TYPE=Release | ||
cmake --build build --target install | ||
# Debug build | ||
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE="unreal-linux-toolchain.cmake" -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DCMAKE_BUILD_TYPE=Debug | ||
cmake --build build --target install | ||
``` | ||
### :computer: Developing with Unreal Engine | ||
|
||
3. Point your Unreal Engine Project to the `CesiumForUnreal.uplugin` file to load the plugin into Unreal Engine. --> | ||
See the [Developer Setup Guide](Documentation/developer-setup.md) to learn how to set up a development environment for Cesium for Unreal, allowing you to compile it, customize it, and contribute to its development. |