Best Practice - o3de/wikicollection GitHub Wiki

Tools Dependence

ninja

Download URL：https://github.com/ninja-build/ninja/releases :1.10.1

Path Config：

create dir "ninja/1.10.1/Windows"

set path=%LY_3RDPARTY_PATH%/ninja/1.10.1/Windows;%path%

Note: Do not contain space within path, since it can't be parsed by the scripts: .\scripts\build\Platform\Android\gradle_windows.cmd

android studio

NDK Version：21.4.7075529 (can be downloaded through Android studio SDKmanager)

Third Party

To be Added

Version

NDK：21.4.7075529

Android SDK：30.0.2

CMake：3.21.0-rc2

O3DE Version：fantasy_main_release_2107

Build & Compile & Package

STEP1: Environment Setting

set GE_ROOT=D:/01_code/
set GE_CODE_ROOT=%GE_ROOT%/GameEngine
set GE_BUILD_ROOT=%GE_CODE_ROOT%/build_main
set LY_PACKAGE_DOWNLOAD_CACHE_LOCATION=%GE_ROOT%/3rdParty
set LY_3RDPARTY_PATH=%LY_PACKAGE_DOWNLOAD_CACHE_LOCATION%
call .\scripts\o3de.bat register --this-engine
set LY_PACKAGE_SERVER_URLS=https://d2c171ws20a1rv.cloudfront.net
set CL=/source-charset:utf-8
set LY_PACKAGE_SERVER_URLS=http://cmc-szver-artifactory.cmc.tools.huawei.com/artifactory/ccs/cloud-game/3rdParty/

cmake -B %GE_BUILD_ROOT% -S %GE_CODE_ROOT% -G "Visual Studio 16 2019" -DLY_3RDPARTY_PATH=%LY_3RDPARTY_PATH% -DLY_UNITY_BUILD=ON -DLY_PROJECTS=AutomatedTesting;AtomSampleViewer

STEP2: Configuration

Gems Config: Comment gems in "engine.json", if you do not need them, such as:

