diff --git a/README.md b/README.md index b57a38cf..01186907 100644 --- a/README.md +++ b/README.md @@ -80,12 +80,12 @@ You can also find the presentation of the live tutorial of Cosys-AirSim at ANNSI Some more details on our changes can be found in the [changelog](https://github.com/Cosys-Lab/Cosys-AirSim/blob/main/CHANGELOG.md). ## How to Get It -This branch uses a custom Unreal Engine version! Please read the documentation carefully. - -### Windows +#### Download and install from precompiled plugin - Windows/Linux +* [Download and install it](https://cosys-lab.github.io/install_precompiled) +#### Install and use from source - Windows * [Install/Build it](https://cosys-lab.github.io/install_windows) -### Linux +#### Install and use from source - Linux * [Install/Build it](https://cosys-lab.github.io/install_linux) ## How to Use It diff --git a/docs/README.md b/docs/README.md index b57a38cf..01186907 100644 --- a/docs/README.md +++ b/docs/README.md @@ -80,12 +80,12 @@ You can also find the presentation of the live tutorial of Cosys-AirSim at ANNSI Some more details on our changes can be found in the [changelog](https://github.com/Cosys-Lab/Cosys-AirSim/blob/main/CHANGELOG.md). ## How to Get It -This branch uses a custom Unreal Engine version! Please read the documentation carefully. - -### Windows +#### Download and install from precompiled plugin - Windows/Linux +* [Download and install it](https://cosys-lab.github.io/install_precompiled) +#### Install and use from source - Windows * [Install/Build it](https://cosys-lab.github.io/install_windows) -### Linux +#### Install and use from source - Linux * [Install/Build it](https://cosys-lab.github.io/install_linux) ## How to Use It diff --git a/docs/install_precompiled.md b/docs/install_precompiled.md new file mode 100644 index 00000000..77edc2eb --- /dev/null +++ b/docs/install_precompiled.md @@ -0,0 +1,8 @@ +# Download and install precompiled Plugin + +If you wish to not build the plugin from source, you can download the precompiled plugin from the [releases page](https://github.com/Cosys-Lab/Cosys-AirSim/releases) for the right version of Unreal you are using. +It does not come with a environment so you will need to create your own Unreal project. Follow this [step-by-step guide](unreal_custenv.md). + +The releases page also comes with additional downloads and links to the several API implementations for ROS(2) and the Python and Matlab API clients for that specific version of the Cosys-AirSim plugin. + + diff --git a/docs/unreal_blocks.md b/docs/unreal_blocks.md index 2c21a7ee..5aa36d0d 100644 --- a/docs/unreal_blocks.md +++ b/docs/unreal_blocks.md @@ -1,38 +1,36 @@ # Setup Blocks Environment for AirSim -Blocks environment is available in repo in folder `Unreal/Environments/Blocks` and is designed to be lightweight in size. That means its very basic but fast. +Blocks environment is available in repo in folder `Unreal/Environments/Blocks` and is designed to be lightweight in size. That means it is very basic but fast. Here are quick steps to get Blocks environment up and running: -## Windows +## Windows from Source 1. Make sure you have [built or installed Unreal and built AirSim](install_windows.md). 2. Navigate to folder `AirSim\Unreal\Environments\Blocks` and run `update_from_git.bat`. 3. Double click on generated .sln file to open in Visual Studio. -4. Make sure `Blocks` project is the startup project, build configuration is set to `DebugGame_Editor` and `Win64`. Hit F5 to run. -5. Press the Play button in Unreal Editor and you will see something like in below video. Also see the other documentation for how to use it. +4. Make sure `Blocks` project is the startup project, build configuration is set to `DevelopmentEditor_Editor` and `Win64`. Hit F5 to run. +5. Press the Play button in Unreal Editor. Also see the other documentation for how to use it. ### Changing Code and Rebuilding For Windows, you can just change the code in Visual Studio, press F5 and re-run. There are few batch files available in folder `AirSim\Unreal\Environments\Blocks` that lets you sync code, clean etc. -## Linux +## Linux from Source 1. Make sure you have [built or installed the Unreal Engine and AirSim](install_linux.md). 2. Navigate to folder `AirSim\Unreal\Environments\Blocks` and run `update_from_git.sh`. 3. Navigate to your UnrealEngine repo folder and run `Engine/Binaries/Linux/UE4Editor` which will start Unreal Editor. 4. On first start you might not see any projects in UE4 editor. Click on Projects tab, Browse button and then navigate to `AirSim/Unreal/Environments/Blocks/Blocks.uproject`. -5. If you get prompted for incompatible version and conversion, select In-place conversion which is usually under "More" options. If you get prompted for missing modules, make sure to select No so you don't exit. +5. If you get prompted for incompatible version and conversion, select In-place conversion which is usually under "More" options. If you get prompted for missing modules, make sure to select _No_, so you don't exit. 6. Finally, when prompted with building AirSim, select Yes. Now it might take a while so go get some coffee :). -7. Press the Play button in Unreal Editor and you will see something like in below video. Also see the other documentation for how to use it. - -[![Blocks Demo Video](images/blocks_video.png)](https://www.youtube.com/watch?v=-r_QGaxMT4A) +7. Press the Play button in Unreal Editor. Also see the other documentation for how to use it. ### Changing Code and Rebuilding For Linux, make code changes in AirLib or Unreal/Plugins folder and then run `./build.sh` to rebuild. This step also copies the build output to Blocks sample project. You can then follow above steps again to re-run. -## Chosing Your Vehicle: Car or Multirotor -By default AirSim spawns multirotor. You can easily change this to car and use all of AirSim goodies. Please see [using car](using_car.md) guide. +## Choosing Your Vehicle: Car or Multirotor +By default, AirSim spawns multirotor. You can easily change this to car and use all of AirSim goodies. Please see [using car](using_car.md) guide. ## FAQ -#### I see warnings about like "_BuitData" file is missing. -These are intermediate files and you can safely ignore it. +#### I see warnings about like "_BuiltData" file is missing. +These are intermediate files and, you can safely ignore it. diff --git a/docs/unreal_custenv.md b/docs/unreal_custenv.md index 455c5d24..70366df0 100644 --- a/docs/unreal_custenv.md +++ b/docs/unreal_custenv.md @@ -1,19 +1,78 @@ # Creating and Setting Up Unreal Environment -This page contains the complete instructions start to finish for setting up Unreal environment with AirSim. The Unreal Marketplace has [several environment](https://www.unrealengine.com/marketplace/content-cat/assets/environments) available that you can start using in just few minutes. It is also possible to use environments available on websites such as [turbosquid.com](https://www.turbosquid.com/) or [cgitrader.com](https://www.cgtrader.com/) with bit more effort (here's [tutorial video](https://www.youtube.com/watch?v=y09VbdQWvQY&feature)). In addition there also several [free environments](https://github.com/Microsoft/AirSim/issues/424) available. +This page contains the complete instructions start to finish for setting up Unreal environment with AirSim. The Unreal Marketplace has [several environment](https://www.unrealengine.com/marketplace/content-cat/assets/environments) available that you can start using in just few minutes. It is also possible to use environments available on websites such as [turbosquid.com](https://www.turbosquid.com/) or [cgtrader.com](https://www.cgtrader.com/) with bit more effort (here's [tutorial video](https://www.youtube.com/watch?v=y09VbdQWvQY&feature)). In addition, there also several [free environments](https://github.com/Microsoft/AirSim/issues/424) available. Below we will use a freely downloadable environment from Unreal Marketplace called Landscape Mountain but the steps are same for any other environments. ## Note for Linux Users There is no `Epic Games Launcher` for Linux which means that if you need to create custom environment, you will need Windows machine to do that. Once you have Unreal project folder, just copy it over to your Linux machine. -## Step by Step Instructions +## Step-by-Step Instructions when using Cosys-AirSim from Precompiled Binaries +1. It is assumed you downloaded the right precompiled Cosys-AirSim plugin from the [GitHub releases page](https://github.com/Cosys-Lab/Cosys-AirSim/releases) for the right Unreal version. +2. In `Epic Games Launcher` click the Samples tab then scroll down and find `Landscape Mountains`. Click the `Create Project` and download this content (~2GB download). -1. Make sure AirSim is built and Unreal 5.4.2 is installed as described in [the install instructions](install_windows.md). -2. In `Epic Games Launcher` click the Learn tab then scroll down and find `Landscape Mountains`. Click the `Create Project` and download this content (~2GB download). + ![current version](images/landscape_mountains.png) + +3. Open `LandscapeMountains.uproject`, it should launch the Unreal Editor. + + ![unreal editor](images/unreal_editor.png) + + !!!note + + The Landscape Mountains project is supported up to Unreal Engine version 4.24. If you do not have 4.24 installed, you should see a dialog titled `Select Unreal Engine Version` with a dropdown to select from installed versions. Select 5.4.2 to migrate the project to a supported engine version. If you have 4.24 installed, you can manually migrate the project by navigating to the corresponding .uproject file in Windows Explorer, right-clicking it, and selecting the `Switch Unreal Engine version...` option. + +4. Go to the `LandscapeMountains` project folder and create a new subfolder called `Plugins`. Now copy the precompiled AirSim Plugin folder into this newly created folder. This way now your own Unreal project has AirSim plugin. + +5. Edit the `LandscapeMountains.uproject` so that you add the AirSim plugin to the list of plugins to load. + + ```json + { + ... + "Plugins": [ + { + "Name": "AirSim", + "Enabled": true + } + ] + ... + } + ``` + +6. Edit the `Config\DefaultGame.ini` to add the following lines at the end: + + ``` + +MapsToCook=(FilePath="/AirSim/AirSimAssets") + +DirectoriesToAlwaysCook=(Path="/AirSim/HUDAssets") + +DirectoriesToAlwaysCook=(Path="/AirSim/Beacons") + +DirectoriesToAlwaysCook=(Path="/AirSim/Blueprints") + +DirectoriesToAlwaysCook=(Path="/AirSim/Models") + +DirectoriesToAlwaysCook=(Path="/AirSim/Sensors") + +DirectoriesToAlwaysCook=(Path="/AirSim/StarterContent") + +DirectoriesToAlwaysCook=(Path="/AirSim/VehicleAdv") + +DirectoriesToAlwaysCook=(Path="/AirSim/Weather") + ``` + + Doing this forces Unreal to include all necessary AirSim content in packaged builds of your project. + +7. If using Unreal Engine 5.3/5.4 check [here](#unreal-5354-scene-camera-bug) for a fix to the camera scene rendering bug in these engine versions! + +8. Close the `Unreal Editor` and restart it by opening the uproject file again. + +9. In `Window/World Settings` as shown below, set the `GameMode Override` to `AirSimGameMode`: + + ![sim_game_mode.png](images/sim_game_mode.png) + +10. Go to 'Edit->Editor Preferences' in Unreal Editor, in the 'Search' box type 'CPU' and ensure that the 'Use Less CPU when in Background' is unchecked. If you don't do this then UE will be slowed down dramatically when UE window loses focus. + +11. Be sure to `Save` these edits. Hit the Play button in the Unreal Editor. See the other documentation pages for how to use it. + +## Step-by-Step Instructions when using Cosys-AirSim from Source Build + +1. Make sure AirSim is built and Unreal 5.4.2 is installed as described in [the installation instructions](install_windows.md). +2. In `Epic Games Launcher` click the Samples tab then scroll down and find `Landscape Mountains`. Click the `Create Project` and download this content (~2GB download). ![current version](images/landscape_mountains.png) -1. Open `LandscapeMountains.uproject`, it should launch the Unreal Editor. +3. Open `LandscapeMountains.uproject`, it should launch the Unreal Editor. ![unreal editor](images/unreal_editor.png) @@ -21,15 +80,15 @@ There is no `Epic Games Launcher` for Linux which means that if you need to crea The Landscape Mountains project is supported up to Unreal Engine version 4.24. If you do not have 4.24 installed, you should see a dialog titled `Select Unreal Engine Version` with a dropdown to select from installed versions. Select 5.4.2 to migrate the project to a supported engine version. If you have 4.24 installed, you can manually migrate the project by navigating to the corresponding .uproject file in Windows Explorer, right-clicking it, and selecting the `Switch Unreal Engine version...` option. -1. From the `File menu` select `New C++ class`, leave default `None` on the type of class, click `Next`, leave default name `MyClass`, and click `Create Class`. We need to do this because Unreal requires at least one source file in project. It should trigger compile and open up Visual Studio solution `LandscapeMountains.sln`. +4. From the `File menu` select `New C++ class`, leave default `None` on the type of class, click `Next`, leave default name `MyClass`, and click `Create Class`. We need to do this because Unreal requires at least one source file in project. It should trigger compile and open up Visual Studio solution `LandscapeMountains.sln`. -1. Go to your folder for AirSim repo and copy `Unreal\Plugins` folder in to your `LandscapeMountains` folder. This way now your own Unreal project has AirSim plugin. +5. Go to your folder for AirSim repo and copy `Unreal\Plugins` folder in to your `LandscapeMountains` folder. This way now your own Unreal project has AirSim plugin. !!!note If the AirSim installation is fresh, i.e, hasn't been built before, make sure that you run `build.cmd` from the root directory once before copying `Unreal\Plugins` folder so that `AirLib` files are also included. If you have made some changes in the Blocks environment, make sure to run `update_to_git.bat` from `Unreal\Environments\Blocks` to update the files in `Unreal\Plugins`. -1. Edit the `LandscapeMountains.uproject` so that it looks like this +6. Edit the `LandscapeMountains.uproject` so that it looks like this ```json { @@ -60,7 +119,7 @@ There is no `Epic Games Launcher` for Linux which means that if you need to crea } ``` -1. Edit the `Config\DefaultGame.ini` to add the following lines at the end: +7. Edit the `Config\DefaultGame.ini` to add the following lines at the end: ``` +MapsToCook=(FilePath="/AirSim/AirSimAssets") @@ -76,7 +135,9 @@ There is no `Epic Games Launcher` for Linux which means that if you need to crea Doing this forces Unreal to include all necessary AirSim content in packaged builds of your project. -1. Close Visual Studio and the `Unreal Editor` and right click the LandscapeMountains.uproject in Windows Explorer and select `Generate Visual Studio Project Files`. This step detects all plugins and source files in your Unreal project and generates `.sln` file for Visual Studio. +8. If using Unreal Engine 5.3/5.4 check [here](#unreal-5354-scene-camera-bug) for a fix to the camera scene rendering bug in these engine versions! + +9. Close Visual Studio and the `Unreal Editor` and right-click the LandscapeMountains.uproject in Windows Explorer and select `Generate Visual Studio Project Files`. This step detects all plugins and source files in your Unreal project and generates `.sln` file for Visual Studio. ![regen](images/regen_sln.png) @@ -84,35 +145,34 @@ There is no `Epic Games Launcher` for Linux which means that if you need to crea If the `Generate Visual Studio Project Files` option is missing you may need to reboot your machine for the Unreal Shell extensions to take effect. If it is still missing then open the LandscapeMountains.uproject in the Unreal Editor and select `Refresh Visual Studio Project` from the `File` menu. -1. Reopen `LandscapeMountains.sln` in Visual Studio, and make sure "DebugGame Editor" and "Win64" build configuration is the active build configuration. +10. Reopen `LandscapeMountains.sln` in Visual Studio, and make sure "DebugGame Editor" and "Win64" build configuration is the active build configuration. ![build config](images/vsbuild_config.png) -1. Press `F5` to `run`. This will start the Unreal Editor. The Unreal Editor allows you to edit the environment, assets and other game related settings. First thing you want to do in your environment is set up `PlayerStart` object. In Landscape Mountains environment, `PlayerStart` object already exist and you can find it in the `World Outliner`. Make sure its location is setup as shown. This is where AirSim plugin will create and place the vehicle. If its too high up then vehicle will fall down as soon as you press play giving potentially random behavior +11. Press `F5` to `run`. This will start the Unreal Editor. The Unreal Editor allows you to edit the environment, assets and other game related settings. First thing you want to do in your environment is set up `PlayerStart` object. In Landscape Mountains environment, `PlayerStart` object already exist, and you can find it in the `World Outliner`. Make sure its location is set up as shown. This is where AirSim plugin will create and place the vehicle. If its too high up then vehicle will fall down as soon as you press play giving potentially random behavior ![lm_player_start_pos.png](images/lm_player_start_pos.png) -1. In `Window/World Settings` as shown below, set the `GameMode Override` to `AirSimGameMode`: +12. In `Window/World Settings` as shown below, set the `GameMode Override` to `AirSimGameMode`: ![sim_game_mode.png](images/sim_game_mode.png) -1. Go to 'Edit->Editor Preferences' in Unreal Editor, in the 'Search' box type 'CPU' and ensure that the 'Use Less CPU when in Background' is unchecked. If you don't do this then UE will be slowed down dramatically when UE window loses focus. +13. Go to 'Edit->Editor Preferences' in Unreal Editor, in the 'Search' box type 'CPU' and ensure that the 'Use Less CPU when in Background' is unchecked. If you don't do this then UE will be slowed down dramatically when UE window loses focus. -1. Be sure to `Save` these edits. Hit the Play button in the Unreal Editor. See the other documentation pages for how to use it. +14. Be sure to `Save` these edits. Hit the Play button in the Unreal Editor. See the other documentation pages for how to use it. Congratulations! You are now running AirSim in your own Unreal environment. -## Choosing Your Vehicle: Car or Multirotor -By default AirSim prompts user for which vehicle to use. You can easily change this by setting [SimMode](settings.md#SimMode). Please see [using car](using_car.md) guide. - -## Updating Your Environment to Latest Version of AirSim +#### Updating Your Environment to Latest Version of AirSim Once you have your environment using above instructions, you should frequently update your local AirSim code to latest version from GitHub. Below are the instructions to do this: 1. First put [clean.bat](https://github.com/Cosys-Lab/Cosys-AirSim/blob/main/Unreal/Environments/Blocks/clean.bat) (or [clean.sh](https://github.com/Cosys-Lab/Cosys-AirSim/blob/main/Unreal/Environments/Blocks/clean.sh) for Linux users) in the root folder of your environment. Run this file to clean up all intermediate files in your Unreal project. 2. Do `git pull` in your AirSim repo followed by `build.cmd` (or `./build.sh` for Linux users). 3. Replace [your project]/Plugins folder with AirSim/Unreal/Plugins folder. -4. Right click on your .uproject file and chose "Generate Visual Studio project files" option. This is not required for Linux. +4. Right-click on your .uproject file and chose "Generate Visual Studio project files" option. This is not required for Linux. +## Choosing Your Vehicle: Car or Multirotor +By default, AirSim prompts user for which vehicle to use. You can easily change this by setting [SimMode](settings.md#SimMode). Please see [using car](using_car.md) guide. ## Unreal 5.3/5.4 Scene camera bug Note that Unreal 5.3 and 5.4 breaks camera scene rendering when Effects is not set to the Epic scalability preset. You can use the console command r.DetailMode 2 to fix this at runtime! @@ -139,14 +199,14 @@ r.DetailMode=2 ## FAQ #### What are other cool environments? -[Unreal Marketplace](https://www.unrealengine.com/marketplace) has dozens of prebuilt extra-ordinarily detailed [environments](https://www.unrealengine.com/marketplace/content-cat/assets/environments) ranging from Moon to Mars and everything in between. The one we have used for testing is called [Modular Neighborhood Pack](https://www.unrealengine.com/marketplace/modular-neighborhood-pack) -but you can use any environment. Another free environment is [Infinity Blade series](https://www.unrealengine.com/marketplace/infinity-blade-plain-lands). Alternatively, if you look under the Learn tab in Epic Game Launcher, you will find many free samples that you can use. One of our favorites is "A Boy and His Kite" which is a 100 square miles of highly detailed environment (caution: you will need *very* beefy PC to run it!). +[Unreal Marketplace](https://www.unrealengine.com/marketplace) has dozens of prebuilt extraordinarily detailed [environments](https://www.unrealengine.com/marketplace/content-cat/assets/environments) ranging from Moon to Mars and everything in between. The one we have used for testing is called [Modular Neighborhood Pack](https://www.unrealengine.com/marketplace/modular-neighborhood-pack) +but you can use any environment. Another free environment is [Infinity Blade series](https://www.unrealengine.com/marketplace/infinity-blade-plain-lands). Alternatively, if you look under the Learn tab in Epic Game Launcher, you will find many free samples that you can use. One of our favorites is "A Boy and His Kite" which is 100 square miles of highly detailed environment (caution: you will need *very* beefy PC to run it!). #### When I press Play button some kind of video starts instead of my vehicle. If the environment comes with MatineeActor, delete it to avoid any startup demo sequences. There might be other ways to remove it as well, for example, click on Blueprints button, then Level Blueprint and then look at Begin Play event in Event Graph. You might want to disconnect any connections that may be starting "matinee". #### Is there easy way to sync code in my Unreal project with code in AirSim repo? -Sure, there is! You can find bunch of `.bat` files (for linux, `.sh`) in `AirSim\Unreal\Environments\Blocks`. Just copy them over to your own Unreal project. Most of these are quite simple and self explanatory. +Sure, there is! You can find a bunch of `.bat` files (for linux, `.sh`) in `AirSim\Unreal\Environments\Blocks`. Just copy them over to your own Unreal project. Most of these are quite simple and self-explanatory. #### I get some error about map. You might have to set default map for your project. For example, if you are using Modular Neighborhood Pack, set the Editor Starter Map as well as Game Default Map to Demo_Map in Project Settings > Maps & Modes. diff --git a/docs/unreal_proj.md b/docs/unreal_proj.md index 09e89d6e..3131d03f 100644 --- a/docs/unreal_proj.md +++ b/docs/unreal_proj.md @@ -3,16 +3,12 @@ ## Setting Up the Unreal Project ### Option 1: Built-in Blocks Environment -To get up and running fast, you can use the Blocks project that already comes with AirSim. This is not very highly detailed environment to keep the repo size reasonable but we use it for various testing all the times and it is the easiest way to get your feet wet in this strange land. +To get up and running fast, you can use the Blocks project that already comes with Cosys-AirSim. This is not very highly detailed environment to keep the repo size reasonable but we use it for various testing all the times and it is the easiest way to get your feet wet in this strange land. Follow these [quick steps](unreal_blocks.md). ### Option 2: Create Your Own Unreal Environment If you want to setup photo-realistic high quality environments, then you will need to create your own Unreal project. This is little bit more involved but worthwhile! -Follow this [step-by-step guide](unreal_custenv.md). - -## Changing Code and Development Workflow -To see how you can change and test AirSim code, please read our [recommended development workflow](dev_workflow.md). - +Follow this [step-by-step guide](unreal_custenv.md). diff --git a/mkdocs.yml b/mkdocs.yml index 4fefbcf6..fe09eb4e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,9 +14,10 @@ nav: - "Home": - "Home": 'README.md' - "Changelog": 'https://github.com/Cosys-Lab/Cosys-AirSim/blob/main/CHANGELOG.md' - - "Building AirSim": - - "Install on Windows": 'install_windows.md' - - "Install on Linux": 'install_linux.md' + - "Installing AirSim": + - "Download and install from precompiled plugin": 'install_precompiled.md' + - "Install from Source on Windows": 'install_windows.md' + - "Install from Source on Linux": 'install_linux.md' - "Custom Unreal Environment": 'unreal_custenv.md' - "Using AirSim": - "Core APIs": 'apis.md'