docs/unreal_custenv.md
This page contains the complete instructions start to finish for setting up Unreal environment with AirSim. The Unreal Marketplace has several environment available that you can start using in just few minutes. It is also possible to use environments available on websites such as turbosquid.com or cgitrader.com with bit more effort (here's tutorial video). In addition there also several free environments available.
Below we will use a freely downloadable environment from Unreal Marketplace called Landscape Mountain but the steps are same for any other environments.
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.
Make sure AirSim is built and Unreal 4.27 is installed as described in build instructions.
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).
Open LandscapeMountains.uproject, it should launch the Unreal Editor.
!!!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 4.27 or greater 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.
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.
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`.
Edit the LandscapeMountains.uproject so that it looks like this
{
"FileVersion": 3,
"EngineAssociation": "4.27",
"Category": "Samples",
"Description": "",
"Modules": [
{
"Name": "LandscapeMountains",
"Type": "Runtime",
"LoadingPhase": "Default",
"AdditionalDependencies": [
"AirSim"
]
}
],
"TargetPlatforms": [
"MacNoEditor",
"WindowsNoEditor"
],
"Plugins": [
{
"Name": "AirSim",
"Enabled": true
}
]
}
Edit the Config\DefaultGame.ini to add the following line at the end:
+MapsToCook=(FilePath="/AirSim/AirSimAssets")
Doing this forces Unreal to include all necessary AirSim content in packaged builds of your project.
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.
!!!tip
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.
Reopen LandscapeMountains.sln in Visual Studio, and make sure "DebugGame Editor" and "Win64" build configuration is the active build configuration.
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
In Window/World Settings as shown below, set the GameMode Override to AirSimGameMode:
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.
Be sure to Save these edits. Hit the Play button in the Unreal Editor. See how to use AirSim.
Congratulations! You are now running AirSim in your own Unreal environment.
By default AirSim prompts user for which vehicle to use. You can easily change this by setting SimMode. Please see using car guide.
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:
git pull in your AirSim repo followed by build.cmd (or ./build.sh for Linux users).Unreal Marketplace has dozens of prebuilt extra-ordinarily detailed environments ranging from Moon to Mars and everything in between. The one we have used for testing is called Modular Neighborhood Pack but you can use any environment. Another free environment is Infinity Blade series. 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!).
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".
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.
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.
In this case, create a new blank C++ project with no Starter Content and add your environment in to it.
Copy the Unreal\Plugins folder from the build you did in the above section into the root of your Unreal project's folder. In your Unreal project's .uproject file, add the key AdditionalDependencies to the "Modules" object
as we showed in the LandscapeMountains.uproject above.
"AdditionalDependencies": [
"AirSim"
]
and the Plugins section to the top level object:
"Plugins": [
{
"Name": "AirSim",
"Enabled": true
}
]