Gems/Multiplayer
Gems/CertificateManager
Gems/AWSClientAuth (if your mobile phone can't access the AWS server)
... and so on

Build config: Change the Test project cmake flags to accelerate building process

ly_set(PAL_TRAIT_BUILD_TESTS_SUPPORTED TRUE) -> FALSE (cmake\Platform\Android\PAL_android.cmake)

Asset bundle config:

project name : engine.json ("projects": "AtomSampleViewer")
bundle flag: AtomSampleViewer\project.json ("place_assets_in_apk": 0 -> 1)
Asset mode:
- debug : --asset-mode -> LOOSE
- release: --asset-mode -> PAK

STEP3: Asset Build

Build AssetProcessor
Asset build configuration:
- GameEngine\Registry\AssetProcessorPlatformConfig.setreg
  
  "Platforms": {
  
  "android": "enabled"
  
  }
asset build

Load the project in O3DE project manager, the asset will be processed by AssetProcessor automatically

STEP4: Project configuration

environment config

set GAME_PROJECT=D:\01_code\GameEngine\AtomSampleViewer

set OUTPUT_DIRECTORY=D:\01_code\GameEngine\build_android
cd D:\01_code\GameEngine & scripts\build\Platform\Android\gradle_windows.cmd
check the output

verify the project config file：build_android\platform.settings (embed_assets_in_apk = False -> True)

STEP5: Generate APK

configuration

To shrink the apk package size: D:\01_code\GameEngine\build_signpal\app\src\main\AndroidManifest.xml
```
<application>
    android:extractNativeLibs="true"
<\application>
```
Gradle sync
Set the target version

Project update recommended -> build Variants: release or debug

Note:

Release Pak: You should process asset_bundle.bat script (see attachment) to generate the pak files in following dir

D:\01_code\GameEngine\SignPal\Pak\SignPal_android_paks
Debug Pak:
- verify the *.setreg file (GameEngine\SignPal\Cache\android\Registry\cmake_dependencies.signpal.signpal_gamelauncher.setreg) to make sure the lib files suffix is ***.so
- Remove dir GameEngine\SignPal\Pak\SignPal_android_paks

STEP6: RUN

adb install -r -t .\app-release.apk

FAQ

Building Questions

Android Studio (AS) Project building error

Q1: :app:syncLYLayoutModeDebug, unable to open "project.json"

A1: solution: To use absolute path in gradle_windows.cmd

Q2: Could not find a version that satisfies the requirement certifi==2019.11.2

A2: To check your proxy configuration, maybe change or disable proxy will solve this problem
Release Asset bundle uncorrectly

Q1: Pak folder for the project at path '***' is missing

A1: To see the generate Apk section in Build & Compile & Package
Asset build error

Q1: Lost connections to asset builder

A1: To close the AP in the background

Q2: AssetProcessor broken down

A2: Low resource PC raise this problem, you can decrease the AP thread num. Maybe close other unrelated process is also helpful

Running Questions

To be added

Debug Questions

To be added

Attachment

Asset_bundle.bat

::Step 1, param setting
::set ly_project=%1%
::set AssetBundlerBatchexe_path=%2%
::set PLATFORM=%3%
::set other_seed=%4%

set ly_project=SignPal
set engine_root=D:\01_code\GameEngine
set AssetBundlerBatchexe_path=%engine_root%\build_main\bin\profile
set PLATFORM=android
set assetdir=%engine_root%\%ly_project%\Cache\%PLATFORM%
set pakdir=%engine_root%\%ly_project%\Pak\%ly_project%_%PLATFORM%_paks

::Step 2, generate assets
echo %AssetBundlerBatchexe_path%\AssetBundlerBatch.exe assetLists ^^>>%ly_project%_asset_bundle.bat
echo --addDefaultSeedListFiles ^^>>%ly_project%_asset_bundle.bat
echo --addSeed SignPal_Dependencies.xml ^^>>%ly_project%_asset_bundle.bat
echo --addSeed Levels\signpal\level.pak ^^>>%ly_project%_asset_bundle.bat
echo --addSeed user.cfg ^^>>%ly_project%_asset_bundle.bat
echo --addSeed assetcatalog.xml ^^>>%ly_project%_asset_bundle.bat
echo --addSeed project.json --generateDebugFile --assetListFile %ly_project%_%PLATFORM%.assetlist --platform %PLATFORM% --allowOverwrites ^^>> %ly_project%_asset_bundle.bat
echo --regset="/Amazon/AzCore/Bootstrap/project_path=%ly_project%">> %ly_project%_asset_bundle.bat
echo "generate assetLists ..."
call %ly_project%_asset_bundle.bat
echo "generate assetLists success"

::step 3, bundle assets
%AssetBundlerBatchexe_path%\AssetBundlerBatch.exe bundles --assetListFile %ly_project%_%PLATFORM%.assetlist --outputBundlePath engine_%PLATFORM%.pak --regset="/Amazon/AzCore/Bootstrap/project_path=%ly_project%" --allowOverwrites --platform %PLATFORM%
echo "bundles assets success"

::Step 4, compress assets
rd /s /q %pakdir%
md %pakdir%
md %pakdir%\tmp
move %engine_root%\engine_%PLATFORM%.pak %pakdir%
copy %assetdir% %pakdir%\tmp
if exist %pakdir%\tmp\engine_%PLATFORM%.pak (
        del %pakdir%\tmp\engine_%PLATFORM%.pak
    )
    
:: compress %pakdir%\engine_%PLATFORM%.pak %pakdir%\tmp\*

::Step 5: move & copy asset files
copy %assetdir%\bootstrap.game.release.android.setreg %pakdir%
copy %assetdir%\*.json %pakdir%
echo d | xcopy %assetdir%\assets %pakdir%\assets /e
echo d | xcopy %assetdir%\config %pakdir%\config /e
echo d | xcopy %assetdir%\levels %pakdir%\levels /e
echo d | xcopy %assetdir%\passes %pakdir%\passes /e
echo d | xcopy %assetdir%\shaderlib %pakdir%\shaderlib /e
echo d | xcopy %assetdir%\shaders %pakdir%\shaders /e

::Step 6--- rename pak
del %engine_root%\%ly_project%_%PLATFORM%.assetlist
del %engine_root%\%ly_project%_asset_bundle.bat
del %engine_root%\%ly_project%_%PLATFORM%.assetlistdebug
rd /s /q %pakdir%\tmp
move %pakdir%\engine_%PLATFORM%.pak %pakdir%\engine.pak

Signature

Method 1: use debug signature file

Project Structure -> Build Variants -> app -> Build Types -> Signing Config: $signingConfigs.debug

Method 2: Generate Signed file by Android studio

build -> generate Signed Bundle or APK, then choose APK -> next
click button Create new, fill in the password
choose the target platform: Release of profile

Code Debug

Project configuration

Run/Debug Configurations -> app -> Debugger

Debug type : Dual (Java + Native)

Symbol Directories:GameEngine\build_***\app\build\intermediates\cmake\debug\obj
Array values check

LLDB tools to check JNI Array: parray $num $arrayname
Log info

IDE Log: view -> tool windows -> logcat: com.lumberyard.***

Log print: AZ_TracePrintf(window, ...)