The
Google Play Games on PC Developer Emulator
is a developer-focused emulator for
Google Play Games on PC. Unlike the player experience, you can install and
debug your own packages. You also can simulate various player configurations
such as the aspect ratio, mouse emulation, and graphics backend to help you
ensure that your game performs as expected across a variety of PC
configurations.
Starting the Emulator
Once installed, you will have a "Google Play Games Developer Emulator" start
menu element and a desktop shortcut to launch the emulator. The emulator will
remain resident in your system tray when you close the window.
Sign in
You are asked to sign into your Google account the first time you run the
emulator. Use the same login credentials you plan to use for development.
You can sign out by right clicking on the system tray icon, selecting
Developer
Options
, then clicking
Force sign out
. When you do so, the emulator
immediately restarts and asks you to sign in again.
Navigation
After launching, you will see a typical Android home screen. Left mouse
clicks are directly translated into finger taps as in mouse emulation mode.
Games sideloaded for development appear in the application list, which you can
get to by clicking and dragging up on the desktop (emulating an upwards swipe on
a phone or tablet).
In addition to mouse translation, the Google Play Games on PC Developer Emulator provides
keyboard shortcuts to improve navigation:
- ctrl + h
: press the home button
- ctrl + b
: press the back button
- F11
or
alt + enter
: toggle between fullscreen and
windowed mode
- shift + tab
: open the Google Play Games on PC overlay, including
the current key mappings for the Input SDK
Installing a game
The Google Play Games on PC Developer Emulator uses the
Android Debug Bridge (adb)
to
install packages.
adb compatibility
Current versions of
adb
are compatible with the Google Play Games on PC Developer Emulator.
Additionally a compatible version is installed at
C:\Program
Files\Google\Play Games Developer Emulator\current\emulator
when you install
the emulator.
To follow these instructions, adb should be available in your
$PATH
. You can
verify that
adb
is configured correctly with the
adb devices
command
adb devices
List of devices attached
localhost:6520 device
Install the game
- Launch
Google Play Games for PC Emulator
Type
adb devices
in your command prompt. You should see:
adb devices
List of devices attached
localhost:6520 device
Troubleshooting:
- If you get an error, verify that you've followed the instructions in
Adb
compatibility
.
- If you don't see a device, attempt to reconnect over port
6520
:
adb connect localhost:6520
Type
adb install path\to\your\game.apk
to install your game. If you've
generated an Android App Bundle (aab), see the instructions for
bundletool
and use
bundletool install-apks
instead.
Run your game by either:
- Type
adb shell monkey -p your.package.name 1
to run your game, replacing
your.package.name
with your game's package name.
- In the Google Play Games on PC Developer Emulator, click the icon to run your game.
Just like on an Android phone, you have to "swipe up" on the home
screen to see the list of installed games.
Debugging a game
Use the
Android Debug Bridge (adb)
to debug as you do for any other game.
The emulator appears as a device connected via
localhost:6520
.
adb logcat
functions as expected, as do tools that help prettify or filter
logcat output -- including Android Studio.
In addition to
adb
, logs can be accessed in your
%LOCALAPPDATA%\Google\Play Games Developer Emulator\Logs
directory. Most
useful here is
AndroidSerial.log
which represents everything
adb logcat
would echo from the moment the emulator starts.
Developer settings
The Google Play Games on PC Developer Emulator focuses on developer efficiency rather
than end user experience. This means that you have unobstructed access to the
Android system, including using the standard Android launcher instead of the
Google Play Games on PC experience, and controls over features that are
otherwise automatically enabled and disabled for players.
Testing mouse input
During development, the Google Play Games on PC Developer Emulator defaults to touch
emulation rather than giving you direct mouse input. You can enable direct mouse
input by right clicking the system tray icon, selecting
Developer Options
,
and then
PC mode (KiwiMouse)
.
Google Play Games on PC has two mouse modes: an emulated mode that translates
mouse clicks into single taps and a passthrough "PC mode" that lets games handle
mouse actions natively and perform pointer capture. For details on mouse input
in Google Play Games on PC see
Setup mouse input
.
In the player client, emulation is disabled by adding this to your manifest:
<manifest ...>
<uses-feature
android:name="android.hardware.type.pc"
android:required="false" />
...
</manifest>
This feature flag has no effect in the development environment.
Testing aspect ratios
The developer emulator launches in a 16:9 aspect ratio ? unlike the player
client which derives its aspect ratio from the primary display. By right
clicking on the system tray icon, selecting
Developer Options
, and then any
option in the
Display Ratio
section, you can test how the game looks on
different player's screens.
The
preferred method
to configure your aspect ratio
is to use
android:minAspectRatio
and
android:maxAspectRatio
.
For example,
a portrait game would have a
9/16
or
0.5625
aspect ratio so you may want to
set a max aspect ratio of
1
to prevent your game from going wider than square:
<activity android:maxAspectRatio="1">
...
</activity>
Similarly, a landscape game would be
16/9
or roughly
1.778
, so you may want
to set a min aspect ratio of
1
to prevent it from going skinnier than square:
<activity android:minAspectRatio="1">
...
</activity>
What to test
If your game only supports portrait modes in the manifest, you can select
9:16
(Portrait)
in the drop-down to see how it looks on players' PCs. Otherwise
verify that your game works at the widest and narrowest landscape ratios you
support in your manifest, remembering that
16:9 (Default)
(or
9:16 (Portrait)
if your game is portrait only) is
required for
full certification
.
Testing rendering backends
Google Play Games on PC uses
ANGLE
as compatibility layer to
ensure that OpenGL ES calls are handled correctly by the host PC using either a
DirectX or Vulkan backend. The emulator also supports Vulkan directly, although
not on DirectX. This layer also converts mobile only compressed texture formats
to PC compatible ones. By right clicking on the system tray icon and selecting
Graphics Stack Override
, you may either set it to your system's default or
force vulkan on or off for compatibility testing.
What to test
There are minor variations in supported texture formats and the steps needed to
emulate various mobile features on desktop. When profiling and optimizing your
game, it may be worth checking each backend.
Profiling your PC game
Since the emulator uses the same technology as the consumer client, it's a
suitable environment for performance profiling.
Perfetto
is a tool for analyzing performance on Android. You can gather and
view a Perfetto trace using the following steps:
In a PowerShell prompt, start a trace using
adb
adb shell perfetto --time 10s gfx wm sched --out /data/misc/perfetto-traces/example.trace
- The
--time
flag specifies the duration of the trace to gather.?In this
example, the trace is 10 seconds.
- The arguments after the
--time
flag indicate which events are to be
traced. In this example
gfx
indicates graphics,
wm
window management, and
sched
process scheduling information. These are common flags for profiling
games and a
full reference
is available.
- The
--out
flag specifies the output file, which is pulled out of
the emulator onto the host machine in the next step.
Pull the trace from your host
adb pull /data/misc/perfetto-traces/example.trace $HOME/Downloads/example.trace
Open the trace in the Perfetto UI
- Open
ui.perfetto.dev
.
- Select
Open trace file
from the upper left corner under
Navigation
.
- Open the
example.trace
file you downloaded in the previous step to your
Downloads/
directory.
Inspect the trace in the Perfetto UI. Some tips:
- Each process has its own row, which can be expanded to show all the threads
in that process. If you're profiling a game, it's process is likely the first
row.
- You can zoom in and out by holding
Control
and using the scroll
wheel.
- When using the
sched
event, there is a row for each thread showing when
that thread's state is running, runnable, sleeping, or blocked.
- When enabling an event like
gfx
, you are able to see the various
graphics calls made by various threads. You can select individual "slices" to
see how long they took, or you can drag along a row causing a "slices" section
to open at the bottom and show you how long all the slices took in your
selected time window.
Graphics Profiling
It is possible to perform some graphics profiling with
RenderDoc
.
- Set the environment variable
ANDROID_EMU_RENDERDOC
to a non-empty string (such as
"1"
).
Set the environment variable
TMP
to
%USERPROFILE%\AppData\LocalLow
. This tells Renderdoc to place its log files
somewhere reachable within the emulator sandbox.
If you are using the
Vulkan
backend. Select
Graphics Settings
>
Vulkan Instance Implicit Layers
and ensure that
VKLAYER_RENDERDOC_Capture
is checked.
Launch Google Play Games on PC Developer Emulator. A RenderDoc overlay is drawn at the
top as long as support is enabled.
Launch RenderDoc anytime before or after Google Play Games on PC Developer Emulator
launches.
Click
File
>
Attach to Running Instance
and select
crosvm
.
Specify Environment Variables
In order for Renderdoc to work, you have to add or change environment variables
in Windows. You can change environment variables using the UI, PowerShell, or
cmd.exe.
Use the UI
- Press
Win+R
to open the run dialog.
- Type
sysdm.cpl
to open the
System Properties
window.
- Select the
Advanced
tab if it isn't already active.
- Click the
Environment Variables
button.
From here you can either click the
New
button to create a new environment
variable or select a variable and click the
Edit
button to edit it.
Use PowerShell
In a PowerShell window, type:
$Env:VARIABLE_NAME=VALUE
Replace
VARIABLE_NAME
and
VALUE
with the values you wish to set. For
example, to set
ANDROID_EMU_RENDERDOC
to
"1"
type:
$Env:ANDROID_EMU_RENDERDOC="1"
Use cmd.exe
In a cmd.exe window, type:
set VARIABLE_NAME=VALUE
Replace
VARIABLE_NAME
and
VALUE
with the values you wish to set. For
example, to set
ANDROID_EMU_RENDERDOC
to
"1"
type:
set ANDROID_EMU_RENDERDOC="1"
Tips for Android 11 (API level 30) or higher
Google Play Games on PC is updated with the latest Android releases. Here are
some tips for working with the latest version of Android.
Android Studio installs a version of adb that is compatible with the developer
emulator; however, some game engines include an older version of adb. In that
case, after you install the developer emulator, you can find a compatible
version of
adb
at
C:\Program Files\Google\Play Games Developer
Emulator\current\emulator
.
If you launch one version of
adb
, it terminates the other. This means that
if your game engine automatically launches its own
adb
instance, you may have
to re-launch and reconnect the version of
adb
that comes with the developer
emulator whenever you deploy.
If you are using an Android App bundle, you must install the latest version of
Bundletool
from the
GitHub repository
.
Scoped Storage
Android 11 (API level 30) or higher includes
scoped storage
, which provides
better protection to app and user data on external storage. Besides making your
game compatible with
scoped storage requirements
, you need to perform
extra steps to load
APK Expansion Files
(obb) or asset data into the
Google Play Games on PC Developer Emulator. Follow these steps if you run into issues
accessing those files from your game:
- Create a directory that your app can read.
- Push your expansion files to the emulator.
adb shell mkdir /sdcard/Android/obb/com.example.game
adb push main.com.example.game.obb /sdcard/Android/obb/com.example.game
Package Visibility
Because of the new
package visibility
rules, apps that target Android 11
(API level 30) or higher are blocked from querying for information about the
other apps that are installed on a device. This means that your game is blocked
from accessing Play Services when sideloaded via
adb
instead of being
installed via the Play Store. To test your IAP with a sideloaded game,
you must add a query to the package "
com.android.vending
" in your
AndroidManifest.xml
file as follows:
<manifest>
<queries>
<package android:name="com.android.vending" />
</queries>
</manifest>
Installing your game in the consumer client
You cannot install a game on the consumer client until it has been listed in the
Play Games Services catalog. After your game has a single release, you
can create an
internal test track
validate future updates
before release.
The player client doesn't support the developer focused features of the
Google Play Games on PC Developer Emulator. This is best used to QA the game before release
to test the end to end player experience after the initial release.