Overhauled iOS and Android manuals. Separate dev app manual. Clarified detail in runner tutorial.

docs/en/en.json

@@ -315,6 +315,10 @@
                     {
                         "path": "/manuals/bob",
                         "name": "Bob the builder"
+                    },
+                    {
+                        "path": "/manuals/dev-app",
+                        "name": "The mobile dev app"
                     }
                 ]
             },

docs/en/manuals/android.md

@@ -5,7 +5,7 @@ brief: This manual describes how to build and run Defold applications on Android
 
 # Android development
 
-Android development differs from iOS development in that the devices give free access to upload content. It is very easy to build a version of your game and copy it onto an Android device. You can just as easily put the development engine on a device for iterative development on the device over wifi.
+Android devices allows you to freely run your own apps on them. It is very easy to build a version of your game and copy it onto an Android device. This manual explains the steps involved in bundling your game for Android. During development, running your game through the [development app](/manuals/dev-app) is often preferred since it allows you to hot reload content and code wirelessly directly to your device.
 
 ## Android and Google Play signing process
 
@@ -15,7 +15,49 @@ The process of creating certificates and keys may seem complicated but as long a
 
 It is important to note that when it is time to release an app on Google Play, you will need to create a certificate and key that you use to sign the app. The reason is that when you intend to publish an updated version of the app, _the updated *.apk* file needs to be signed with the same signature as the current version_. If you sign with a different private key, Google Play will reject the *.apk* update and you will need to publish the game as a totally new app.
 
