Set Up Your Device For Debugging
The first thing you’ll want to do when you’re ready to start debugging is prepare the device you are using. You can do this by going to Settings Applications Development and then tapping on “USB Debugging” to switch it on. You may also find it beneficial to tap the "Stay Awake" flag too so that the screen is always active. Once that is done you are ready to start using your device for testing games with GameMaker:Studio and debug them as you go.
The Android Debug Bridge
When creating games for Android, it is important that the ADB(Android Debug Bridge) Platform Tools are up to date and that you know how to use them. When you test a game on Android, you will see that a command line window opens which shows a number of details about the progress of configuring your device as well as the state of the device as you play. This is part of the ADB tools for Android and GameMaker:Studio uses it to show debug messages and other important information like device, resolution, ad providers etc...
You can also run this tool yourself by opening up a command line and going to the ADB directory (EG:
E:\Android_SDK\platform-tools). Once you have found the correct directory, you can type
adb help to get a full list of the available commands, but in general you will only need the following two:
- adb get-state - Using this command will show whether your device is connected and recognised or not. If everything is fine it will return "device" but if there is an error the return value will be "unknown".
- adb logcat - This will start the ADB logging function which will ooutput to the cmd window everything that is happening on your device so that you can see exactly what is being done at any given moment. This function is VERY useful for checking that ads, pausing, touches etc... are being registered correctly.
For a more detailed explanation of the ADB log, please see ADB Logging Your Android Game.
The Dalvik Debug Monitor
Dalvik Debug Monitor comes with the Android SDK and is found in the Android_SDK/Tools/ folder. It is an excellent debug tool for all Android devices and it is highly recommended that you familiarise yourself with it. However due to the sheer quantity of information that it can supply, to go through and explain every feature is outside of the scope of this wiki, but thankfully Google have their own page that explains everything clearly and concisely here: DDMS.
Now, to make things easier, you should make a desktop direct link to it by first finding the DDMS.BAT file and then using the right click menu to create a shortcut to it on your desktop. Double clicking on this BAT will now open the DDM on your PC, which will show all the currently connected devices. Clicking on any device will connect the DDM to it and start to show debug information in the main window.
Note : The first time you run DDMS.BAT you may be asked to send usage details to Google. Once passed this stage, the file may fail, in which case you should close the command prompt window and try again. Even now it may return a few errors, depending on where you have installed your Android SDK, so you may need to manually enter the PATH in the system environment variables for the bin folder of your Java installation. You may also need to manually enter the ANDROID_SWT variable for the path to the swt.jar file in your Android SDK installation (you may not need to do either of these things – just pay attention to any errors the DDMS.bat file returns!).
As a debug tool, screenshots can be exceptionally helpful, whether it is for sending an image to an ad provider to demonstrate a problem, or for sending to the YoYo Games Bug Tracker, or for analysing in an image editor to see how things look "up close". however, due to the nature of the Android platform and it's use of multiple versions over multiple devices, this is not always an easy thing to achieve! However, it can be done in a variety of different ways and one of them is sure to work for your device.
Android 4.0 IceCream Sandwich
If you’re using Android 4.0 or later taking a screenshot is easy. Just press and hold the Volume Down and Power buttons at the same time. You’ll see an animation on the screen, indicating that the screenshot was saved to your Gallery. You can then launch the Gallery app and tap Screenshots to view and share your screenshots, or connect the device to your PC via USB cable and access them that way.
Using The Android SDK
You can take screenshots on any Android device using Google’s Android SDK. After you’ve set up the Android SDK, all you have to do is connect your Android phone or tablet to your computer with its USB cable and fire up the SDK. Now, this isn't the most user-friendly application to use in this way, but it’s easy to use once you've gotten everything set up correctly. The following steps should enable you to achieve this easily:
- Double click the link to the DDMS.BAT and it will launch the Dalvik Debug Monitor (see above)
- Select the device you wish to debug from the list
- Use CONTROL + S or go to the Device drop down menu and then select "Screen Capture"
The screen will now be shown in a large window on your PC and there are several options to choose from for your screen:
- Refresh - refresh the currently captured image
- Rotate - rotate the captured image anti-clockwise
- Save - save the image as a *.png file (a windows dialogue will open so you can name it and choose the save location)
- Copy - copy the image to the clipboard
- Done - close the image capture window
The screen capture is of a very high quality, and you can just click “Refresh” to get a new image again before saving, copying or exiting the application. Once you’re set up to capture screenshots in this way, you’ll be able to start capturing some of the most amazing screenshots of your Android mobile device in three simple steps – launch DDMS.BAT, click Capture Screenshot on the debug monitor, and save the picture to your hard drive.
This page aims to help you with debugging your games on the Android target platform. Before starting however, please make sure that you have set up the Android SDK correctly and that your device is visible. If you cannot even run a game on your device, please see the list of typical problems found on the page about Troubleshooting Android Devices.
If your device is running Version 4.2.2 and you find ADB logging disabled see ADB Debugging on Android 4.2.2 for help.