The[Google Play Games on PC Developer Emulator](https://developer.android.com/games/playgames/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.
| **Note:** you cannot run the Google Play Games on PC Developer Emulator and the consumer Google Play Games on PC at the same time. You must quit one from the system tray before launching the other.

### 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.
| **Caution:** Your local device image, including any games you have installed, is erased when you sign out.

### 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
- F11oralt + 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

| **Note:** ctrl + handctrl + bare provided for development purposes only. Don't rely on them in your shipping game.

## Installing a game

The Google Play Games on PC Developer Emulator uses the[Android Debug Bridge (adb)](https://developer.android.com/tools/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

| **Note:** If you prefer to not modify your`$PATH`variable, run your terminal from`C:\Program Files\Google\Play Games Developer Emulator\current\emulator`. Some shells require you to type`./adb`rather than`adb`depending when doing this.

### 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](https://developer.android.com/games/playgames/pg-emulator#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](https://developer.android.com/tools/bundletool#deploy_with_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)](https://developer.android.com/tools/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.
| **Note:** `%LOCALAPPDATA%`typically expands to`C:\Users\<username>\AppData\Local`

## 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](https://developer.android.com/games/playgames/input-mouse).

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](https://developer.android.com/games/playgames/graphics#dynamic-display)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>

| **Note:** In practice games don't work well as they approach square aspect ratios. You should find a value that makes sense in your own testing across Android devices.

#### 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](https://developer.android.com/games/playgames/graphics#aspect-ratios).

### Testing rendering backends

Google Play Games on PC uses Vulkan to render your games, which is common to both Android and PC environments. A sandboxing layer is used to isolate the PC and Android environments. Since many games still use OpenGL ES for rendering,[ANGLE](https://github.com/google/angle)will convert OpenGL ES commands to Vulkan commands compatible with the host PC.

Similarly, Google Play Games on PC maximizes game compatibility and minimizes developer effort by automatically converting mobile-friendly texture formats such as ETC1 and ETC2 to PC friendly formats at runtime. For the best results, avoid this conversion by utilizing formats supported by PC GPUs, such as DXTC or BPTC.

#### What to test

If your game is experiencing unexpected rendering artifacts, inspect your source graphics and consider moving to a PC-friendly format. Pay close attention to textures used for more advanced effects, as normal or cube map issues are often harder to spot than issues with albeido.

ANGLE's conversion of your OpenGL ES commands to Vulkan will add some overhead. Validate you're meeting your expected performance targets and consider switching to a Vulkan based renderer.

### Profiling your PC game

Since the emulator uses the same technology as the consumer client, it's a suitable environment for performance profiling.

[Perfetto](https://developer.android.com/tools/perfetto)is a tool for analyzing performance on Android. You can gather and view a Perfetto trace using the following steps:

1. In a PowerShell prompt, start a trace using[`adb`](https://developer.android.com/games/playgames/pg-emulator#adb-compatibility)

       adb shell perfetto --time 10s gfx wm sched --out /data/misc/perfetto-traces/example.trace

   1. The`--time`flag specifies the duration of the trace to gather. In this example, the trace is 10 seconds.
   2. 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](https://android.googlesource.com/platform/frameworks/native/+/refs/tags/android-q-preview-5/cmds/atrace/atrace.cpp#100)is available.
   3. The`--out`flag specifies the output file, which is pulled out of the emulator onto the host machine in the next step.
2. Pull the trace from your host

       adb pull /data/misc/perfetto-traces/example.trace $HOME/Downloads/example.trace

3. Open the trace in the Perfetto UI

   1. Open[ui.perfetto.dev](https://ui.perfetto.dev/).
   2. Select**Open trace file** from the upper left corner under**Navigation**.
   3. Open the`example.trace`file you downloaded in the previous step to your`Downloads/`directory.
4. Inspect the trace in the Perfetto UI. Some tips:

   1. 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.
   2. You can zoom in and out by holding<kbd>Control</kbd>and using the scroll wheel.
   3. When using the`sched`event, there is a row for each thread showing when that thread's state is running, runnable, sleeping, or blocked.
   4. 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

| **Caution:** Attaching Renderdoc only works in the Developer Emulator and is not officially supported.

It is possible to perform some graphics profiling with[RenderDoc](https://renderdoc.org/).
| **Note:** Renderdoc can only detect the output of the emulator, after instructions from your game have been translated from the guest to the host operating system.

1. [Set the environment variable](https://developer.android.com/games/playgames/pg-emulator#environment-variables)`ANDROID_EMU_RENDERDOC`to a non-empty string (such as`"1"`).
2. [Set the environment variable](https://developer.android.com/games/playgames/pg-emulator#environment-variables)`TMP`to`%USERPROFILE%\AppData\LocalLow`. This tells Renderdoc to place its log files somewhere reachable within the emulator sandbox.

   | **Note:** you may need to log out and back in at this point.
3. If you are using the[Vulkan](https://developer.android.com/games/playgames/pg-emulator#testing-rendering)backend. Select**Graphics Settings** \>**Vulkan Instance Implicit Layers** and ensure that**VKLAYER_RENDERDOC_Capture**is checked.

   | **Note:** Changes to**Graphics Settings**require a relaunch of the emulator to take effect.
4. Launch Google Play Games on PC Developer Emulator. A RenderDoc overlay is drawn at the top as long as support is enabled.

5. Launch RenderDoc anytime before or after Google Play Games on PC Developer Emulator launches.

6. 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

- PressWin+Rto 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.

### Keep tools up to date

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](https://developer.android.com/tools/bundletool)from the[GitHub repository](https://github.com/google/bundletool/releases).

### Scoped Storage

Android 11 (API level 30) or higher includes[scoped storage](https://developer.android.com/training/data-storage#scoped-storage), which provides better protection to app and user data on external storage. Besides making your game compatible with[scoped storage requirements](https://developer.android.com/games/playgames/pc-compatibility#scoped-storage), you need to perform extra steps to load[APK Expansion Files](https://developer.android.com/google/play/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:

1. Create a directory that your app can read.
2. 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](https://developer.android.com/training/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>

| **Note:** You don't need to add this in the release version of your game distributed via the Play Store.

## 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](https://play.google.com/console/about/internal-testing/)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.