-You can find more information from the [Google Play developer console](https://play.google.com/apps/publish/). See below for info on how to create your own certificates and keys.
+You can find more information from the [Google Play developer console](https://play.google.com/apps/publish/).
+
+## Creating certificates and keys
+
+You need the to create certificates in *.pem*-format and keys in *.pk8*-format. You can generate these with the `openssl` tool:
+
+```sh
+$ openssl genrsa -out key.pem 2048
+$ openssl req -new -key key.pem -out request.pem
+$ openssl x509 -req -days 9999 -in request.pem -signkey key.pem -out certificate.pem
+$ openssl pkcs8 -topk8 -outform DER -in key.pem -inform PEM -out key.pk8 -nocrypt
+```
+
+This will leave you with the files *certificate.pem* and *key.pk8* that you can use to sign your application bundles.
+
+::: important
+Make sure that you store your certificate and key safely. If you lose them you will _not_ be able to upload updated *.apk* file versions to Google Play.
+:::
+
+## Creating an Android application bundle
+
+The editor lets you easily create a stand alone application bundle for your game. Select <kbd>Project ▸ Bundle... ▸ Android Application...</kbd> from the menu.
+
+If you want the editor to automatically create random debug certificates, leave the *Certificate* and *Private key* fields empty:
+
+![Signing Android bundle](images/android/sign_bundle.png)
+
+If you want to sign your bundle with a particular certificate and key, specify the *.pem* and *.pk8* files:
+
+![Signing Android bundle](images/android/sign_bundle2.png)
+
+Press <kbd>Create Bundle</kbd> and you will then be prompted to specify where on your computer the bundle will be created.
+
+![Android Application Package file](images/android/apk_file.png)
+
+The editor writes an *.apk* file which is an Android application bundle. This file can be copied to your device with the `adb` tool (see below), or to Google Play via the [Google Play developer console](https://play.google.com/apps/publish/). You can specify what icon(s) to use for the app, set version code etc in the "game.project" project settings file.
+
+```
+$ adb install Defold\ examples.apk
+4826 KB/s (18774344 bytes in 3.798s)
+  pkg: /data/local/tmp/my_app.apk
+Success
+```
 
 ## Android Debug Bridge
 
@@ -25,25 +67,25 @@ Download the Android SDK from: http://developer.android.com/sdk/index.html. You
 
 On Ubuntu Linux:
 
-```sh
+```
 $ sudo apt-get install android-tools-adb
 ```
 
 On Fedora 18/19:
 
-```sh
+```
 $ sudo yum install android-tools
 ```
 
 On Mac OS X (Homebrew)
 
-```sh
+```
 $ brew cask install android-platform-tools
 ```
 
 You can veryfy that `adb` works by connecting your Android device to your computer via USB and issue the following command:
 
-```sh
+```
 $ adb devices
 List of devices attached
 31002535c90ef000    device
@@ -53,57 +95,11 @@ If your device does not show up, verify that you have enabled *USB debugging* on
 
 ![Enable USB debugging](images/android/usb_debugging.png)
 
-## Installing and running the development dmengine
-
-A stand-alone version of the Defold engine is available as a ready made *.apk* file that you can install on a device and use for iterative development wirelessly.
-
-* Visit http://d.defold.com where Defold downloads can be found.
-* Click on the version you want to download to expand a list of available engine builds.
-* Select *engine/armv7-android/dmengine.apk* for a debug enabled build for the Android platform (Armv7).
-
-![Download dmengine](images/android/download_dmengine.png)
-
-Download the file, then issue the following `adb` command from the location of the *.apk*:
-
-```sh
-$ adb install dmengine.apk
-4445 KB/s (8706017 bytes in 1.912s)
-	pkg: /data/local/tmp/dmengine.apk
-Success
-```
-
-The development "dmengine" app is now available on the device.
-
-![dmengine on the device](images/android/dmengine_on_device.png)
-
-## Launching the game
-
-To launch your game on your Android device, the dmengine app and editor must be able to connect over the same wifi network.
-
-1. Make sure the editor is up and running.
-2. Launch the "dmengine" app on the Android device.
-3. Select your device under <kbd>Project ▸ Targets</kbd> in the editor.
-4. Select <kbd>Project ▸ Build And Launch</kbd> to run the game. It may take a while for the game to start since the game content is streamed to the device over the network.
-
-While the game is running, you can use [hot reloading](/manuals/debugging#anchor-hr) as usual.
-
-## Creating an Android application bundle
-
-The editor lets you easily create a stand alone application bundle for your game. Select <kbd>Project ▸ Bundle... ▸ Android Application...</kbd> from the menu.
-
-![Signing Android bundle](images/android/sign_bundle.png)
-
-Select your code signing identity and browse for your mobile provisioning file. Press *Package* and you will then be prompted to specify where on your computer the bundle will be created.
-
-![Android Application Package file](images/android/apk_file.png)
-
-The editor writes an *.apk* file which is an Android application bundle. This file can be copied to your device with the `adb` tool, or to Google Play via the [Google Play developer console](https://play.google.com/apps/publish/). You can specify what icon(s) to use for the app, set version code etc in the "game.project" project settings file.
-
 ## Debugging an application bundle
 
 A bundle built with the debug mode version of the engine (i.e. "Release mode" unchecked during bundling) will send all its console output to the Android system log. Access the log with the `adb` tool and give the `logcat` command. You probably want to filter the output by a tag (`-s [tagname]`):
 
-```sh
+```
 $ adb logcat -s "defold"
 --------- beginning of /dev/log/system
 --------- beginning of /dev/log/main
@@ -116,39 +112,17 @@ D/defold  ( 6210): DEBUG:SCRIPT: Hello there, log!
 ...
 ```
 
-## Creating certificates and keys
-
-You need the to create certificates in *.pem*-format and keys in *.pk8*-format. You can generate these with the `openssl` tool:
-
-```sh
-$ openssl genrsa -out key.pem 2048
-$ openssl req -new -key key.pem -out request.pem
-$ openssl x509 -req -days 9999 -in request.pem -signkey key.pem -out certificate.pem
-$ openssl pkcs8 -topk8 -outform DER -in key.pem -inform PEM -out key.pk8 -nocrypt
-```
-
-This will leave you with the files *certificate.pem* and *key.pk8* that you can use to sign your application bundles:
-
-![Signing Android bundle](images/android/sign_bundle2.png)
-
-::: important
-Make sure that you store your certificate and key safely. If you lose them you will _not_ be able to upload updated *.apk* file versions to Google Play.
-:::
-
 ## Troubleshooting
 
-Your device does not appear in the Targets menu
-: Make sure that your device and computer are on the same wifi network. Also, the *dmengine* app needs to be of the same version as the editor. If you have upgraded the editor, you will need to download a new *dmengine.apk* and install it on your device.
-
 I'm getting "Failure [INSTALL_PARSE_FAILED_INCONSISTENT_CERTIFICATES]" when installing
 : Android detects that you try to install the app with a new certificate. When bundling debug builds, each build will be signed with a temporary certificate. Uninstall the old app before installing the new version:
 
-  ```sh
+  ```
   $ adb uninstall com.defold.examples
   Success
   $ adb install Defold\ examples.apk
   4826 KB/s (18774344 bytes in 3.798s)
-  	pkg: /data/local/tmp/Defold examples.apk
+          pkg: /data/local/tmp/Defold examples.apk
   Success
   ```
 

docs/en/manuals/dev-app.md

@@ -0,0 +1,76 @@
+---
+title: Running the development app on device
+brief: This manual explains how to put the development app on your device for iterative wireless development on device.
+---
+
+# The mobile development app
+
+The development app is a very convenient bare bones version of the engine that allows you to push content to it over wifi. You install the development app on your device(s), start the app and then select the device as a build target from the editor.
+
+## Signing the development app (iOS)
+
+Currently, at least one team member needs to run macOS and act as signer. The signer needs a code signing identity certificate installed on his/her computer. The signer also needs a mobile provisioning profile on his/her computer. (Note that the auto generated free provisioning profile Xcode can generate is only valid for one device)
+
+To upload a signed development app to the Defold Dashboard, the following steps are required:
+
+- In the editor, select <kbd>Project ▸ Sign iOS App...</kbd>
+- Select your code signing identity.
+- Browse for your mobile provisioning file.
+- Press the <kbd>Sign</kbd> button.
+
+![Signing the app](images/dev-app/sign.png)
+
+The Defold dev app is uploaded to the project page on the Dashboard.
+Each project member can now:
+
+- Browse to the Dashboard from their iOS device.
+- Open the project page from the list of projects.
+- Click the link *Install the Defold App*, which can be found below the *Members* section.
+
+![install the app](images/dev-app/install.jpg)
+
+## Installing the development dmengine (Android)
+
+A stand-alone version of the Defold engine is available as a ready made *.apk* file that you can install on a device and use for iterative development wirelessly.
+
+* Visit http://d.defold.com where Defold downloads can be found.
+* Click on the version you want to download to expand a list of available engine builds.
+* Select *engine/armv7-android/dmengine.apk* for a debug enabled build for the Android platform (Armv7).
+
+![Download dmengine](images/dev-app/download_dmengine.png)
+
+Download the file, then issue the following `adb` command from the location of the *.apk*:
+
+```sh
+$ adb install dmengine.apk
+4445 KB/s (8706017 bytes in 1.912s)
+    pkg: /data/local/tmp/dmengine.apk
+Success
+```
+
+The development "dmengine" app is now available on the device.
+
+![dmengine on the device](images/android/dmengine_on_device.png)
+
+## Launching your game
+
+To launch your game on your device, the dev app and editor must be able to connect, over the same wifi network.
+
+1. Make sure the editor is up and running.
+2. Launch the dev app on the device.
+3. Select your device under <kbd>Project ▸ Targets</kbd> in the editor.
+4. Select <kbd>Project ▸ Build And Launch</kbd> to run the game. It may take a while for the game to start since the game content is streamed to the device over the network.
+5. While the game is running, you can use [hot reloading](/manuals/debugging#_hot_reloading) as usual.
+
+![launch](images/dev-app/launch.png)
+
+## Troubleshooting
+
+Unable to download application
+: Make sure the your device UDID is included in the mobile provisioning that was used for signing the app.
+
+Your device does not appear in the Targets menu
+: Make sure that your device is connected to the same wifi network as your computer.
+
+The game does not start with a message about mis-matching versions
+: This happens when you have upgraded the editor to the latest version. On iOS you need to sign the app again (<kbd>Project ▸ Sign iOS App...</kbd>) which creates a new dev app from the current engine version. Then download the new app from the dashboard onto your device. On Android you will need to download a new *dmengine.apk* and install it on your device.

docs/en/manuals/ios.md

@@ -1,19 +1,19 @@
 ---
 title: Defold development for the iOS platform
-brief: This manual explains how to develop games and apps for iOS devices in Defold.
+brief: This manual explains how to build and run games and apps on iOS devices in Defold.
 ---
 
 # iOS development
 
-iOS development differs from Android development in that you have to be a registered developer to be able to put apps or games on an iOS device, even during development. iOS requires that all apps that are out on a phone or tablet are signed with an Apple-issued certificate and provisioning profile.
+iOS requires that _any_ app that you build and want to run on your phone or tablet _must_ be signed with an Apple-issued certificate and provisioning profile. This manual explains the steps involved in bundling your game for iOS. During development, running your game through the [development app](/manuals/dev-app) is often preferred since it allows you to hot reload content and code wirelessly directly to your device.
 
 ## Apple's code signing process
 
-The security associated with iOS apps consists of several components. To get access to the required tools, you need to sign up to the [Apple's iOS Developer Program](https://developer.apple.com/programs/). When you have enrolled, go to the [Apple's Developer Member Center](https://developer.apple.com/membercenter/index.action).
+The security associated with iOS apps consists of several components. You can get access to the required tools by singing up to the [Apple's iOS Developer Program](https://developer.apple.com/programs/). When you have enrolled, go to the [Apple's Developer Member Center](https://developer.apple.com/membercenter/index.action).
 
 ![Apple Member Center](images/ios/apple_member_center.png)
 
-The section *Certificates, Identifiers & Profiles* contains all the tools you need. From here you can create, delete and edit:
+The section *Certificates, Identifiers & Profiles* contains all the tools that you need. From here you can create, delete and edit:
 
 Certificates
 : Apple-issued cryptographic certificates that identify you as a developer. You can create development or production certificates. Developer certificates allow you to test certain features such as the in-app purchase mechanism in a sandbox test environment. Production certificates are used to sign the final app for upload to the App Store. You need a certificate to sign apps before you can put them on your device for testing.
@@ -22,10 +22,10 @@ Identifiers
 : Identifiers for various uses. It is possible to register wildcard identifiers (i.e. `some.prefix.*`) which can be used with several apps. App IDs can contain Application Service information, like if the app enables Passbook integration, the Game Center, etc. Such App IDs cannot be wildcard identifiers. For Application Services to function, your application's *bundle identifier* must match the App ID identifier.
 
 Devices
-: Each development device needs to be registered with their UDID (Unique Device IDentifier). See below for details on how to find the UDID of your device.
+: Each development device needs to be registered with their UDID (Unique Device IDentifier, see below).
 
 Provisioning Profiles
-: Provisioning profiles associate certificates with App IDs and specific devices. They basically tell which app by what developer is allowed to be on what devices.
+: Provisioning profiles associate certificates with App IDs and a list of devices. They tell which app by what developer is allowed to be on what devices.
 
 When signing your games and apps in Defold, you need a valid certificate and a valid provisioning profile.
 
@@ -33,80 +33,59 @@ When signing your games and apps in Defold, you need a valid certificate and a v
 Some of the things you can do on the Member Center homepage you can also perform from inside the XCode development environment---if you have that installed.
 :::
 
-## Device UDID
+Device identifier (UDID)
+: The UDID for an iOS device can be found by connecting the device to a computer via wifi or cable. Open Xcode and select <kbd>Window ▸ Devices and Simulators</kbd>. The serial number and identifier are displayed when you select your device.
 
-The UDID for an iOS device can be found by connecting the device to a computer via wifi or cable. Open up iTunes and click on the devices symbol. Select your device.
+  ![xcode devices](images/ios/xcode_devices.png)
 
-![iTunes devices](images/ios/itunes_devices.png)
+  If you don't have Xcode installed you can find the identifier in iTunes. Click on the devices symbol and select your device.
 
-On the *Summary* page, locate the *Serial Number*.
+  ![itunes devices](images/ios/itunes_devices.png)
 
-![Device UDID step 1](images/ios/udid.png)
+  1. On the *Summary* page, locate the *Serial Number*.
+  2. Click the *Serial Number* once so the field changes into *UDID*. If you click repeatedly, several pieces of information about the device will show up. Just continue to click until *UDID* shows.
+  3. Right-click the long UDID string and select <kbd>Copy</kbd> to copy the identifier to the clipboard so you can easily paste it into the UDID field when registering the device on Apple's Developer Member Center.
 
-Click the *Serial Number* once so the field changes into *UDID*. If you click repeatedly, several pieces of information about the device will show up. Just continue to click until *UDID* shows. Right-click the long UDID string and select <kbd>Copy</kbd> to copy the identifier to the clipboard so you can easily paste it into the UDID field when registering the device on Apple's Developer Member Center.
+## Developing using a free Apple developer account
 
-![Device UDID step 2](images/ios/udid_2.png)
+Since Xcode 7, anyone can install Xcode and do on-device development for free. You don't have to sign up for the iOS Developer Program. Instead, Xcode will automatically issue a certificate for you as a developer (valid for 1 year) and a provisioning profile for your app (valid for one week) on your specific device.
 
-## Signing the Defold development app
+1. Connect your device.
+2. Install Xcode.
+3. Add a new account to Xcode and sign in with your Apple ID. 
+4. Create a new project. The simplest "Single View App" works fine.
+5. Select your "Team" (auto created for you) and give the app a bundle identifier.
+6. Make sure that Xcode has created a *Provisioning Profile* and *Signing Certificate* for the app.
+  
+   ![](images/ios/xcode_certificates.png)
 
-The development app is a very convenient version of the engine that allows you to push content to it over wifi. You install the development app on your device(s), start the app and then select the device as a build target from the editor.
+7. Build and launch the app on your device. The first time, Xcode will ask you to enable Developer mode and will prepare the device with debugger support. This may take a while.
+8. When you have verified that the app works, find it on your disk. You can see the build location in the Build report in the "Report Navigator".
 
-Currently, at least one team member needs to run OS X and be a registered Apple Developer in order to sign the development app for other team members. We will call this person the _signer_.
+   ![](images/ios/app_location.png)
 
-* The signer needs a certificate installed on his/her computer.
-* The signer needs a mobile provisioning profile on his/her computer.
-* The signer needs to collect all the UDIDs from other members and add these to his/her mobile provisioning file.
+9. Locate the app, right-click it and select <kbd>Show Package Contents</kbd>.
 
-To upload a signed development app to the Defold Dashboard, the following steps are required:
+   ![](images/ios/app_contents.png)
 
-- In the editor, select <kbd>Project ▸ Sign iOS App...</kbd>
-- Select your code signing identity.
-- Browse for your mobile provisioning file.
-- Press the *Sign and upload* button.
+10. Copy the file "embedded.mobileprovision" to some place on your drive where you will find it.
 
-![Signing the app](images/ios/sign.png)
+   ![](images/ios/free_provisioning.png)
 
-The Defold dev app is uploaded to the project page on the Dashboard.
-Each project member can now:
+This provision file can be used together with your code signing identity to sign apps in Defold for one week, for _one device_. There is no way to add additional device UDIDs to this generated provisioning profile.
 
-- Browse to the Dashboard from their iOS device.
-- Open the project page from the list of projects.
-- Click the link *Install the Defold App*, which can be found below the *Members* section.
-
-This video shows the whole process:
-
-<iframe width="560" height="315" src="https://www.youtube.com/embed/T_igYdHubqA" frameborder="0" allowfullscreen></iframe>
-
-## Launching the game
-
-To launch your game on your iOS device, the Defold dev app and editor must be able to connect, over the same wifi network.
-
-- Make sure the editor is up and running.
-- Launch the Defold dev app on the iOS device.
-- Select your device under <kbd>Project ▸ Targets</kbd> in the editor.
-- Select <kbd>Project ▸ Build And Launch</kbd> to run the game. It may take a while for the game to start since the game content is streamed to the device over the network.
-- While the game is running, you can use [hot reloading](/manuals/debugging#_hot_reloading) as usual.
+When the provision expires, you need to build the app again in Xcode and get a new temporary provision file as described above.
 
 ## Creating an iOS application bundle
 
-You can also easily create a stand alone application bundle for your game from the editor. Simply select <kbd>Project ▸ Bundle... ▸ iOS Application...</kbd> from the menu.
+When you have the code signing identity and privisioning profile, you are ready to create a stand alone application bundle for your game from the editor. Simply select <kbd>Project ▸ Bundle... ▸ iOS Application...</kbd> from the menu.
 
 ![Signing iOS bundle](images/ios/sign_bundle.png)
 
 Select your code signing identity and browse for your mobile provisioning file. Press *Package* and you will then be prompted to specify where on your computer the bundle will be created.
 
-![ipa iOS application bundle](images/ios/ipa_file.png){.left}
+You specify what icon to use for the app, the launch screen image and so forth on the *game.project* project settings file.
 
-The editor writes an *.ipa* file which is an iOS application bundle. This file you can drag and drop into iTunes and it will install on your device during the next sync. You can specify what icon to use for the app, the launch screen image and so forth on the *game.project* project settings file.
-
-## Troubleshooting
-
-Unable to download application
-: Make sure the signer has included your UDID in the mobile provisioning  that was used for signing the app.
-
-Your device does not appear in the Targets menu
-: Make sure that your device is connected to the same wifi network as your computer.
-
-The game does not start with a message about mis-matching versions
-: This happens when you have upgraded the editor to the latest version. You need to sign the app again (<kbd>Project ▸ Sign iOS App...</kbd>) which creates a new dev app from the current engine version. Then download the new app from the dashboard onto your device.
+![ipa iOS application bundle](images/ios/ipa_file.png){.left}
 
+The editor writes an *.ipa* file which is an iOS application bundle. To install the file on your device, you can use Xcode (via the "Devices and Simulators" window). Other options are to use a command line tool such as [ios-deploy](https://github.com/phonegap/ios-deploy) or iTunes.

docs/en/tutorials/runner.md

@@ -457,7 +457,7 @@ Now that we have a hero character set up with collision and all, we need to also
 2. Open the new file, right-click the root in the *Outline* and select <kbd>Add Collection from File</kbd> and choose *ground.collection*.
 3. In *level.collection*, right-click the root in the *Outline* and select <kbd>Add Game Object File</kbd> and choose *hero.go*.
 4. Now, create a new folder called *level* in the project root (right-click the white space below *game.project* and select <kbd>New ▸ Folder</kbd>), then move the level assets you have created so far to it: the files *level.collection*, *level.atlas*, the "images" folder holding the images for the level atlas, and the files *ground.collection* and *ground.script*.
-5. Open *main.collection* and replace *ground.collection* with *level.collection*.
+5. Open *main.collection*, delete *ground.collection* and instead add *level.collection* (right-click and <kbd>Add Collection from File</kbd>) which now contains the *ground.collection*. Make sure that you place the collection at position 0, 0, 0.
 
 ::: sidenote
 As you might have noticed by now, the file hierarchy seen in the *Project Explorer* is decoupled from the content structure you build in your collections. Individual files are referenced from collection- and game object files, but their location is completely arbitrary.
@@ -519,7 +519,7 @@ end
 ![Add ground code](images/runner/insert_ground_code.png)
 
 <a name="part-6"></span></a>
-# STEP 6 - Ground physics and platforms
+## STEP 6 - Ground physics and platforms
 
 At this point we should add physics collision for the ground: