====== FlashDevelop ======

This document aims to help you set up [[http://www.flashdevelop.org|FlashDevelop]] to use with Starling for desktop and mobile development.

<note tip>If you find an error or a missing step, or if you have some other suggestion that might make things clearer for beginners, please help us out by enhancing this document! Just hit one of the ''Edit'' buttons and write away.</note>

===== General Setup =====

  * Download and install FlashDevelop.
    * Get the latest installer from [[http://www.flashdevelop.org/community/viewforum.php?f=11|here]].
    * If you need help during installation, [[http://www.flashdevelop.org/wikidocs/index.php?title=Installation|this document]] contains further information.
  * Launch FlashDevelop.
  * The easiest way to install the required SDKs and runtimes is with the integrated "AppMan". 
    * "AppMan" will automatically open up the first time you launch FlashDevelop. 
    * Later, it's available via "Tools -> Install Software"
  * Inside "AppMan", these are the dependencies you will need to install:
    * Select "Compilers / AIR SDK + ASC 2.0"
    * Select "Runtimes / Flash Player (SA)"
    * Click "Install 2 items"
    * When done, close "AppMan"
    * At this point, I had to restart FlashDevelop for the installed SDKs to show up.

<note tip>
You already downloaded the AIR SDK manually? In that case, you don't need "AppMan", but you need to tell FlashDevelop where to find the SDK.

Go to: "Tools -> Program Settings... -> AS3 Content -> Installed Flex SDK's (hit the square to the right of this with the 3 dots in it) -> Add -> Path (again, in the square) and point it to your SDK.
</note>

===== Project Setup =====

  * Enter "Project -> New Project" and pick one of the following:
    * "AS3 Project" for a Flash Player SWF project
    * "AIR Mobile AS3 App" for an iOS or Android app
    * "AIR AS3 Projector" for an Desktop application
    * "AS3 Library SWC" for an SWC library project (like Starling)
  * Set Name & Location
  * Add Starling:
    * Via "Project -> Properties", add a classpath that points to ''starling/src'' within the Starling download/Git folder. (**recommended**)
    * Or create a ''lib'' folder in your project and copy ''starling.swc'' into it; then go to "Project -> Properties -> Compiler Options -> SWC Libraries" and add the entry ''lib/starling.swc''.

<note tip>If you are a beginner and want to get started quickly, I recommend you create an "AS3 Project" that runs in the standalone Flash Player (the so-called "Projector). That's easiest to set up. Then, add the code shown in the [[http://manual.starling-framework.org/en/#_hello_world|Hello World]] example shown in the Starling Manual.</note>

=== AIR only: Configuring "application.xml" ===

Open the file ''application.xml'' that's part of your project.
You need to make sure about two things:

  * The ''xmlns'' must point to the same AIR version that you installed via "AppMan". The sample below shows the value for "AIR 24".
  * Make sure that ''renderMode'' is set to ''direct''. That's required so that Starling may use Stage3D.

<code xml>
<application xmlns="http://ns.adobe.com/air/application/24.0">
<initialWindow>
  <!-- ... -->
  <renderMode>direct</renderMode>
</initialWindow>
</code>

<note important>The "application.xml" file is only required for AIR projects, not for AS3 Projects that target just the Flash Player.</note>

=== Configuring the Project's SDK ===

  * In "Project -> Properties", make sure that the latest AIR SDK is selected. (The one you installed via "AppMan".)
  * To make sure you can use all the features of the AIR SDK, you have to set the correct "SWF Version".
    * Find the correct SWF version for your AIR SDK here: [[https://www.adobe.com/devnet/articles/flashplayer-air-feature-list.html|Adobe AIR Feature List]] 
    * Navigate to "Project -> Properties -> Compiler Options -> Additional Compiler Options".
    * Add an entry like this: ''-swf-version=35''

=== Configuring "RunApp.bat" ===

This batch file is executed when you hit "Test Project" (F5).

  * The section '':target'' controls how you want to launch/debug your application. For example, 
    * if "goto desktop" is uncommented, you will debug on the Desktop via "adb".
    * if "goto android-debug" is uncommented, the app will be installed and started on an attached Android device.
  * The section '':desktop'' controls the screen resolution used in the adb debugger.
    * For a list of supported screen sizes, refer to [[http://help.adobe.com/en_US/air/build/WSfffb011ac560372f-6fa6d7e0128cca93d31-8000.html|this document]].
==== Notes for iOS =====

Any mobile project setup with FlashDevelop will contain a file [[https://github.com/fdorg/flashdevelop/blob/development/External/Extensions/AS3Templates/%24(BaseDir)/Projects/190%20ActionScript%203%20-%20AIR%20Mobile%20AS3%20App/AIR_iOS_readme.txt|AIR_iOS_readme.txt]]. It contains detailed informations about how to work with iOS. **Follow these instructions!**

<note tip>
To make a release build, execute the "**PackageApp.bat**" script located in your project folder and choose "**ipa-ad-hoc**" or "**ipa-app-store**" when prompted. It's not enough to only choose the "Release" configuration in FlashDevelop and build the project .
</note>

==== Notes for Android =====

Any mobile project setup with FlashDevelop will contain a file [[https://github.com/fdorg/flashdevelop/blob/development/External/Extensions/AS3Templates/%24(BaseDir)/Projects/190%20ActionScript%203%20-%20AIR%20Mobile%20AS3%20App/AIR_Android_readme.txt|AIR_Android_readme.txt]]. It contains detailed informations about how to work with Android. **Follow these instructions!**

  * If you need help enabling USB debugging on your device this document contains some more details: [[https://developer.android.com/studio/run/device.html|Run Apps on a Hardware Device]]
  * You will also need a certificate with which to sign the app. Create it using /bat/CreateCertificate.bat and wait a minute.

<note tip>
To test the performance of Starling, always make a release build.
</note>

===== General Tips =====

==== Code Completion ====

FlashDevelop helps insert ''import'' statements in several ways.

When declaring something, if the class import hasn't been added yet, code completion will present a list of possible imports. Using arrow keys to select one and hitting enter will add the import code.

{{ :manual:flashdevelop-code-completion.gif?nolink |}}

The other way is to place the cursor on the class name and press "CTRL + SHIFT + 1".
For example, if you were to write:

<code as3>
var bytes:ByteArray
</code>

Drop the cursor on ByteArray and try pressing "CTRL + SHIFT + 1". That's if FlashDevelop doesn't automatically add the import (which it should if you complete the line with a semi-colon).

If the import hasn't been added, it will be added immediately, or a list will be presented with options if multiple classes with the same name are found (common when using Starling).

"CTRL + SHIFT + 1" is FlashDevelop's "Code Generator" shortcut, a super handy shortcut that does all sorts of wonderful things depending on the context where it's used.

==== Adding Resources to an AIR project ====

You will want to add files to an AIR project so that they are bundled with the application (allowing you to load them at runtime). In FlashDevelop, that happens with all the files found in the ''bin'' directory.

However, you probably don't want to place your assets in that folder -- the bin folder is normally supposed to only contain files that are generated in the build-process.

Instead, I recommend you modify the file ''RunApp.bat'' so that it automatically clears all contents of the ''bin'' folder and then repopulates it with the contents of the ''assets'' folder (that's where you would put your assets).

  * To do that, edit the file ''bat/RunApp.bat'' and find the line that says:

<code winbatch>
set PAUSE_ERRORS=1
</code>

  * Now add this on a new line after it:

<code winbatch>
:: Clear bin folder and copy over assets to be packaged.
for /D %%p IN ("bin\*.*") DO rmdir "%%p" /s /q
xcopy "assets" "bin" /s /c /y /i /q
</code>

===== Troubleshooting =====

> When I start the debug launcher, it says: ''error while loading initial content''

You probably forgot to update ''application.xml'' so that it points to the same XML schema version as the AIR SDK you're using. Open it up and change the version number at the end of the ''application'' XML tag.