diff --git a/Documentation/using-prerelease-packages.md b/Documentation/using-prerelease-packages.md new file mode 100644 index 000000000..8992e2abe --- /dev/null +++ b/Documentation/using-prerelease-packages.md @@ -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: + +image + +Then click the "Cesium for Unreal on: push" link: + +image + +And scroll down to the Artifacts section: + +image + +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: + +image + +Click any of the Details links that appear: + +image + +Then click the Summary link: + +image + +And scroll down to the Artifacts section: + +image + +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. diff --git a/README.md b/README.md index d5df598d0..4f5acaf15 100644 --- a/README.md +++ b/README.md @@ -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. - - +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.