Installation for Beta Testers ============================= .. topic:: Important! **Beta-testing is only supported on Android devices.** Testing on iOS is currently impossible as there is no "debug" mode for apps. When you're nearly finished creating your game, you may want other people to test it on a variety of real mobile devices. This helps you fix bugs and improve the user experience before your first "real" release. **Beta-testers should generally be given the following two files,** discussed in further detail below. +-----------------+------------------------------------------------------------------------+ | File | Description | +=================+========================================================================+ | *javamon.apk* | The game itself, as an Android application package. Beta-testers will | | | need to install this file on their phones before they can play. | +-----------------+------------------------------------------------------------------------+ | *musicPack.zip* | An optional file containing extra music and sound effects. These files | | | will need to be unzipped and placed on the mobile device's SD card. | +-----------------+------------------------------------------------------------------------+ Installing the APK ------------------ To install and play the game, you must have the following: * An Android phone or tablet. * A file manager for browsing the SD card. `Astro `_ is a good choice; it's free and easy to use. Users can install Astro via Google Play, just like any other app. First you will need to **copy the APK to your SD card.** An example of how to do this on Windows: 1. **Connect your Android device to a computer** via USB cable. 2. A message may pop up on your computer about a new USB device. If so, click on this and **choose to "mount" the device if prompted.** 3. Navigate to "This PC" or "My Computer" and select your device from the list. It may or may not have a name; for example, my Moto X is called "XT1060". 4. **Navigate to the root of the SD card.** This will probably have a bunch of folders in it like "Download", "Pictures", etc. 5. **Copy the APK file to this folder.** This may take a few seconds! 6. After the file has been copied, you can eject and unplug your device from the computer. If you're having trouble, there are `many guides `_ on the Internet that describe this process. You can also take a look at the image below: .. image:: betaCopy.png :scale: 50% After you've copied the APK to your Android device, it's time to install it! It's really quite simple: 1. Open Astro on your Android device. 2. Navigate to the SD card. This is typically called ``sdcard0`` or something similar. 3. Find the APK you copied and click on it to "open" it. If Astro asks, choose to install the app. 4. You will be presented with a confirmation dialog. Choose "install". 5. That's it! You can now play the game. For a visualization of this process, take a look at the following image: .. image:: betaInstall.png :scale: 50% .. topic:: Important! If the developer decides to release an updated APK, you must repeat the above steps to update the version on your Android device. Installing the Extra Music Files -------------------------------- If you were provided with extra music files, you can install them very easily: 1. Unzip the file *musicPack.zip* on your computer. 2. Find the ``javamon`` folder that was created. 3. Copy the ``javamon`` folder to the root of the SD card on your Android device. This is just like copying the APK file, but it will take a bit longer. 4. You're done! Note that **you only have to install the music files ONCE** unless they are changed in a future release. The ``javamon`` folder goes in the same directory as the APK, as shown below: .. image:: betaMusic.png :scale: 50% .. topic:: What if I already have a ``javamon`` folder? If you've already installed and ran a JavaMon app, the ``javamon`` folder may already exist. This folder is used not only for music, but also for exporting your save file, error logs, etc. If you already have a ``javamon`` folder, you can just copy over it. On Windows, you will be asked if you want to overwrite any existing files—always choose "yes". Bug Reports ----------- Oh no, the game crashed! What do you do? **If you can still run the game normally:** 1. Open up the app again. 2. On the main screen, hold "Options" for at least 2 seconds. 3. The screen will automatically change to an "export log files" screen. 4. Choose "Export Logs". A visualization of this process is below: .. image:: betaBug.png :scale: 50% Once you've obtained the logs, navigate to the ``javamon/logs`` folder on your SD card. This folder will contain one or many subfolders, each with several ``*.log`` files. Zip up the entire ``logs`` folder and send it to the developer, along with a written description of what you were doing when the game crashed. The more detail you can provide, the better! **If you cannot run the game normally** (i.e. it crashes on startup), you should still send a report to the developer. Be sure to include the following information: * A written description of what you were doing when the game crashed. * The type of Android device you were using (the exact model number, if possible). * Any unusual circumstances: apps you were running, whether you received a phone call when the crash occurred, etc. The developer may attempt to walk you through a process to retrieve information via Android logs. However, this will not be covered in this guide. .. topic:: We Respect Your Privacy! The app logs recorded by JavaMon never contain **ANY** personally-identifying information. Logs only include the following: * The currently running JavaMon version. * The hardware on which JavaMon is running (CPU, GPU, etc.). * The pathnames of local/external storage (never their contents!). * Regular application messages: loading/saving the game, moving to a new map, debug information, etc. * Error stacktraces, used to identify why a crash occurred. JavaMon will *never* record information about any apps you are running. The only external files accessed by JavaMon are those located in the ``javamon`` folder.