Menu
Lumberyard
User Guide (Version 1.13)

Design Considerations for Creating Mobile Games Using Lumberyard

This feature is in preview release and is subject to change.

This topic references tools and features that are legacy. If you want to use legacy tools in Lumberyard Editor, disable the CryEntity Removal gem using the Project Configurator or the command line. To learn more about legacy features, see the Amazon Lumberyard Legacy Reference.

Lumberyard is a cross-platform game engine, which allows you to develop your game with less concern about the release platform(s). However, some mobile development considerations are discussed below, including game logic, input, and application lifecycle.

Input

You may need to consider the various physical input devices when you design your game. Lumberyard provides support for the following input devices for iOS and Android:

  • Touch screens

  • Motion sensors

Touch

You can use the TouchEvent node (located under Input, Touch) in the Flow Graph Editor to script touch-specific input.

You can also script touch input using more advanced flow nodes:

  • MultiTouchCoords – Outputs touch events from the specified ID (finger)

  • MultiTouchEvent – Returns touch location information.

  • TouchRayCast – Generates a ray cast for every frame.

  • VirtualThumbstick – Implements a virtual thumbstick.

If you have created your game logic to use mouse-based input, Lumberyard provides a way to emulate mouse events using the primary touch on mobile devices. To enable the ability to emulate mouse events, set s_SimulateMouseEventsWithPrimaryTouch to 1. To support multi-touch input logic and prevent emulated mouse events from being generated alongside touch events, set s_SimulateMouseEventsWithPrimaryTouch to 0.

Gestures

Lumberyard provides a Gestures Gem (in the Project Configurator) that allows you to script input in the Flow Graph Editor using flow nodes (located under Input, Gestures) that detect common gesture-based input actions, including:

  • Tap (or click, single-touch)

  • Drag (or pan, single-touch)

  • Hold (or press, single-touch)

  • Swipe (single-touch)

  • Pinch (multi-touch)

  • Rotate (multi-touch)

Gestures that require only a single touch to be recognized (Tap, Drag, Hold, and Swipe) function the same when using mouse input on PC. Multi-touch gestures (Pinch and Rotate) can only be recognized through multiple, simultaneous touches.

Motion Sensors

You can use a range of MotionSensor nodes in the Flow Graph Editor to return motion sensor data generated by mobile devices from the accelerometer, gyroscope, and magnetometer. Each flow node returns a vector (or quaternion for orientation) for the device's:

  • Acceleration – Raw, user-generated, or gravity

  • Rotation – Raw or unbiased

  • Magnetic Field – Raw, unbiased, or magnetic north

  • Orientation – Absolute or difference from the previous reading

Game Logic

You can use the CheckPlatform node in the Flow Graph Editor to modify your game logic by branching your logic based on the current platform.

You can also use the AZ_PLATFORM_* #defines in C++ to explicitly include or exclude code for compilation based on specific platforms. Or you can include entire files for compilation for a specific platform by listing the files in a separate .waf_files file.

For example, Code\Framework\AzFramework\AzFramework\API\ApplicationAPI_ios.h is only listed in Code\Framework\AzFramework\AzFramework\azframework_ios.waf_files, which is referenced exclusively for iOS in:

Code\Framework\AzFramework\AzFramework\wscript ios_file_list = ['azframework_ios.waf_files'],

Application Lifecycle

Lumberyard provides a Process Life Management Gem (in the Project Configurator) that shows how you can respond to various application lifecycle events in order to pause your game, display a modal splash screen, and any other actions that need to occur if your application loses focus. You can access system-specific events in C++ by connecting to the appropriate EBus; however, Lumberyard also generates platform-agnostic events that you can use for all supported platforms.

Lumberyard Application Lifecycle Events iOS Android
OnApplicationConstrained applicationWillResignActive onPause()
OnApplicationUnconstrained applicationDidBecomeActive onResume()
OnApplicationSuspended applicationDidEnterBackground onPause()
OnApplicationResumed applicationWillEnterForeground onResume()
OnMobileApplicationWillTerminate applicationWillTerminate onDestroy()
OnMobileApplicationLowMemoryWarning applicationDidReceiveMemoryWarning onLowMemory()

To receive process lifecycle events in your game

  1. Derive your class from AzFramework::ApplicationLifecycleEvents::Bus::Handler (or AzFramework::[Ios|Android|Windows]LifecycleEvents::Bus::Handler for platform-specific events).

  2. Override the functions corresponding to the events you wish to override:

    void OnApplicationConstrained(Event /*lastEvent*/) override; void OnApplicationUnconstrained(Event /*lastEvent*/) override; void OnApplicationSuspended(Event /*lastEvent*/) override; void OnApplicationResumed(Event /*lastEvent*/) override
  3. Connect to the event bus when you want to start listening for events (be sure to also disconnect when you no longer wish to receive them):

    ApplicationLifecycleEvents::Bus::Handler::BusConnect(); ??? ApplicationLifecycleEvents::Bus::Handler::BusDisconnect();

For a complete example of how to subscribe and respond to application events, see the Gems\ProcessLifeManagement\Code\Source\ProcessLifeManagementGem.h\.cpp directory.