Debugging a Unity Project on an Android Device via Visual Studio

Unity keeps improving its debugging tools, but the things still can get very painful, especially for Android development when it comes to debugging.

Recently, we faced with a really weird bug only happening on Android devices, and couldn’t find any real reason for it. So, we needed to debug the project line by line, while it runs on the device. Unfortunately, Unity still (15/05/2019) cannot provide a straight forward debugging tools for such situations, but my Google search provided me a tool called ADB (Android Debug Bridge).

However, using ADB wasn’t straightforward too, and the steps making it work were spread around the Internet. So, I blended the steps I found on the Internet with my own experience and wrote this article for the future reference and fellow sufferers.

Here, I will focus on Unity running on Windows machines and using Visual Studio as the IDE(?). I use Unity 2018.3 on a Windows 10 machine and Visual Studio 2017. So, I wrote the steps according to these components. But, as long as, you have a Windows machine and Visual Studio, I don’t expect any problems.

I. Setting up ADB

Before we start, you should be sure that you activated Developer Mode on your phone:

  1. Go to Settings -> System -> About Phone
  2. Start tapping on Build Number (Some legends say that you should tap 7 times)
  3. It will either directly activate Developer Mode (and inform you with a toast message) or you will see a pop-up for a confirmation

After you activate Developer Mode, you also need to allow USB and ADB debugging. For this:

  1. Go to Developer Options (Settings -> System -> Developer Options)
  2. Find USB debugging option and activate it
  3. Find allow ADB debugging in charge only mode (or something like that) and activate it

You do not need to keep USB debugging and ADB debuggins options active all the time, but do not forget to activate them before you start debugging, unless you want to get angry in front of your devices and keep screaming “Why the f*#@ you don’t work?!”.

Next step is setting up ADB. You most likely don’t have ADB in your system. So, I suggest you to start by downloading and extracting ADB somewhere reasonable, such as C:\ADB

So, here comes the steps:

  1. Download the latest platform tools for Windows from Android
  2. Extract the content (I extract it to C:\ADB)
  3. Open cmd (Command Prompt):
    1. Press WindowsKey + R
    2. Type cmd and press enter
  4. Change location where you extracted ADB:
    1. Type cd C:\ADB\platform-tools into cmd
    2. Press enter
  5. Connect your phone to your computer with a USB cable
    1. Choose “File transfer” mode if the phone asks
  6. Type adb devices into cmd and press enter
    1. If you did not allow USB debugging before, the phone will ask you for your permission. Give the permission and Repeat Step 6
  7. If everything goes smoothly, you should see a message like “List of devices attached \n [serial number of your device] device”
    1. If you want to be sure, you can verify it by Settings -> System -> About Phone -> Status -> Serial number

That’s all for setting up ADB folks! Now, you can take a deep breath and start setting up your environment for ADB debugging. It might be a bit painful though…

II. Setting up Your Environment for ADB Debugging

This part is probably the most chaotic part. Before diving it, you need to be sure about some stuff:

  1. Be sure your computer and your phone are connected to the same WIFI network (Surprisingly, many people had problems at this step)
  2. Be sure your phone is connected to the computer via the USB cable
  3. Get IP address of your phone. For this step you can
    1. Either go to System -> About Phone -> Status -> IP address
    2. Or type adb shell ip addr show wlan0 to cmd. It will print something like “inet” and many other stuff. The address written after “inet” is your phone’s IP address and you don’t need the numbers after the slash (/)

Now, we are at the moment that the things get real. Now, we will make a connection between ADB and our phone. If you are lucky enough, you will just type adb connect [YOUR_PHONE’S_IP_ADDRESS], press enter and cmd returns you “connected to [your phone’s ip address]“.

If you are not lucky enough, you will most likely get a message like “missing port in specification: tcp: [your_phone’s_ip_address]”. If so, you need to follow these steps:

  1. Be sure your phone is still connected to the computer via USB cable
  2. Be sure your phone and computer are connected to the same WIFI network
  3. Type ping [YOUR_PHONE’S_IP_ADDRESS] to cmd and press enter
  4. Be sure you can ping your phone
  5. Type adb kill-server to cmd and press enter
  6. Type adb usb to cmd and press enter
  7. Type adb tcpip 5555 to cmd and press enter (Here, I am POSITIVE that 5555 is just an arbitrary number)
  8. Unplug your phone from the USB cable
  9. Type adb connect [YOUR_PHONE’S_IP_ADDRESS]:5555 to cmd and press enter (like adb connect
  10. Type adb devices to cmd and press enter
  11. Now, you should see a message like “connected to [your_phone’s_ip_address]:5555

If you couldn’t get the message at Step 11, then be sure you activated USB debugging and ADB debuggins options as we mentioned in the section Setting up ADB. If the both options are active, but you still can’t get “connected to …” message, then open this link and a new tab to search the given error message on Google.

If you think this is the end, I have some bad news for you my friend. But, we are almost there. Now, we will set up Unity to build and debug our application on an Android device:

  1. Put the breakpoints in your scripts
  2. Get Unity editor and go to Build Settings: File -> Build Settings
  3. Be sure you properly set it up for an Android build (via Player settings)
  4. Check Development Build box (on Build Settings window)
  5. Check Script Debugging box (on Build Settings window)
  6. Click “Build and Run”
  7. Open Visual Studio and wait until the application starts running on your phone
  8. When the application runs, go to Debug -> Attach Unity Debugger -> Choose your phone (probably named as AndroidPlayer)
  9. Enjoy your breakpoints

If everything goes smoothly and you are lucky enough, you should start debugging your project line by line. But, I wasn’t the lucky one and needed to put a bit more effort. So, there are 3 more things I would like to talk before finishing:

First of all, “Build and Run” button did not work for me. Actually, “Build and Run” button stopped working for me long time ago. So, in the end, I built the application and installed on my phone manually. Luckily, ADB did not require “Build and Run”, and I was still able to debug my application by simply replacing the Step 6 by “Build and install manually”.

Second of all, all these plugging-unplugging USB thing and connecting your device over IP address, deep down made me feel that I do not need to plug my phone with a USB cable during debugging. So, I forgot to reconnect my phone with a USB cable, but since “Build and Run” doesn’t work for me, in the end I needed to plug it to copy the .apk anyway and I debugged while my phone was connected with the USB cable. But, ideally you are supposed to debug your phone over TCP without a USB cable (If I verify this, I will let you know. If you verify this before me, please let me know).

Finally, debugging may take up to 4-5 minutes to start and it may freeze from time to time while you go over the lines. So, please be patient and don’t think it crashed right away. When it crashes, it doesn’t just freeze, the debugger literally lets you know it crashes.

III. This is the End

All in all, it is still not the best, i.e., I couldn’t debug my main MonoBehavior.Start() no matter what I did, it always crashed, but it is much better than nothing, especially when you have no idea what the heck is going on and desperately need to go over the lines to sort things out.