This section contains some important things to know when you create an application for Android devices. Please read it carefully and keep it in mind when programming you application.

Permissions

Some features require special user permissions. If you use these features, you must select the corresponding permissions in the Android properties of the application, else the application won’t work. Here is the list of permissions to activate for the following features :

• If you use other extension objects for Android, refer to their documentation to see what Android permissions you need to select.

Runnning the application on various devices

Android devices use different resolutions. You can use the options in the properties of the application to adapt your window size to the size of the devices.

Fonts

PC fonts are replaced by the default Android font.

HWA features

The graphic engine of the Android runtime is hardware accelerated, it supports some of the HWA features of Clickteam Fusion 2.5, including the Blending and RGB coefficients. It doesn’t support shaders, layer effect or frame effects.

Sounds

• OGG: the Android devices support OGG sound files. This is the preferred format.
• MP3: Android supports MP3 sounds. The Android exporter for Clickteam Fusion 2.5 adds an MP3 filter to allow you to insert MP3 sounds into your applications. Avoid playing several MP3 sounds, you should use MP3 sounds for background music. You can also use the MP3 filter to play MP3 sounds in your Windows applications, however this filter just calls the decoding API of Windows, so it depends on codecs that are installed on the user’s machine (Windows is usually provided with a MP3 codec though). Note: if you redistribute an application that contains MP3 sounds you may need to get a MP3 license (at the date this documentation was written, a license was not required for any entity with a MP3-related gross revenue less than $100,000, but the terms of this license may change, check them from time to time on mp3licensing.com).
• Other formats: the sound files that are not in OGG or MP3 format are converted to uncompressed WAV format.

Storing data

You can write files to the data folder of the application, you do not need special permissions for this, use the DataStorageDirectory$ expression of the Android object to retrieve the pathname of this directory. The Android object also contains an expression to retrieve the pathname of the external storage directory, typically the SD card. Note: if you want to write data to this external storage directory you need to enable the WRITE_EXTERNAL_STORAGE permission in the Android properties of your application.

Embedded Files

• If you want to pass initialization files to objects like Active Picture, INI, List Box, etc, just add them to the Binary Data tab in the Data Elements editor. For example, if you want to display landscape.png with an Active Picture object, add this file to the Binary Data tab in the Data Element editor and load it as you would do it on PC in the Active Picture object.

• Note 1: on Android the directory pathname of the files in the Binary Data tab is ignored. If 2 files have the sane name only the first one will be used.
• Note 2: in the Android runtime, if you initialize the INI object with a predefined INI file stored in the Binary Data tab, the INI file will be stored in the folder of the application on the Android device only if it doesn’t exist already. So, if you want to change the content of the INI file you pass in the Binary Data tab, don’t forget to erase the data of your application in the Android parameters of your device.
• Note 3: if you use the Unicode version of Clickteam Fusion 2.5 and want to use Unicode characters in text files you pass to the List Box, Combo Box or INI objects via the Binary Data tab, make sure these files are in UTF-8 format (if you are not sure, edit them with Notepad, select Save As and set the character set option in the file selector to UTF-8). Also the INI file should start with an empty line.

Memory considerations

Android devices are portable devices. As such, the amount of usable memory (RAM, not to be confused with Flash memory where the files are stored) is limited.

The conclusion is that if you want your application to work on an Android device, you have to be very careful about the size of your graphics and sounds. The next section will give you tips to reduce the memory imprint of your graphics.

How to find out exactly how much memory your application takes?

The amount of memory used by an application is shown in the debugger window (top left of the screen) when you launch your application in Clickteam Fusion 2.5. The memory displayed is evaluated for a PC application and does not reflect the amount of RAM really taken by your application under Android.

How to save memory for your graphics?

Alpha-channels
Alpha-channels look awesome and give a visually pleasing effect but they will slow down your game if you overuse them, just as they do in the PC runtime (only more).
An image with an alpha-channel takes 33% more memory and space than an image without and it takes more power and time to render them.

Workaround:
Does your graphic really need the alpha-channel? Does the background underneath it ever change? If not you could probably “bake” the alpha-channel effect into the image itself so that the shadow is just part of the picture.

Huge pictures
Many are often tempted to import really large pictures into the game where it will only show very little of that picture at one time. Some good advice is to break it up into smaller parts so that fewer of them are shown at one time. Remember that any image you have in your game has to fit inside their texture. In a sample game there was a 960×480 sized background image on a frame. This picture alone had to fit into a 1024×512 texture taking up a huge amount of memory. What was even worse was that it had an alpha-channel even though no pixel in it was transparent. Second, the same frame had two different huge animations sized 957×158 (each of them contained 17 frames). This already takes up 2*17 * 1024*256 * 3 = 26738688 bytes = 25.5 MB of RAM which is way above what Android likes. That was even without the rest of the graphics and the huge background image we talked about before.

Workaround:
Most graphics don’t need 100% crispness and quality. It will only take 1/4th of the previous memory usage if you cut your image size in half and then at runtime scale it to 2.0. It will also run much faster as it utilizes the graphics card RAM cache much better.

Tip:
Crop your images, remove any useless empty space around them. Some developers tend to use a single frame size for an entire animation with huge transparent parts in some images. It’s probably better at design time, but at runtime it results in a loss of time and space.

Tip:
Try to make your graphics of a size close a power-of-two. It will waste less precious memory.
A power-of-two size is one of the following: 8,16,32,64,128,256,512,1024 Images less than 8×8 pixels will be stored in a 8×8 texture as they cannot be smaller than that.
You can easily use different sizes for your width and height, they don’t have to be equal.

Tip:
Be sure to set the “Image compression” property to “Color reduction” either globally for all objects in the App Android properties or per object, as often as you can. In many cases, it will consume half the memory it did before.
Take for example the big background image mentioned above. It wasted 2 MB of texture memory. With color compression and no alpha channel it will only take 1 MB. If it was cropped to only fill out the resolution of the iPhone device it would only take 30 KB. The animations mentioned before that took 25 MB of RAM can with color compression and half the resolution only take: 2*17 * 512*128 * 2 = 4456448 bytes = 4.25 MB! That is a huge difference.

Single color graphic
This is kinda an extension to the previous pitfall. We have often seen in the sample games we have debugged some big actives (typical white) that are meant to cover the entire screen and fade to transparent. People need to realize that even though they are pure white (or whatever color) they are still stored in memory uncompressed at runtime and waste just as much memory as if it was a pretty picture. If you need those fade-effects, you can scale a small active to fit the screen at runtime and gradually alter it’s semi-transparency.

Speed considerations

Overuse of “text” counters/score and strings Although it may not be a big issue, it can hurt the performance of your game if you use too many objects that draw text. If the text doesn’t change, it should not be a performance problem, but if you update your string/score/counters often you will get a performance problem.

Workaround:
– Only use text whenever you know it will not change often (like every frame).
– Use bitmap counters/scores instead of text counters/scores. You can much better control the visual style of your objects and there is nearly no performance penalty.

Unnecessary effects
We have seen other games almost ready for release where effects are unnecessarily used often. Having a big background covering the screen and setting it to either transparent or ADD so that it will be added to some gradient behind it, will only make your game slower and consume more power. Instead, make your graphics as they should look at runtime and then use them like that. Effects are only meant for places where you cannot modify the original image to look like it should at edit time. For example, if you want a grayscale background from a picture, make it grayscale before you import it into Clickteam Fusion 2.5. You simply don’t put the monochrome effect on it and forget about it.