Updates to this readme
July 06, 2021
- Switch licenses to APACHE-2.0 OR MIT
May 14, 2021
- Removed instructions for the 3rdParty zip file and downloader URL. This is no longer a requirement.
- Updated instructions for dependencies
- Links to full documentation
April 7-13, 2021
- Updates to the 3rdParty zip file
March 25, 2021
- Initial commit for instructions
Download and Install
This repository uses Git LFS for storing large binary files. You will need to create a Github personal access token to authenticate with the LFS service.
To install Git LFS, download the binary here: https://git-lfs.github.com/.
After installation, you will need to install the necessary git hooks with this command
git lfs install
Create a Git Personal Access Token
You will need your personal access token credentials to authenticate when you clone the repository and when downloading objects from Git LFS
Create a personal access token with the 'repo' scope.
During the clone operation, you will be prompted to enter a password. Your token will be used as the password. You will also be prompted a second time for Git LFS.
(Recommended) Verify you have a credential manager installed to store your credentials
Recent versions of Git install a credential manager to store your credentials so you don't have to put in the credentials for every request.
It is highly recommended you check that you have a credential manager installed and configured
For Linux and Mac, use the following commands to store credentials
git config --global credential.helper cache
git config --global credential.helper osxkeychain
Clone the repository
> git clone https://github.com/o3de/o3de.git Cloning into 'o3de'... # initial prompt for credentials to download the repository code # enter your Github username and personal access token remote: Counting objects: 29619, done. Receiving objects: 100% (29619/29619), 40.50 MiB | 881.00 KiB/s, done. Resolving deltas: 100% (8829/8829), done. Updating files: 100% (27037/27037), done. # second prompt for credentials when downloading LFS files # enter your Github username and personal access token Filtering content: 100% (3853/3853), 621.43 MiB | 881.00 KiB/s, done.
If you have the Git credential manager core or other credential helpers installed, you should not be prompted for your credentials anymore.
Building the Engine
Build Requirements and redistributables
- Visual Studio 2019 16.9.2 minimum (All versions supported, including Community): https://visualstudio.microsoft.com/downloads/
- Install the following workloads:
- Game Development with C++
- MSVC v142 - VS 2019 C++ x64/x86
- C++ 2019 redistributable update
- Install the following workloads:
- CMake 3.20 minimum: https://cmake.org/download/
- WWise - 2019.2.8.7432 minimum: https://www.audiokinetic.com/download/
- Note: This requires registration and installation of a client to download
- You will also need to set a environment variable:
- For example:
set LY_WWISE_INSTALL_PATH="C:\Program Files (x86)\Audiokinetic\Wwise 2019.2.8.7432"
Quick Start Build Steps
Create a writable folder to cache 3rd Party dependencies. You can also use this to store other redistributable SDKs.
For the 0.5 branch - Create an empty text file named
3rdParty.txtin this folder, to allow a legacy CMake validator to pass
Install the following redistributables to the following:
- Visual Studio and VC++ redistributable can be installed to any location
- CMake can be installed to any location, as long as it's available in the system path
- WWise can be installed anywhere, but you will need to set an environment variable for CMake to detect it:
Navigate into the repo folder, then download the python runtime with this command
For the 0.5 branch - Set this environment variable prior to the
Configure the source into a solution using this command line, replacing and <3rdParty cache path> to a path you've created:-DLY_UNITY_BUILD=ON -DLY_PROJECTS=AutomatedTesting ">
-S -G "Visual Studio 16" -DLY_3RDPARTY_PATH=<3rdParty cache path> -DLY_UNITY_BUILD=ON -DLY_PROJECTS=AutomatedTesting
Note: Do not use trailing slashes for the <3rdParty cache path>
Alternatively, you can do this through the CMake GUI:
- Select the local path of the repo under "Where is the source code"
- Select a path where to build binaries under "Where to build the binaries"
- Click "Configure"
- Wait for the key values to populate. Fill in the fields that are relevant, including
- Click "Generate"
The configuration of the solution is complete. To build the Editor and AssetProcessor to binaries, run this command inside your repo:
--target AutomatedTesting.GameLauncher AssetProcessor Editor --config profile -- /m
This will compile after some time and binaries will be available in the build path you've specified
Setting up new projects
- While still within the repo folder, register the engine with this command:
scripts\o3de.bat register --this-engine
- Setup new projects using the
o3de create-projectcommand. In the 0.5 branch, the project directory must be a subdirectory in the repo folder.
\scripts\o3de.bat create-project --project-path
- Register the engine to the project
\scripts\o3de.bat register --project-path
- Once you're ready to build the project, run the same set of commands to configure and build:
// For the 0.5 branch, you must build a new Editor for each project: cmake --build
--target .GameLauncher Editor --config profile -- /m // For all other branches, just build the project: cmake --build --target .GameLauncher --config profile -- /m ">
-S -G "Visual Studio 16" -DLY_3RDPARTY_PATH=<3rdParty cache path> // For the 0.5 branch, you must build a new Editor for each project: cmake --build --target .GameLauncher Editor --config profile -- /m // For all other branches, just build the project: cmake --build --target .GameLauncher --config profile -- /m
For a tutorial on project configuration, see Creating Projects Using the Command Line in the documentation.
For terms please see the LICENSE*.TXT file at the root of this distribution.