преди 8 години · 198e638ef0
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
 
				-.DS_Store
			
 
				+.DS_Store
			
 
				+build
			
--- a/README.md
+++ b/README.md
@@ -1,3 +1,11 @@
 
				 # Defold manuals
			
 
				 
			
 
				-This repo holds the markdown source files and assets for Defold documentation.
			
 
				+This repo holds the markdown source files and assets for Defold documentation.
			
 
				+
			
 
				+To build documentation type `make´.
			
 
				+
			
 
				+## Dependencies
			
 
				+
			
 
				+The translation from Markdown (Commonmark) to HTML5 is done with cmark (https://github.com/jgm/cmark). To build it you need `cmake` on your system.
			
 
				+
			
 
				+Publishing documentation is done with the `gsutil` which is part of the Google Cloud SDK.
			
--- a/docs/index.html
+++ b/docs/index.html
@@ -0,0 +1,7 @@
 
				+<html>
			
 
				+<body>
			
 
				+    <h1>Defold documentation</h1>
			
 
				+    You find all docs here: <a href
			
 
				+
			
 
				+</body>
			
 
				+</html>
			
--- a/docs/manuals/en/2dgraphics.md
+++ b/docs/manuals/en/2dgraphics.md
@@ -0,0 +1,250 @@
 
				+2D Graphics
			
 
				+===========
			
 
				+
			
 
				+2D games are commonly built by many images that are presented as is (for backgrounds or sprites), used in _flip-book animation_ (for sprites), combined and rigged to create _Spine animation_ (for sprites) or mapped out into tilemaps and used for levels or backgrounds. This manual details Defold's support for these 2D graphical elements.
			
 
				+
			
 
				+For performance reasons, images are often combined into one or a few larger images, but the small original image can still be referenced as a sub-image on the larger one. Combining smaller images into larger is especially important on mobile devices where memory and processing power is more scarce than on desktop machines or dedicated game consoles.
			
 
				+
			
 
				+In Defold, there are two types of asset that represent such a larger image:
			
 
				+
			
 
				+Atlases
			
 
				+: An _atlas_ contains a list of separate images files, which are automatically combined into a larger image. See http://en.wikipedia.org/wiki/Texture_atlas
			
 
				+
			
 
				+
			
 
				+Tile Sources
			
 
				+: A tile source references an image file that is already containing sub-images ordered on a uniform grid. Other tools sometimes use the terms _tile set_ and _sprite sheet_ for this type of image. See http://en.wikipedia.org/wiki/Tileset#Tile_set
			
 
				+
			
 
				+
			
 
				+## Importing Image Files
			
 
				+
			
 
				+Defold needs all assets that should be in your project hierarchy. Therefore you should start by importing the image files you want to build your graphics from. To import image assets, simply drag the files from the file system on your computer and drop them in an appropriate place in the Defold editor _Project Explorer_.
			
 
				+
			
 
				+::: important
			
 
				+Currently, Defold only support the PNG image format.
			
 
				+:::
			
 
				+
			
 
				+![Importing image files](images/2dgraphics/2dgraphics_import1.png)
			
 
				+
			
 
				+![Importing image files](images/2dgraphics/2dgraphics_import2.png)
			
 
				+
			
 
				+## Creating an Atlas
			
 
				+
			
 
				+You need to populate an _Atlas_ before you can use it. As soon as you have added images and/or animations to the Atlas, it can be used as a graphics source to object components like Sprites and ParticleFX components.
			
 
				+
			
 
				+Your atlas has now been populated with images (and animations) it can be used as a graphics source to other components in Defold (see Sprite below and the ParticleFX guide).
			
 
				+
			
 
				+1. Import your image files as described above.
			
 
				+2. Select [[New ▸ Atlas File]]{.menu} from the context menu in the Project Explorer.
			
 
				+3. Select *Add Images* from the context menu in the Outline.
			
 
				+
			
 
				+A dialog opens from where you can find and select the images you want to add to the Atlas. Note that you can filter the image files and select multiple files at once.
			
 
				+
			
 
				+![Creating an atlas, adding images](images/2dgraphics/2dgraphics_atlas_add.png)
			
 
				+![Creating an atlas](images/2dgraphics/2dgraphics_atlas.png)
			
 
				+
			
 
				+## Defining flip-book animations
			
 
				+
			
 
				+You can define flip-book animations of selected sub-images in an atlas:
			
 
				+
			
 
				+- Select *Add Animation Group* from the context menu in the Outline.
			
 
				+- Select *Add Images* from the context menu of the created animation group and choose the images that you want as frames of the animation.
			
 
				+- Adjust the *Properties* for the animation as needed.
			
 
				+
			
 
				+You can reorder the images in the Outline by dragging them, if needed. You can also easily create duplicates by copying and pasting (From the *Edit* menu, the right click context menu or keyboard shortcuts) images in the outline. Select an animation and press *Space* on your keyboard to preview the animation.
			
 
				+
			
 
				+## Creating a Tile Source
			
 
				+
			
 
				+To create a Tile Source you need an image containing all the tiles. All tiles must have the exact same dimensions and be placed in a grid. Defold supports _spacing_ between the tiles and _padding_ around each tile. Defold can also automatically _extrude borders_ which is sometimes neccessary to avoid visual artifacts.
			
 
				+
			
 
				+Once you have the source image created, you can create a Tile Source:
			
 
				+
			
 
				+- Import the image to your project by dragging it into the Project Explorer.
			
 
				+- Create a new Tile Source file.
			
 
				+- Click the browse-button next to the *Image* property and select your image. Now you should see the image displayed in the editor.
			
 
				+- Adjust the *Tile Height*, *Tile Width*, *Tile Margin* and *Tile Spacing* to match the source image. When everything is correctly set you should see the tiles line up perfectly inside each cell of the transparent grid.
			
 
				+
			
 
				+![Creating a Tile Source](images/2dgraphics/2dgraphics_tilesource.png)
			
 
				+
			
 
				+::: sidenote
			
 
				+If you use linear filtering (see below) and a Tile Source where each tile lies immediately next to each other (i.e. has no borders), there is a risk that you will experience a visual artifact called edge bleeding: if a neighboring tile has colored pixels on its edge, their color might bleed over at the edges. The easiest way to fix this problem is to set the *Extrude Border* property (which can be found on Atlases and Tile Sources). The value specifies how many times the edge pixels should be automatically replicated in the final texture used in when the game is run.
			
 
				+
			
 
				+A good measure is to specify a number that corresponds to how much you scale the textures when viewed in game. If you display the game world at half scale (you can see 2 times as much) then set *Extrude Borders* to 2. When the texture is used scaled down to half the size, a _mipmap_ is used for rendering. That mipmap is half the width and height of the original image.
			
 
				+:::
			
 
				+
			
 
				+## Tile Source collision shapes
			
 
				+
			
 
				+Collision shapes that enable physics interaction with Tile Maps can be automatically generated. Defold uses the alpha channel from the image specified in the *Collision* property to generate a _convex_ shape for each tile. Often it is sensible to use the same image for collision as the one containing the actual graphics, but you are free to specify a separate image if you want collision shapes that differ from the visuals. When you specify a collision image, the preview is updated with an outline on each tile indicating the generated collision shapes. See the [Physics documentation](/manuals/physics) for more details.
			
 
				+
			
 
				+![Collision Shapes](images/2dgraphics/2dgraphics_tilesource_collision.png)
			
 
				+
			
 
				+## Tile Source flip-book animations
			
 
				+
			
 
				+To define an animation in a Tile Source each frame must correspons to one tile (be on a grid of a certain width and height). Each frame tile must lie next to each other in a sequence left to right. The sequence can wrap from one row to the next. All newly created Tile Sources has a default animation named "anim". Selecting it displays the animation *Properties* that allow you to set a descriptive name, start and end frame, playback method and speed and whether the animation should be visually flipped horizontally or vertically.
			
 
				+
			
 
				+![Tile Source add animation](images/2dgraphics/2dgraphics_tilesource_animation.png)
			
 
				+
			
 
				+You can easily add more animations to the Tile Source by selecting *Add Animation* in the context menu that can be accessed by right clicking the root *Tile Source* in the Outline view.
			
 
				+
			
 
				+![Tile Source animation](images/2dgraphics/2dgraphics_tilesource_add_animation.png)
			
 
				+
			
 
				+## Manipulating Game Objects and components
			
 
				+
			
 
				+When you add visual components (Sprites, ParticleFX etc) to a game object, you are able to set the _position_ and _rotation_ of the component. These values are used as offsets against the position and rotation of the game object. And more, the values are _set_ in the component when you assemble the game object.
			
 
				+
			
 
				+![Component position](images/2dgraphics/2dgraphics_component_position.png)
			
 
				+
			
 
				+Defold game objects can be moved, rotated and have any of its properties animated. Components belonging to a manipulated game object undergo the same manipulations as the game object, but will keep their relative position and rotation as set in the game object. Components can be turned on and off, but are not possible to animate or move or rotate dynamically (with an exception described below). Therefore, if you have graphics that you intend to alter you should put the graphics in separate game objects. A group of game objects or a game object hierarchy is conveniently assembled in a Collection. Then you can freely manipulate the objects through script:
			
 
				+
			
 
				+![Component position](images/2dgraphics/2dgraphics_gameobject_position.png)
			
 
				+
			
 
				+```lua
			
 
				+-- Animate the wand game object to specified position and rotation.
			
 
				+go.animate("wand", "position", go.PLAYBACK_ONCE_FORWARD, vmath.vector3(530, 79, -0.1), go.EASING_INOUTSINE, 0.5)
			
 
				+go.animate("wand", "euler", go.PLAYBACK_ONCE_FORWARD, vmath.vector3(0, 0, -70), go.EASING_INOUTSINE, 0.5)
			
 
				+```
			
 
				+
			
 
				+## Dynamically scaling Sprites
			
 
				+
			
 
				+It is actually possible to dynamically alter the scale of Sprite components in a non uniform way. This is a special feature that may feel odd when you try to construct a mental model for how game objects and components are related to each other and how to work with them.
			
 
				+
			
 
				+Sprites have a property "scale" which is of type `vmath.vector3`. You can animate the components separately:
			
 
				+
			
 
				+```lua
			
 
				+go.animate("my_object#sprite", "scale.x", go.PLAYBACK_ONCE_FORWARD, 1.5, go.EASING_INOUTSINE, 2)
			
 
				+```
			
 
				+
			
 
				+## Sprites
			
 
				+
			
 
				+Sprite components are used to add graphics and flip-book animations to game objects. They are typically used to create characters and props. Creating a Sprite component is very straightforward:
			
 
				+
			
 
				+- Create (or open) the game object the Sprite should belong to.
			
 
				+- From the Game Object context menu in the Outline, select *Add Component*.
			
 
				+- Choose "Sprite".
			
 
				+- Specify in the Sprite's *Image* property which Tile Source or Atlas the Sprite should use.
			
 
				+- Specify in the Sprite's *Default Animation* property which animation it should play by default.
			
 
				+
			
 
				+The default animation is played when the game object is created in the running game. Note that if you use an Atlas as the image resource you will see still images as well as animations in the *Default Animation* drop down menu. If you want to create a Sprite with a still image out of a Tile Source, you can create a 1 frame animation and set its *Playback* property to "None".
			
 
				+
			
 
				+## Collision Shapes
			
 
				+
			
 
				+Sprites do not yet support Collision Shapes generated in Tile Sources. Instead, you add Collision Objects with Collision Shapes like you would for any game object. See the [Physics documentation](/manuals/physics) for details.
			
 
				+
			
 
				+## Blend Mode
			
 
				+
			
 
				+The *Blend Mode* property defines how the sprite should be blended with the graphics behind it. These are the available blend modes and how they are calculated:
			
 
				+
			
 
				+Alpha
			
 
				+: Normal blending: a~0~ * rgb~0~ + (1 - a~0~) * rgb~1~
			
 
				+
			
 
				+
			
 
				+Add
			
 
				+: Brighten the background with the color values of the corresponding sprite pixels: rgb~0~ + rgb~1~
			
 
				+
			
 
				+
			
 
				+Add Alpha
			
 
				+: Brighten the background with the corresponding visible sprite pixels: a~0~ * rgb~0~ + rgb~1~
			
 
				+
			
 
				+
			
 
				+Multiply
			
 
				+: Darken the background with values of the the corresponding sprite pixels: rgb~0~ * rgb~1~
			
 
				+
			
 
				+## Sprite Shading
			
 
				+
			
 
				+The default sprite shading files are located under "/builtins/material/sprite.*" in your project. The default shading performs a regular texture lookup, but also has a tint (a fragment shader constant) which is multiplied with the texture color.
			
 
				+
			
 
				+To obtain effects like flashing a sprite white when it is hit, you can implement custom shading. To set a custom shading for your sprites, follow these steps:
			
 
				+
			
 
				+- Copy the files under "/builtins/material/sprite.*" into one of your project directories (you can't modify the content of the "builtins"-directory). This is not mandatory but makes the process easier.
			
 
				+- Open the copied "sprite.material" file and remap the shader files (.vp and .fp) to your own copies.
			
 
				+- Edit the .vp and .fp copies as you please. If you introduce shader constants, they must also be declared in the material file.
			
 
				+- Open your sprite and specify your new material in the Properties.
			
 
				+- To set a shader constants while the game is running, use the functions [`sprite.set_constant()`](/ref/sprite#sprite.set_constant) and [`sprite.reset_contant()`](/ref/sprite#sprite.reset_constant).
			
 
				+
			
 
				+## Tile Maps
			
 
				+
			
 
				+A Tile Map is a component that allows you to assemble, or _paint_, tiles from a Tile Source onto a large grid area. Tile Maps are commonly used to build game level environments. You can also use the Collision Shapes from the Tile Source in your maps for collision detection and physics simulation.
			
 
				+
			
 
				+## Painting Tiles
			
 
				+
			
 
				+- Open the Tile Map you want to work in.
			
 
				+- Make sure that there are no flagged issues in the Property or Outline view.
			
 
				+- Select or create a Layer to paint on in the Outline view.
			
 
				+- Select a tile to use as brush (press *Space* to show the tile palette)
			
 
				+
			
 
				+![Painting tiles](images/2dgraphics/2dgraphics_tilemap.png)
			
 
				+
			
 
				+## Picking Tiles
			
 
				+
			
 
				+You can also pick tiles directly from the Tile Map to use as a brush. Hold *Shift* and click a tile to pick it up as the current brush. When holding *Shift* you can also click and drag to select a block of tiles to use as a larger brush.
			
 
				+
			
 
				+![Picking tiles](images/2dgraphics/2dgraphics_tiles_pick.png)
			
 
				+
			
 
				+## Erasing Tiles
			
 
				+
			
 
				+The Eraser tool is used to erase painted tiles. To select the Eraser, you can either:
			
 
				+
			
 
				+- Select it from the Tile Map menu
			
 
				+- Press *Backspace*
			
 
				+- Click the active tile again in the tiles palette
			
 
				+- Pick any empty cell on the Tile Map
			
 
				+
			
 
				+## Attaching Physics
			
 
				+
			
 
				+You can attach physics to the Tile Map to do collision detection or physics simulations involving tiles. To attach physics to a Tile Map, see the [Physics documentation](/manuals/physics) for details.
			
 
				+
			
 
				+## Changing tiles from script
			
 
				+
			
 
				+You can change the content of a Tile Map dynamically while your game is running. To do so, send [`set_tile`](/ref/tilemap#set_tile) messages to the Tile Map:
			
 
				+
			
 
				+```lua
			
 
				+-- Replace the two door-tiles with "open door" tiles.
			
 
				+-- The door is two tiles on top of each other.
			
 
				+local doorpos = vmath.vector3(174, 305, 0)
			
 
				+msg.post("/level#tilemap", "set_tile", { layer_id = hash("layer1"), position = doorpos, tile = 58 })
			
 
				+-- Upper part of door can be adressed with same position and "dy" set to 1.
			
 
				+msg.post("/level#tilemap", "set_tile", { layer_id = hash("layer1"), position = doorpos, tile = 46, dy = 1 })
			
 
				+```
			
 
				+
			
 
				+## Adding a Tile Map to your game
			
 
				+
			
 
				+To add a Tile map to your game:
			
 
				+
			
 
				+1. Create a game object to hold the Tile Map component. The game object can be in a file or created directly in a collection
			
 
				+2. Right-click the root of the game object and select [menuseq]#Add component from file#
			
 
				+3. Select the Tile Map file
			
 
				+
			
 
				+The game object now contains the Tile Map and you can place or spawn the game object wherever you want it.
			
 
				+
			
 
				+![Placed tile map](images/2dgraphics/2dgraphics_tilemap_go.png)
			
 
				+
			
 
				+## Texture Filtering and Sampling
			
 
				+
			
 
				+Defold supports two different ways to do texture sampling. The method governs the visual result in cases when a _texel_ (a pixel in a texture) is not perfectly aligned with a screen pixel--. This happens when you move a Sprite containing the texture seamlessly (say 0.2 pixels in any direction), if your camera is moving seamlessly or if your camera zooms in or out:
			
 
				+
			
 
				+Nearest
			
 
				+: The nearest texel will be picked to color the screen pixel. This sampling method should be chosen if you want a perfect one-to-one pixel mapping from your textures to what you see on screen. With nearest filtering everything will snap from pixel to pixel when moving which looks twitchy if the Sprite moves slowly.
			
 
				+
			
 
				+
			
 
				+Linear
			
 
				+: The texel will be averaged with its neighbors before coloring the screen pixel. This produces smooth appearances for slow, continuous motions as a Sprite will bleed into the pixels before fully coloring them--it is this possible to move a Sprite less than a whole pixel.
			
 
				+
			
 
				+
			
 
				+The setting for which filtering to use is stored in the [Project Settings](/manuals/project-settings) file. There are two settings:
			
 
				+
			
 
				+default_texture_min_filter
			
 
				+: Minifying filtering applies whenever the texel is smaller than the screen pixel.
			
 
				+
			
 
				+default_texture_mag_filter
			
 
				+: Magnifying filtering applies whenever the texel is larger than the screen pixel.
			
 
				+
			
 
				+Both settings accept the values `linear` or `nearest`. For example:
			
 
				+
			
 
				+```ini
			
 
				+[graphics]
			
 
				+default_texture_min_filter = nearest
			
 
				+default_texture_mag_filter = nearest
			
 
				+```
			
 
				+
			
 
				+If you don’t specify anything, both are set to `linear` by default.
			
 
				+
			
 
				+(Some of the graphic assets used are made by Kenney: http://kenney.nl/assets)
			
--- a/docs/manuals/en/3dgraphics.md
+++ b/docs/manuals/en/3dgraphics.md
@@ -0,0 +1,51 @@
 
				+3D graphics
			
 
				+===========
			
 
				+
			
 
				+Defold is at its core a 3D engine. Even when you work with 2D material only all rendering is done in 3D, but ortographically projected onto the screen. This manual outlines the 3D support in Defold.
			
 
				+
			
 
				+Defold allows you to utilize full 3D content by including 3D assets, or _Models_ into your collections. You can build games in strictly 3D with only 3D assets, or you can mix 3D and 2D content as you wish.
			
 
				+
			
 
				+## Defold resources
			
 
				+
			
 
				+*Model*
			
 
				+: The model component contains the object mesh, its skeleton and animations. Like all visual components it also has a material tied to it.
			
 
				+
			
 
				+*Animation Set*
			
 
				+: The animation set file contains a list of *.dae* files from where to read animations. You can also add other *.animationset* files to an animation set, which is handy if you share partial sets of animations between several models.
			
 
				+
			
 
				+
			
 
				+The [Model documentation](/manuals/model) explains how to import 3D assets and create models.
			
 
				+
			
 
				+The [Animation documentation](/manuals/animation) explains how to animate 3D models.
			
 
				+
			
 
				+## Collada support
			
 
				+
			
 
				+Defold's 3D support requires you to save or export model, skeleton and animation data in the _Collada_ format. This is a widely adopted format that most 3D modelling software supports. So you should be able to create assets in in _Maya_, _3D Max_, _Blender_, _Sketchup_ or any other popular software and then bring the results into Defold.
			
 
				+
			
 
				+::: important
			
 
				+Defold currently supports only baked animations. Animations need to have matrices for each animated bone each keyframe, and not position, rotation and scale as separate keys.
			
 
				+
			
 
				+Animations are also linearly interpolated. If you do more advanced curve interpolation the animations needs to be prebaked from the exporter.
			
 
				+
			
 
				+Animation clips in Collada are not supported. To use multiple animations per model, export them into separate *.dae* files and gather the files into an *.animationset* file in Defold.
			
 
				+:::
			
 
				+
			
 
				+## Materials, shaders and textures
			
 
				+
			
 
				+3D software commonly allows you to set properties to your object vertices, like coloring and texturing. This information goes into the Collada *.dae* file that you export from your 3D software. Depending on the requirements of your game you will have to select and/or create appropriate and _performant_ materials for your objects. A material combines _shader programs_ with a set of parameters for rendering of the object.
			
 
				+
			
 
				+You will also need to design and implement a game camera that works with your intended gameplay.
			
 
				+
			
 
				+Your Defold project has some built-in materials that are used to render sprites, tiles, particles and GUI nodes. For 3D models, there is no suitable built-in material so we have to create one. For the example book model there is a "textured.material" resource ready-made.
			
 
				+
			
 
				+Read the [Material documentation](/manuals/material) for information how materials work and how you can create materials that work with textured 3D models.
			
 
				+
			
 
				+The [Shader manual](/manuals/shader) contains information on how shader programs work.
			
 
				+
			
 
				+## Rendering
			
 
				+
			
 
				+The last thing to do to get the model into the game is to alter the *Render Script* for the project. The default render script is tailor made for 2D games and does not work with 3D models. But by copying the default render script and adding a handful of lines of Lua code we can make sure that our book is rendered as expected. For the example the render script is already set up.
			
 
				+
			
 
				+Read the [Rendering documentation](/manuals/rendering) for details on how render scripts work.
			
 
				+
			
 
				+
			
--- a/docs/manuals/en/android.md
+++ b/docs/manuals/en/android.md
@@ -0,0 +1,153 @@
 
				+= Android development
			
 
				+
			
 
				+This document describes how to build and run Defold applications on Android devices.
			
 
				+
			
 
				+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 as easily put the development engine on a device for iterative development on the device over wifi.
			
 
				+
			
 
				+## Android and Google Play signing process
			
 
				+
			
 
				+Android requires that apps that you want to install are digitally signed. Unlike iOS where all certificates are issued by Apple, Android allows self signed apps so you can freely create certificates and keys required to sign apps.
			
 
				+
			
 
				+The process of creating certificates and keys may seem complicated but as long as you are in development, Defold fully automates the process. When you create an Android application bundle from the editor you can provide a specific certificate and key. If you don't, Defold generates a random certificate and a key and signs the resulting *.apk* (Android Application Package) file.
			
 
				+
			
 
				+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.
			
 
				+
			
 
				+## Android Debug Bridge
			
 
				+
			
 
				+The `adb` command line tool is an easy to use and versatile program that is used to interact with Android devices. You can download and install `adb` as part of the Android SDK package, for Mac, Linux or Windows.
			
 
				+
			
 
				+Download the Android SDK from: http://developer.android.com/sdk/index.html. You find the `adb` tool in <sdk>/platform-tools/. Alternatively, platform specific packages can be installed through respective package managers.
			
 
				+
			
 
				+On Ubuntu Linux:
			
 
				+
			
 
				+----
			
 
				+$ sudo apt-get install android-tools-adb
			
 
				+----
			
 
				+
			
 
				+On Fedora 18/19:
			
 
				+
			
 
				+----
			
 
				+$ sudo yum install android-tools
			
 
				+----
			
 
				+
			
 
				+On Mac OS X (Homebrew)
			
 
				+
			
 
				+----
			
 
				+$ brew 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:
			
 
				+
			
 
				+----
			
 
				+$ adb devices
			
 
				+List of devices attached
			
 
				+31002535c90ef000    device
			
 
				+----
			
 
				+
			
 
				+If your device does not show up, verify that you have enabled *USB debugging* on the Android device. Open the device *Settings* and check *Developer options* (or *Development*).
			
 
				+
			
 
				+![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*:
			
 
				+
			
 
				+----
			
 
				+$ 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 *Project > Targets* in the editor.
			
 
				+4. Select *Project > Build And Launch* 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 *Project > Bundle... > Android Application...* 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]"):
			
 
				+
			
 
				+----
			
 
				+$ adb logcat -s "defold"
			
 
				+--------- beginning of /dev/log/system
			
 
				+--------- beginning of /dev/log/main
			
 
				+I/defold  ( 6210): INFO:DLIB: SSDP started (ssdp://192.168.0.97:58089, http://0.0.0.0:38637)
			
 
				+I/defold  ( 6210): INFO:ENGINE: Defold Engine 1.2.50 (8d1b912)
			
 
				+I/defold  ( 6210): INFO:ENGINE: Loading data from:
			
 
				+I/defold  ( 6210): INFO:ENGINE: Initialised sound device 'default'
			
 
				+I/defold  ( 6210):
			
 
				+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:
			
 
				+
			
 
				+----
			
 
				+$ openssl genrsa -out key.pem 1024
			
 
				+$ 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:
			
 
				+
			
 
				+----
			
 
				+$ 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
			
 
				+Success
			
 
				+----
			
 
				+
			
--- a/docs/manuals/en/animation.md
+++ b/docs/manuals/en/animation.md
@@ -0,0 +1,416 @@
 
				+Animation
			
 
				+=========
			
 
				+
			
 
				+Defold has built in support for many types of animation that you can use as a source of graphics for object components:
			
 
				+
			
 
				+Flip-book animation
			
 
				+: A flip book animation consists of a series of still images that are shown in succession. The technique is very similar to traditional cell animation (see http://en.wikipedia.org/wiki/Traditional_animation). The technique offers limitless opportunities since each frame can be manipulated individually. However, since each frame is stored in a unique image, the memory footprint can be high. The smoothness of animation is also dependent on the number of images shown each second but increasing the number of images usually also increase the amount of work. Defold flip book animations are either stored as individual images added to an Atlas, or as a Tile Source with all frames laid out in a horizontal sequence.
			
 
				+
			
 
				+
			
 
				+![Animation sheet](images/animation/animsheet.png)
			
 
				+![Run loop](images/animation/runloop.gif)
			
 
				+
			
 
				+Spine animation
			
 
				+: Spine animation provides 2D _skeletal animation_ support (see http://en.wikipedia.org/wiki/Skeletal_animation). This is a fundamentally different technique that is closer to cutout animation. In cutout animation separate pieces of the animated object (e.g body parts, eyes, mouth etc) are moved individually between each frame. Spine animation let you build an invisible, virtual skeleton consisting of a hierarchy of interconnected _bones_. This skeleton, or _rig_, is then animated and individual images are attached to the bones. Defold supports animations created or exported in the [Spine JSON format](http://esotericsoftware.com/spine-json-format). Skeletal animation is very smooth since the engine can interpolate the location of each bone for each frame.
			
 
				+
			
 
				+
			
 
				+For details on how to import Spine data into a Spine model for animation, see the [Spine documentation](/manuals/spine).
			
 
				+
			
 
				+![Spine animation](images/animation/spine_animation.png)
			
 
				+![Run loop](images/animation/frog_runloop.gif)
			
 
				+
			
 
				+3D skinned animation
			
 
				+: Skeletal animation of 3D models is similar to Spine animation but works in 3D as opposed to 2D. The 3D model is not cut into separate parts and tied to a bone like in cutout animation. Instead, the bones apply deformation to vertices in the model and you have great control over how much a bone should affect the vertices.
			
 
				+
			
 
				+
			
 
				+For details on how to import 3D data into a Model for animation, see the [3D graphics documentation](/manuals/3dgraphics).
			
 
				+
			
 
				+![Blender animation](images/animation/blender_animation.png)
			
 
				+![Wiggle loop](images/animation/wiggle.gif)
			
 
				+
			
 
				+Property animation
			
 
				+: All numeric properties (numbers, vector3, vector4 and quaterions) can be animated in the built in animation system, using the function `go.animate()`. The engine will automatically "tween" properties for you according to given playback modes and easing functions. You can also specify custom easing functions.
			
 
				+
			
 
				+
			
 
				+![Property animation](images/animation/property_animation.png)
			
 
				+![Bounce loop](images/animation/bounce.gif)
			
 
				+
			
 
				+## Playing flip-book animations
			
 
				+
			
 
				+Sprites and GUI box nodes can play flip-book animations and you have great control over them at runtime.
			
 
				+
			
 
				+*Sprites*
			
 
				+: To run an animation during runtime you post `[play_animation](/ref/sprite#play_animation)` messages to the Sprite component you want to animate the texture on. 
			
 
				+
			
 
				+As soon as an animation is finished playing, the engine sends back a `[animation_done](/ref/sprite#animation_done)` message to the script that sent the `play_animation` message.
			
 
				+
			
 
				+*GUI box nodes*
			
 
				+: To run an animation during runtime you use the `[gui.play_flipbook()](/ref/gui#play_flipbook) function. See below for an example.
			
 
				+
			
 
				+
			
 
				+## Sprite example
			
 
				+
			
 
				+Suppose that your game has a "dodge" feature that allows the player to press a specific button to dodge. You have created four animations to support the feature with visual feedback:
			
 
				+
			
 
				+"idle"
			
 
				+: A looping animation of the player character idling.
			
 
				+
			
 
				+"dodge_idle"
			
 
				+: A looping animation of the player character idling while being in the dodging stance.
			
 
				+
			
 
				+"start_dodge"
			
 
				+: A play-once transition animation taking the player character from standing to dodging.
			
 
				+
			
 
				+"stop_dodge"
			
 
				+: A play-once transition animation taking the player character from dodging back to standing.
			
 
				+
			
 
				+
			
 
				+The following script provides the logic:
			
 
				+
			
 
				+```lua
			
 
				+function on_input(self, action_id, action)
			
 
				+    -- "dodge" is our input action
			
 
				+    if action_id == hash("dodge") then
			
 
				+        if action.pressed then
			
 
				+            msg.post("#sprite", "play_animation", {id = hash("start_dodge")})
			
 
				+            -- remember that we are dodging
			
 
				+            self.dodge = true
			
 
				+        elseif action.released then
			
 
				+            msg.post("#sprite", "play_animation", {id = hash("stop_dodge")})
			
 
				+            -- we are not dodging anymore
			
 
				+            self.dodge = false
			
 
				+        end
			
 
				+    end
			
 
				+end
			
 
				+
			
 
				+function on_message(self, message_id, message, sender)
			
 
				+    if message_id == hash("animation_done") then
			
 
				+        -- one of the transition animations are finished, let's start looping
			
 
				+        if self.dodge then
			
 
				+            msg.post("#sprite", "play_animation", {id = hash("dodge_idle")})
			
 
				+        else
			
 
				+            msg.post("#sprite", "play_animation", {id = hash("idle")})
			
 
				+        end
			
 
				+    end
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+## GUI box node example
			
 
				+
			
 
				+When selecting an animation or image for a node, you are in fact assigning the image source (atlas or tile source) and default animation in one go. The image source is statically set in the node, but the current animation to play can be changed in runtime. Still images are treated as one frame animations so changing an image means in run time is equivalent to playing a different flip book animation for the node:
			
 
				+
			
 
				+```lua
			
 
				+local function flipbook_done(self)
			
 
				+    msg.post("#", "jump_completed")
			
 
				+end
			
 
				+
			
 
				+function init(self)
			
 
				+    local character_node = gui.get_node("character")
			
 
				+    -- This requires that the node has a default animation in the same atlas or tile source as
			
 
				+    -- the new animation/image we're playing.
			
 
				+    gui.play_flipbook(character_node, "jump_left", flipbook_done)
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+An optional function that is called on completion can be provided. It will be called on animations that are played back in any of the ONCE_* modes.
			
 
				+
			
 
				+## Animating Spine models
			
 
				+
			
 
				+To run animations on your model, simply call the `[spine.play_anim()](/ref/spine#spine.play_anim)+ function:
			
 
				+
			
 
				+```lua
			
 
				+local function anim_done(self)
			
 
				+    -- the animation is done, do something useful...
			
 
				+end
			
 
				+
			
 
				+function init(self)
			
 
				+    -- Play the "walk" animation on component "spinemodel" and blend against previous
			
 
				+    -- animation for the first 0.1 seconds, then call callback.
			
 
				+    local anim_props = { blend_duration = 0.1 }
			
 
				+    spine.play_anim("#spinemodel", "walk", go.PLAYBACK_LOOP_FORWARD, anim_props, anim_done)
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+![Spine model in game](images/animation/spine_model_ingame.png)
			
 
				+
			
 
				+If an animation is played with any of the *go.PLAYBACK_ONCE_* modes and you have provided a callback function to `spine.play_anim()` the callback is run on animation complete. See below for information on callbacks.
			
 
				+
			
 
				+## Cursor animation
			
 
				+
			
 
				+In addition to using the `spine.play_anim()` to advance a spine animation, *Spine Model* components expose a "cursor" property that can be manipulated with `go.animate()`:
			
 
				+
			
 
				+```lua
			
 
				+-- Set the animation on the spine model but don't run it.
			
 
				+spine.play_anim("#spinemodel", "run_right", go.PLAYBACK_NONE)
			
 
				+
			
 
				+-- Set the cursor to position 0
			
 
				+go.set("#spinemodel", "cursor", 0)
			
 
				+
			
 
				+-- Tween the cursor slowly between 0 and 1 pingpong with in-out quad easing.
			
 
				+go.animate("#spinemodel", "cursor", go.PLAYBACK_LOOP_PINGPONG, 1, go.EASING_INOUTQUAD, 6)
			
 
				+```
			
 
				+
			
 
				+::: important
			
 
				+When tweening or setting the cursor, timeline events may not fire as expected.
			
 
				+:::
			
 
				+
			
 
				+## The bone hierarchy
			
 
				+
			
 
				+The individual bones in the Spine skeleton are represented internally as game objects. In the *Outline* view of the Spine model component, the full hierarchy is visible. You can see each bone's name and its place in the skeleton hierarchy.
			
 
				+
			
 
				+![Spine model hierarchy](images/animation/spine_model_hierarchy.png)
			
 
				+
			
 
				+With the bone name at hand, you are able to retrieve the instance id of the bone in runtime. The function `[spine.get_go()](/ref/spine#spine.get_go)` returns the id of the specified bone and you can, for instance, child other game objects under the animated game object:
			
 
				+
			
 
				+```lua
			
 
				+-- Attach pistol game object to the hand of the heroine
			
 
				+local hand = spine.get_go("heroine#spinemodel", "front_hand")
			
 
				+msg.post("pistol", "set_parent", { parent_id = hand })
			
 
				+```
			
 
				+
			
 
				+## Timeline events
			
 
				+
			
 
				+Spine animations can trigger timed events by sending messages at precise moments. They are very useful for events that should take place in sync with your animation, like playing footstep sounds, spawning particle effects, attach or detach objects to the bone hierarchy or anything else you would like happen.
			
 
				+
			
 
				+Events are added in the Spine software and are visualized on the playback timeline:
			
 
				+
			
 
				+![Spine events](images/animation/spine_events.png)
			
 
				+
			
 
				+Each event is referenced with a name identifier ("bump" in the example above) and each event instance on the timeline can contain additional information:
			
 
				+
			
 
				+Integer
			
 
				+: A numerical value expressed as an integer.
			
 
				+
			
 
				+Float
			
 
				+: A floating point numerical value.
			
 
				+
			
 
				+String
			
 
				+: A string value.
			
 
				+
			
 
				+
			
 
				+When the animation plays and events are encountered, `spine_event` messages are sent back to the script component that called `spine.play()`. The message data contains the custom numbers and strings embedded in the event, as well as a few additional fields that are sometimes useful:
			
 
				+
			
 
				+t
			
 
				+: The number of seconds passed since the first frame of the animation.
			
 
				+
			
 
				+animation_id
			
 
				+: The animation name, hashed.
			
 
				+
			
 
				+string
			
 
				+: The provided string value, hashed.
			
 
				+
			
 
				+float
			
 
				+: The provided floating point numerical value.
			
 
				+
			
 
				+integer
			
 
				+: The provided integer numerical value.
			
 
				+
			
 
				+event_id
			
 
				+: The event identifier, hashed.
			
 
				+
			
 
				+blend_weight
			
 
				+: How much of the animation is blended in at this point. 0 means that nothing of the current animation is part of the blend yet, 1 means that the blend consists of the current animation to 100%.
			
 
				+
			
 
				+
			
 
				+```lua
			
 
				+-- Spine animation contains events that are used to play sounds in sync with the animation.
			
 
				+-- These arrive here as messages.
			
 
				+function on_message(self, message_id, message, sender)
			
 
				+  if message_id == hash("spine_event") and message.event_id == hash("play_sound") then
			
 
				+    -- Play animation sound. The custom event data contains the sound component and the gain.
			
 
				+    local url = msg.url("sounds")
			
 
				+    url.fragment = message.string
			
 
				+    msg.post(url, "play_sound", { gain = message.float })
			
 
				+  end
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+## 3D Model animation
			
 
				+
			
 
				+Models are animated with the `[model.play_anim()](/ref/model#model.play_anim)` function:
			
 
				+
			
 
				+```lua
			
 
				+function init(self)
			
 
				+    -- Start the "wiggle" animation back and forth on #model
			
 
				+    model.play_anim("#model", "wiggle", go.PLAYBACK_LOOP_PINGPONG)
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+::: important
			
 
				+Defold currently supports only baked animations. Animations need to have matrices for each animated bone each keyframe, and not position, rotation and scale as separate keys.
			
 
				+
			
 
				+Animations are also linearly interpolated. If you do more advanced curve interpolation the animations needs to be prebaked from the exporter.
			
 
				+
			
 
				+Animation clips in Collada are not supported. To use multiple animations per model, export them into separate *.dae* files and gather the files into an *.animationset* file in Defold.
			
 
				+:::
			
 
				+
			
 
				+## The bone hierarchy
			
 
				+
			
 
				+The bones in the Model skeleton are represented internally as game objects. In the *Outline* view of the Model component, you can see the bone hierarchy and each bone's name.
			
 
				+
			
 
				+![Model hierarchy](images/animation/model_hierarchy.png)
			
 
				+
			
 
				+You can retrieve the instance id of the bone game object in runtime. The function `[model.get_go()](/ref/model#model.get_go)` returns the id of the specified bone.
			
 
				+
			
 
				+```lua
			
 
				+-- Get the middle bone go of our wiggler model
			
 
				+local bone_go = model.get_go("#wiggler", "Bone_002")
			
 
				+
			
 
				+-- Now do something useful with the game object...
			
 
				+```
			
 
				+
			
 
				+## Cursor animation
			
 
				+
			
 
				+Just as Spine models, 3D models can be animated by manipulating the "cursor" property:
			
 
				+
			
 
				+```lua
			
 
				+-- Set the animation on #model but don't start it
			
 
				+model.play_anim("#model", "wiggle", go.PLAYBACK_NONE)
			
 
				+-- Set the cursor to the beginning of the animation
			
 
				+go.set("#model", "cursor", 0)
			
 
				+-- Tween the cursor between 0 and 1 pingpong with in-out quad easing.
			
 
				+go.animate("#model", "cursor", go.PLAYBACK_LOOP_PINGPONG, 1, go.EASING_INOUTQUAD, 3)
			
 
				+```
			
 
				+
			
 
				+## Property animation
			
 
				+
			
 
				+To animate a game object or component property, use the function `go.animate()`. For GUI node properties, the corresponding function is `gui.animate()`.
			
 
				+
			
 
				+```lua
			
 
				+-- Set the position property y component to 200
			
 
				+go.set(".", "position.y", 200)
			
 
				+-- Then animate it
			
 
				+go.animate(".", "position.y", go.PLAYBACK_LOOP_PINGPONG, 100, go.EASING_OUTBOUNCE, 2)
			
 
				+```
			
 
				+
			
 
				+To stop all animations of a given property, call `go.cancel_animations()`, or for GUI nodes, `gui.cancel_animation()`.:
			
 
				+
			
 
				+```lua
			
 
				+-- Stop euler z rotation animation on the current game object
			
 
				+go.cancel_animation(".", "euler.z")
			
 
				+```
			
 
				+
			
 
				+If you cancel the animation of a composite property, like "position", any animations of the sub-components ("position.x", "position.y" and "position.z") will be cancelled as well.
			
 
				+
			
 
				+The [Properties Manual](/manuals/properties) contains all the available properties on game objects, components and GUI nodes.
			
 
				+
			
 
				+## GUI node property animation
			
 
				+
			
 
				+Almost all GUI node properties are possible to animate. You can, for instance, make a node invisible by setting its "color" property to full transparency and then fade it into view by animating the color to white (i.e. no tint color).
			
 
				+
			
 
				+```lua
			
 
				+local node = gui.get_node("button")
			
 
				+local color = gui.get_color(node)
			
 
				+-- Animate the color to white
			
 
				+gui.animate(node, gui.PROP_COLOR, vmath.vector4(1, 1, 1, 1), gui.EASING_INOUTQUAD, 0.5)
			
 
				+-- Animate the outline red color component
			
 
				+gui.animate(node, "outline.x", 1, gui.EASING_INOUTQUAD, 0.5)
			
 
				+-- And move to x position 100
			
 
				+gui.animate(node, hash("position.x"), 100, gui.EASING_INOUTQUAD, 0.5)
			
 
				+```
			
 
				+
			
 
				+## Playback Modes
			
 
				+
			
 
				+Animations can be played either once or looping. How the animation plays is determined by the playback mode:
			
 
				+
			
 
				+* go.PLAYBACK_NONE
			
 
				+* go.PLAYBACK_ONCE_FORWARD
			
 
				+* go.PLAYBACK_ONCE_BACKWARD
			
 
				+* go.PLAYBACK_ONCE_PINGPONG
			
 
				+* go.PLAYBACK_LOOP_FORWARD
			
 
				+* go.PLAYBACK_LOOP_BACKWARD
			
 
				+* go.PLAYBACK_LOOP_PINGPONG
			
 
				+
			
 
				+The pingpong modes run the animation first forwards, then backward. A set of corresponding modes exist for GUI property animations:
			
 
				+
			
 
				+* gui.PLAYBACK_NONE
			
 
				+* gui.PLAYBACK_ONCE_FORWARD
			
 
				+* gui.PLAYBACK_ONCE_BACKWARD
			
 
				+* gui.PLAYBACK_ONCE_PINGPONG
			
 
				+* gui.PLAYBACK_LOOP_FORWARD
			
 
				+* gui.PLAYBACK_LOOP_BACKWARD
			
 
				+* gui.PLAYBACK_LOOP_PINGPONG
			
 
				+
			
 
				+## Easing
			
 
				+
			
 
				+Easing defines how the animated value changes over time. The images below describe the functions applied over time to create the easing.
			
 
				+
			
 
				+The corresponding value to use when calling `go.animate()` are `go.EASING_LINEAR`, `go.EASING_INBACK`, `go.EASING_OUTBACK` and so forth.
			
 
				+
			
 
				+For `gui.animate()` the values are named `gui.EASING_LINEAR`, `gui.EASING_INBACK`, `gui.EASING_OUTBACK` and so forth.
			
 
				+
			
 
				+![Linear interpolation](images/properties/easing_linear.png)
			
 
				+![In back](images/properties/easing_inback.png)
			
 
				+![Out back](images/properties/easing_outback.png)
			
 
				+![In-out back](images/properties/easing_inoutback.png)
			
 
				+![Out-in back](images/properties/easing_outinback.png)
			
 
				+![In bounce](images/properties/easing_inbounce.png)
			
 
				+![Out bounce](images/properties/easing_outbounce.png)
			
 
				+![In-out bounce](images/properties/easing_inoutbounce.png)
			
 
				+![Out-in bounce](images/properties/easing_outinbounce.png)
			
 
				+![In elastic](images/properties/easing_inelastic.png)
			
 
				+![Out elastic](images/properties/easing_outelastic.png)
			
 
				+![In-out elastic](images/properties/easing_inoutelastic.png)
			
 
				+![Out-in elastic](images/properties/easing_outinelastic.png)
			
 
				+![In sine](images/properties/easing_insine.png)
			
 
				+![Out sine](images/properties/easing_outsine.png)
			
 
				+![In-out sine](images/properties/easing_inoutsine.png)
			
 
				+![Out-in sine](images/properties/easing_outinsine.png)
			
 
				+![In exponential](images/properties/easing_inexpo.png)
			
 
				+![Out exponential](images/properties/easing_outexpo.png)
			
 
				+![In-out exponential](images/properties/easing_inoutexpo.png)
			
 
				+![Out-in exponential](images/properties/easing_outinexpo.png)
			
 
				+![In circlic](images/properties/easing_incirc.png)
			
 
				+![Out circlic](images/properties/easing_outcirc.png)
			
 
				+![In-out circlic](images/properties/easing_inoutcirc.png)
			
 
				+![Out-in circlic](images/properties/easing_outincirc.png)
			
 
				+![In quadratic](images/properties/easing_inquad.png)
			
 
				+![Out quadratic](images/properties/easing_outquad.png)
			
 
				+![In-out quadratic](images/properties/easing_inoutquad.png)
			
 
				+![Out-in quadratic](images/properties/easing_outinquad.png)
			
 
				+![In cubic](images/properties/easing_incubic.png)
			
 
				+![Out cubic](images/properties/easing_outcubic.png)
			
 
				+![In-out cubic](images/properties/easing_inoutcubic.png)
			
 
				+![Out-in cubic](images/properties/easing_outincubic.png)
			
 
				+![In quartic](images/properties/easing_inquart.png)
			
 
				+![Out quartic](images/properties/easing_outquart.png)
			
 
				+![In-out quartic](images/properties/easing_inoutquart.png)
			
 
				+![Out-in quartic](images/properties/easing_outinquart.png)
			
 
				+![In quintic](images/properties/easing_inquint.png)
			
 
				+![Out quintic](images/properties/easing_outquint.png)
			
 
				+![In-out quintic](images/properties/easing_inoutquint.png)
			
 
				+![Out-in quintic](images/properties/easing_outinquint.png)
			
 
				+
			
 
				+## Custom easing
			
 
				+
			
 
				+You can create custom easing curves by defining a [type]#vector# with a set of values and then provide the vector instead of one of the predefined easing constants above:
			
 
				+
			
 
				+```lua
			
 
				+local values = { 0, 0, 0, 0, 0, 0, 0, 0,
			
 
				+                 1, 1, 1, 1, 1, 1, 1, 1,
			
 
				+                 0, 0, 0, 0, 0, 0, 0, 0,
			
 
				+                 1, 1, 1, 1, 1, 1, 1, 1,
			
 
				+                 0, 0, 0, 0, 0, 0, 0, 0,
			
 
				+                 1, 1, 1, 1, 1, 1, 1, 1,
			
 
				+                 0, 0, 0, 0, 0, 0, 0, 0,
			
 
				+                 1, 1, 1, 1, 1, 1, 1, 1 }
			
 
				+local square_easing = vmath.vector(values)
			
 
				+go.animate("go", "position.y", go.PLAYBACK_LOOP_PINGPONG, 100, square_easing, 2.0)
			
 
				+```
			
 
				+
			
 
				+## Completion callbacks
			
 
				+
			
 
				+All animation functions (`go.animate()`, `gui.animate()`, `gui.play_flipbook()`, `gui.play_spine_anim()`, `spine.play_anim()` and `model.play_anim()`) supports an optional Lua callback function as the last argument. This function will be called when the animation has played to the end. The function is never called for looping animations, nor when an animation is manually canceled via `go.cancel_animations()`. The callback can be used to trigger events on animation completion or to chain multiple animations together.
			
 
				+
			
 
				+The exact function signature of the callback differs slightly betweeen the animation functions. See the API documentation for the function you are using.
			
 
				+
			
 
				+```lua
			
 
				+local function done_bouncing(self, url, property)
			
 
				+    -- We're done animating. Do something...
			
 
				+end
			
 
				+
			
 
				+function init(self)
			
 
				+    go.animate(".", "position.y", go.PLAYBACK_ONCE_FORWARD, 100, go.EASING_OUTBOUNCE, 2, 0, done_bouncing)
			
 
				+end
			
 
				+```
			
 
				+
			
--- a/docs/manuals/en/application-lifecycle.md
+++ b/docs/manuals/en/application-lifecycle.md
@@ -0,0 +1,120 @@
 
				+Application lifecycle
			
 
				+=====================
			
 
				+:location: documentation manuals concepts
			
 
				+:type: manual
			
 
				+
			
 
				+This document details the lifecycle of Defold games and applications.
			
 
				+
			
 
				+The lifecycle of a Defold application or game is on the large scale very simple. The engine moves through three stages of execution: initialization, the update loop (where apps and games spend most of their time) and finalization.
			
 
				+
			
 
				+![Lifecycle overview](images/application_lifecycle/application_lifecycle_overview.png)
			
 
				+
			
 
				+In many cases only a rudimentary understanding of Defold's inner workings is necessary. However, you might run into edge cases where the exact order Defold carries out its tasks becomes vital. This document describes how the engine runs an application from start to finish.
			
 
				+
			
 
				+The application starts by initializing everything that is needed to run the engine. It loads the main collection and calls `[init()](/ref/go#init)` on all loaded components that has an `init()` Lua function (script components and GUI components with GUI scripts). This allows you to do custom initialization.
			
 
				+
			
 
				+The application then enters the update loop where the application will spend a majority of its lifetime. Each frame, game objects and the components they contain are updated. Any script and GUI script `[update()](/ref/go#update)` functions are called. During the update loop messages are dispatched to its recipients, sounds are played and all graphics is rendered.
			
 
				+
			
 
				+At some point the applications lifecycle will come to an end. Before the application quits the engine steps out of the update loop and enters a finalization stage. It prepares all loaded game objects for deletion. All object components’ `[final()](/ref/go#final)` functions are called, which allows for custom cleanup. Then the objects are deleted and the main collection is unloaded.
			
 
				+
			
 
				+## Initialization
			
 
				+
			
 
				+![Lifecycle overview](images/application_lifecycle/application_lifecycle_init.png)
			
 
				+
			
 
				+This diagram contains a more detailed breakdown of the initialization steps. The steps involved in the "dispatch messages" pass (right before "spawn dynamic objects") has been put in a separate block to the right for clarity. application lifecycle init.png
			
 
				+
			
 
				+The actual steps the engine takes during initialization, before the main collection is loaded is, in fact, much longer. The memory profiler, sockets, graphics, HID (input devices), sound, physics and much more is set up. The application configuration is also loaded ("game.project") and set up.
			
 
				+
			
 
				+The first user-controllable entry point, at the end of engine initialization, is the call to the current render script’s `init()` function.
			
 
				+
			
 
				+The main collection is then loaded and initialized. All game objects in the collection apply their transforms to their children (translation/change of position, movement, rotation and scaling) onto their children. All component `init()` functions that exists are then called.
			
 
				+
			
 
				+::: sidenote
			
 
				+The order game object component `init()` functions are called is unspecified. You should not assume that the engines initialize objects belonging to the same collection in a certain order.
			
 
				+:::
			
 
				+
			
 
				+Since your `init()` code can post new messages, tell factories to spawn new objects, mark objects for deletion and do all sorts of things the engine performs a full "post-update" pass next. This pass carries out message delivery, the actual factory game object spawning and object deletion. Note that the post-update pass includes a  "dispatch messages" sequence that not only sends any queued messages but also handles messages sent to collection proxies. Any subsequent updates on the proxies (enable and disable, loading and mark for unloading) is performed during those steps.
			
 
				+
			
 
				+Studying the diagram above reveals that it is fully possible to load a [collection proxy](/manuals/collection-proxy) during `init()`, ensure all its contained objects are initialized, and then unload the collection through the proxy--all this before the first component `update()` is called, i.e. before the engine has left the initialization stage and entered the update loop:
			
 
				+
			
 
				+```lua
			
 
				+function init(self)
			
 
				+        print("init()")
			
 
				+        msg.post("#collectionproxy", "load")
			
 
				+end
			
 
				+
			
 
				+function update(self, dt)
			
 
				+    -- The proxy collection is unloaded before this code is reached.
			
 
				+    print("update()")
			
 
				+end
			
 
				+
			
 
				+function on_message(self, message_id, message, sender)
			
 
				+        if message_id == hash("proxy_loaded") then
			
 
				+                print("proxy_loaded. Init, enable and then unload.")
			
 
				+                msg.post("#collectionproxy", "init")
			
 
				+                msg.post("#collectionproxy", "enable")
			
 
				+                msg.post("#collectionproxy", "unload")
			
 
				+                -- The proxy collection objects’ init() and final()
			
 
				+                -- is called before we reach this object’s update()
			
 
				+          end
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+## The update loop
			
 
				+
			
 
				+The update loop runs through a long sequence once every frame. The update sequence in the diagram below are divided into logical sequence blocks for clarity. "Dispatch messages" is also broken out separately for the same reason:
			
 
				+
			
 
				+![Update loop](images/application_lifecycle/application_lifecycle_update.png)
			
 
				+
			
 
				+## Input
			
 
				+
			
 
				+Input is is read from available devices, mapped against [input bindings](/manuals/input) and then dispatched. Any game object that has acquired input focus gets input sent to all its component `on_input()` functions. A game object with a script component and a GUI component with a GUI script will get input to both components’ `on_input()` functions--given that they are defined and that they have acquired input focus.
			
 
				+
			
 
				+Any game object that has acquired input focus and that contain collection proxy components dispatches input further to components in the proxy collection belonging to game objects that has acquired input focus. This process continues recursively down enabled collection proxies within enabled collection proxies.
			
 
				+
			
 
				+## Update
			
 
				+
			
 
				+Each game object component in the main collection is traversed. If any of these component has a script `update(),` then it will be called. If the component is a collection proxy, each component in the proxy collection is recursively updated with all the steps in the "update" sequence in the diagram above.
			
 
				+
			
 
				+::: sidenote
			
 
				+The order game object component `update()` functions are called is unspecified. You should not assume that the engines updates objects belonging to the same collection in a certain order.
			
 
				+:::
			
 
				+
			
 
				+In the next step all posted messages are dispatched. Since any receiver component’s `on_message()` code can post additional messages the message dispatcher will continue to dispatch posted messaged until the message queue is empty. There is, however, a limit to how many runs through the message queue the message dispatcher performs. See [Message passing](/manuals/message-passing) and the section "Advanced topics" for details.
			
 
				+
			
 
				+For collision object components, physics messages (collisions, triggers, ray_cast responses etc) are dispatched throughout the encompassing game object to all components that contain a script with an `on_message()` function.
			
 
				+
			
 
				+Transforms are then done, applying any game object movement, rotation and scaling to each game object component and any child game object components.
			
 
				+
			
 
				+## Render update
			
 
				+
			
 
				+The render update block dispatches messages to the @render socket (camera component "set_view_projection" messages, "set_clear_color" messages etc). The render script `update()` is then called.
			
 
				+
			
 
				+## Post update
			
 
				+
			
 
				+After the updates, a post update sequence is run. It unloads from memory collection proxies that are marked for unloading (this happens during the "dispatch messages" sequence). Any game object that is marked for deletion will call all of its components’ `final()` functions called—if there are any. The code in `final()` functions often posts new messages to the queue so a "dispatch messages" pass is run afterwards.
			
 
				+
			
 
				+Any factory components that has been told to spawn a game object will do that next. Finally, game objects that are marked for deletion are actually deleted.
			
 
				+
			
 
				+The last steps in the update loop involves dispatching @system messages ("exit", "reboot" messages, toggling the profiler, starting and stopping video capture etc). Then graphics is rendered. During the graphics rendering, video capture is done, as is any rendering of the visual profiler (see the [Debugging documentation](/manuals/debugging).)
			
 
				+
			
 
				+## Frame rate and collection time step
			
 
				+
			
 
				+The number of frame updates per seconds (which equals the number of update-loop runs per second) can be set in the project settings, or programmatically by sending an "set_update_frequency" message to the `@system` socket. In addition, it is possible to set the _time step_ for collection proxies individually by sending a "set_time_step" message to the proxy. Changing a collection's time step does not affect the frame rate. It has an effect on the physics update time step as well as the "dt" variable passed to `update().` Also note that altering the time step does not alter the number of times `update()` will be called each frame--it is always exactly once.
			
 
				+
			
 
				+(See [Collection proxy](/manuals/collection-proxy) and [set_time_step](/ref/collection-proxy#set_time_step) for details)
			
 
				+
			
 
				+## Finalization
			
 
				+
			
 
				+At the point when the application exits, it finishes the last update loop sequence, which will unload any collection proxies: finalizing and deleting all game objects in the proxy collection.
			
 
				+
			
 
				+The engine lastly enters a finalization sequence that handles the main collection and its objects:
			
 
				+
			
 
				+![Finalization](images/application_lifecycle/application_lifecycle_final.png)
			
 
				+
			
 
				+Component `final()` functions are called first. A subsequent dispatching of messages follows. Finally, all game objects are deleted and the main collection is unloaded.
			
 
				+
			
 
				+The engine follows up with behind the scenes shutting down of subsystems, project configuration is deleted, memory profiler is shut down, and so forth.
			
 
				+
			
 
				+The application is now completely shut down.
			
 
				+
			
--- a/docs/manuals/en/bob.md
+++ b/docs/manuals/en/bob.md
@@ -0,0 +1,122 @@
 
				+Bob the builder
			
 
				+===============
			
 
				+:location: documentation manuals project
			
 
				+:type: manual
			
 
				+
			
 
				+Bob is a tool for building Defold projects outside of the normal editor workflow. This manual explains how to use the tool.
			
 
				+
			
 
				+## Overview
			
 
				+
			
 
				+Bob is able to build data (corresponding to the build step of selecting the editor menu item menu:Project[Build And Launch]), create data archives and standalone, distributable application bundles (corresponding to the editor menu item menu:Project[Bundle > *] options)
			
 
				+
			
 
				+Bob is distributed as a Java _JAR_ archive containing everything needed to build. You find the latest "bob.jar" distribution at http://d.defold.com. Select a release, then download "bob/bob.jar". To run the Bob tool, you need Java 8 installed on your computer. You can download a version of Java from https://www.java.com.
			
 
				+
			
 
				+## Usage
			
 
				+
			
 
				+Bob is run from a shell or from the command line by invoking "java" (or "java.exe" on Windows) and providing the bob java archive as argument:
			
 
				+
			
 
				+----
			
 
				+$ java -jar bob.jar --help
			
 
				+usage: bob [options] [commands]
			
 
				+ -,--identity <arg>                  Sign identity (iOS)
			
 
				+ -a,--archive                        Build archive
			
 
				+ -bo,--bundle-output <arg>           Bundle output directory
			
 
				+ -br,--build-report <arg>            Filepath where to save a build report
			
 
				+                                     as JSON
			
 
				+ -brhtml,--build-report-html <arg>   Filepath where to save a build report
			
 
				+                                     as HTML
			
 
				+ -ce,--certificate <arg>             Certificate (Android)
			
 
				+ -d,--debug                          Use debug version of dmengine (when
			
 
				+                                     bundling)
			
 
				+ -e,--email <arg>                    User email
			
 
				+ -h,--help                           This help message
			
 
				+ -i,--input <arg>                    Source directory. Default is current
			
 
				+                                     directory
			
 
				+ -k,--keep-unused                    Keep unused resources in archived
			
 
				+                                     output
			
 
				+ -mp,--mobileprovisioning <arg>      mobileprovisioning profile (iOS)
			
 
				+ -o,--output <arg>                   Output directory. Default is
			
 
				+                                     "build/default"
			
 
				+ -p,--platform <arg>                 Platform (when bundling)
			
 
				+ -pk,--private-key <arg>             Private key (Android)
			
 
				+ -r,--root <arg>                     Build root directory. Default is
			
 
				+                                     current directory
			
 
				+ -tp,--texture-profiles <arg>        Use texture profiles
			
 
				+ -u,--auth <arg>                     User auth token
			
 
				+ -v,--verbose                        Verbose output
			
 
				+----
			
 
				+
			
 
				+Available commands:
			
 
				+
			
 
				+clean
			
 
				+: Delete built files in the build directory.
			
 
				+
			
 
				+distclean
			
 
				+: Delete all files in the build directory.
			
 
				+
			
 
				+build
			
 
				+: Builds all project data. Add the "--archive" option to build a data archive file ("game.darc" in the build directory).
			
 
				+
			
 
				+bundle
			
 
				+: Creates a platform specific application bundle. Bundling requires that a built archive is present ("build" with the "--archive" option) and that a target platform is specified (with the "--platform" option). Bob creates the bundle in the output directory unless a different directory is specified with the "--bundle-output" option. The bundle is named according to the project name setting in "game.project".
			
 
				+
			
 
				+resolve
			
 
				+: Resolve all external library dependencies.
			
 
				+
			
 
				+
			
 
				+Available platforms:
			
 
				+
			
 
				+x86-darwin
			
 
				+: Mac OSX
			
 
				+
			
 
				+x86_64-darwin
			
 
				+: Mac OSX 64 bit
			
 
				+
			
 
				+x86-win32
			
 
				+: Windows
			
 
				+
			
 
				+x86-linux
			
 
				+: Linux
			
 
				+
			
 
				+armv7-darwin
			
 
				+: iOS
			
 
				+
			
 
				+armv7-android
			
 
				+: Android
			
 
				+
			
 
				+js-web
			
 
				+: HTML5
			
 
				+
			
 
				+
			
 
				+By default, Bob looks in the current directory for a project to build. If you change the current dir to a Defold project and invoke bob, it builds the data for the project in the default output directory "build/default".
			
 
				+
			
 
				+----
			
 
				+$ cd /Applications/Defold-beta/branches/14/4/main
			
 
				+$ java -jar bob.jar
			
 
				+100%
			
 
				+$ 
			
 
				+----
			
 
				+
			
 
				+You can string commands together to perform a sequence of tasks in one go. The following example resolves libraries, wipes the build directory, builds archive data and bundles an OSX application (named "My Game.app"):
			
 
				+
			
 
				+----
			
 
				+$ java -jar bob.jar --archive --platform x86-darwin resolve distclean build bundle
			
 
				+100%
			
 
				+$ ls -al build/default/
			
 
				+total 70784
			
 
				+drwxr-xr-x   13 sicher  staff       442  1 Dec 10:15 .
			
 
				+drwxr-xr-x    3 sicher  staff       102  1 Dec 10:15 ..
			
 
				+drwxr-xr-x    3 sicher  staff       102  1 Dec 10:15 My Game.app
			
 
				+drwxr-xr-x    8 sicher  staff       272  1 Dec 10:15 builtins
			
 
				+-rw-r--r--    1 sicher  staff    140459  1 Dec 10:15 digest_cache
			
 
				+drwxr-xr-x    4 sicher  staff       136  1 Dec 10:15 fonts
			
 
				+-rw-r--r--    1 sicher  staff  35956340  1 Dec 10:15 game.darc
			
 
				+-rw-r--r--    1 sicher  staff       735  1 Dec 10:15 game.projectc
			
 
				+drwxr-xr-x  223 sicher  staff      7582  1 Dec 10:15 graphics
			
 
				+drwxr-xr-x    3 sicher  staff       102  1 Dec 10:15 input
			
 
				+drwxr-xr-x   20 sicher  staff       680  1 Dec 10:15 logic
			
 
				+drwxr-xr-x   27 sicher  staff       918  1 Dec 10:15 sound
			
 
				+-rw-r--r--    1 sicher  staff    131926  1 Dec 10:15 state
			
 
				+$
			
 
				+----
			
 
				+
			
--- a/docs/manuals/en/building-blocks.md
+++ b/docs/manuals/en/building-blocks.md
@@ -0,0 +1,193 @@
 
				+= Building blocks
			
 
				+:location: documentation manuals concepts
			
 
				+:order: 2
			
 
				+:type: manual
			
 
				+
			
 
				+This document digs into the details of how _Game objects_, _Components_ and _Collections_ work.
			
 
				+
			
 
				+Some of the design decisions made in Defold differ from other software and it may take some time to get a good grip on how and why things are put together the way they are. In order to properly understand how Defold manages and gives you access to game resources, read this document and the [Message passing documentation](/manuals/message-passing). Some or many of the things here might be unfamiliar and hard to understand at first, but don't worry. Take your time, experiment with the editor and engine and return to the documentation when you run into problems.
			
 
				+
			
 
				+![Building blocks](images/building_blocks/building_blocks.png)
			
 
				+
			
 
				+## Game objects
			
 
				+
			
 
				+Game objects are simple objects that each have a separate lifespan during the execution of your game. Game objects are usually equipped with visual or audible representation (a sound or sprite component, for instance). They can also be equipped with behavior through script components. Game objects are thus a separate thing from sprites, models or sounds in that they are _containers_ for these different type of components. You create game objects and place them in collections in the editor, or spawn them dynamically at run-time with _factories_.
			
 
				+
			
 
				+There are two different ways you can create game objects in the editor:
			
 
				+
			
 
				+1. Create a game object file and then create an instance of that file in a collection.
			
 
				+2. Create an _in-place_ instance of a game object in a collection.
			
 
				+
			
 
				+Let's look at the difference between these.
			
 
				+
			
 
				+## Prototypes and instances
			
 
				+
			
 
				+When you create a game object _file_, you create a blueprint, or a prototype, for a game object. This prototype can then be _instanced_ into one or many game objects.
			
 
				+
			
 
				+![Game object file](images/building_blocks/building_blocks_gameobject_file.png)
			
 
				+
			
 
				+Creating a game object file does not add anything to your running game. The game object does not exist yet, only the formula to create it. To add an actual game object based on the blueprint just created, you add an instance of the game object to a collection in your project by right clicking the collection and selecting *Add Game Object File*.
			
 
				+
			
 
				+![Game object instance](images/building_blocks/building_blocks_gameobject_instance.png)
			
 
				+
			
 
				+Now you are able to start working on the game object. You might create a large number of instances of the object, each one being an exact clone of what's stored in the game object file.
			
 
				+
			
 
				+![Game object clones](images/building_blocks/building_blocks_gameobject_clones.png)
			
 
				+
			
 
				+The nice thing with this model is that if you change the game object file you are changing the prototype, so any instance that uses the file as its blueprint will immediately change.
			
 
				+
			
 
				+![Game object alter file](images/building_blocks/building_blocks_gameobject_alter.png)
			
 
				+
			
 
				+## Childing game objects
			
 
				+
			
 
				+Let's now look at a case which might seem peculiar at first. Add an instance "my_gameobject" of the above prototype file to a collection, then create another game object called "heart" _in place_ (right click and select *Add Game Object*) with some component. Finally, make "heart" the child of "my_gameobject" by dragging it onto it. You now have a collection that looks like this:
			
 
				+
			
 
				+![Game object instance with child](images/building_blocks/building_blocks_gameobject_instance_child.png)
			
 
				+
			
 
				+You might assume that by dragging the "heart" object onto "my_gameobject" you would change the file "my_gameobject.go", but that is not what happens. The effect of the operation is that the game object _instance_ "my_gameobject" gets a child attached to it. The game object instance has two separate properties for its prototype and its children. When you add children to a game object instance you add the object to the object's *children* property -- you don't touch the prototype.
			
 
				+
			
 
				+If you open the collection in the text editor by right clicking and selecting *Open With > Text Editor* you can inspect the game object data structure:
			
 
				+
			
 
				+----
			
 
				+name: "default"
			
 
				+instances {
			
 
				+  id: "my_gameobject"
			
 
				+  prototype: "/a_simple_test/my_gameobject.go"
			
 
				+  children: "heart"
			
 
				+  ...
			
 
				+}
			
 
				+scale_along_z: 0
			
 
				+embedded_instances {
			
 
				+  id: "heart"
			
 
				+  data: "embedded_components {\n  id: \"sprite\"\n  type: \"sprite\"\n  data: \"tile_set: \\\"/cards_example/cards_sprites.atlas\\\"\\ndefault_animation: \\\"heart\\\"\\nmaterial: \\\"/builtins/materials/sprite.material\\\"\\nblend_mode: BLEND_MODE_ALPHA\\n\"\n  position {\n    x: 0.0\n    y: 0.0\n    z: 0.0\n  }\n  rotation {\n    x: 0.0\n    y: 0.0\n    z: 0.0\n    w: 1.0\n  }\n}\n"
			
 
				+  ...
			
 
				+}
			
 
				+----
			
 
				+
			
 
				+You can see clearly that the game object instance has a property *prototype* that is set to the game object file. It has another property *children* that lists "heart" as its only child. The game object "heart" is different. Since it's an in_place game object not based on a prototype, it is listed under *embedded_instances* and all its data is stored right inside the collection file.
			
 
				+
			
 
				+::: important
			
 
				+Apart from making a clear distinction between game object prototypes and instances when working with them in the editor, you should also take the time to carefully study how game objects are identified with a _fixed_ id in run time and how and why the id is unaffected by childing. The [Message passing documentation](/manuals/message-passing) explains this in detail.
			
 
				+:::
			
 
				+
			
 
				+At this point you might ask yourself _"What if I create a game object file with a game object and a child, and then remove the child after having instanced the object in a collection?"_ The answer is simply that you can't. A game object file is a blueprint for a single game object. It only makes sense to add children to instances of game objects, either at build time in the editor by editing a collection--or at runtime via `msg.post("my_object", "set_parent",  { parent_id = go.get_id("my_parent") })`.
			
 
				+
			
 
				+## Components
			
 
				+
			
 
				+Components are used to give specific expression and/or functionality to game objects. They don't live a life on their own but have to be contained inside game objects. There are two different ways in which you can create new components in the editor:
			
 
				+
			
 
				+1. Create a component-type _file_, then create an instance of that component inside a game object.
			
 
				+2. Create an _in-place_ instance of a component in a game object.
			
 
				+
			
 
				+In either of these cases you create components of a specific type. Opening that component in the editor fires up a component type specific editor that allows you to manipulate the component in ways that make sense for the type.
			
 
				+
			
 
				+In the previous section you saw how the editor stores embedded components in a game object though the *embedded_components* property. If we instead chose to instance the component from a file reference, the data looks like this:
			
 
				+
			
 
				+----
			
 
				+embedded_instances {
			
 
				+  id: "heart2"
			
 
				+  data: "components {\n  id: \"sprite\"\n  component: \"/a_simple_test/my_heart.sprite\"\n  position {\n    x: 0.0\n    y: 0.0\n    z: 0.0\n  }\n  rotation {\n    x: 0.0\n    y: 0.0\n    z: 0.0\n    w: 1.0\n  }\n}\n"
			
 
				+  ...
			
 
				+}
			
 
				+----
			
 
				+
			
 
				+The component specific data are stored in the component file referenced via the *component* property.
			
 
				+
			
 
				+The most common component type is probably the _script component_ that you use to create behaviors. It is easy to forget that there is a clear boundary between the script component and the containing game object. For instance, the following style of message passing is common:
			
 
				+
			
 
				+```lua
			
 
				+msg.post("my_object", "my_message", { my_data = 1 }})
			
 
				+```
			
 
				+
			
 
				+Here, we send a custom message to a game object "my_object". This usually works, but is not recommended. First, since sending messages to a game object _broadcasts_ the message to all containing components you create unnecessary overhead. Secondly, you might even break the behavior of a game object. Suppose, for instance, that the game object has several script components that all listen to the "my_message" message and they are not designed to run simultaneously. The recommended way of addressing messages is to instead be as specific as possible, and that requires that you keep the difference between game object and component in mind.
			
 
				+
			
 
				+```lua
			
 
				+msg.post("my_object#script", "my_message", { my_data = 1 })
			
 
				+```
			
 
				+
			
 
				+## Custom component properties
			
 
				+
			
 
				+Components have type specific properties that you set to alter the component in one way or another. It may be the width and height of a sprite component, or whether a sound component should loop its sound or not during playback. _Script components_, in contrast, allows you to specify custom properties for any purpose. In a script you define a script component simply by adding its definition to the script file:
			
 
				+
			
 
				+```lua
			
 
				+-- self.health will be automatically set to 100 by default. You can change
			
 
				+-- the init value for any instance containing the script component in the editor.
			
 
				+go.property("health", 100)
			
 
				+
			
 
				+function on_message(self, message_id, message, sender)
			
 
				+    -- Now we can access the property as "self.health"
			
 
				+    ...
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+A detailed explanation of how script properties work and how they can be used is found in the [Script properties documentation](/manuals/script-properties). The script properties you define are a type of instance property associated your script component. Defold stores them on file as a generic component property. If the game object is instanced from a prototype, a separate *component_properties* property is added to the object instance containing any script properties (and in the future, possibly other component properties):
			
 
				+
			
 
				+![Script properties](images/building_blocks/building_blocks_properties.png)
			
 
				+
			
 
				+----
			
 
				+  component_properties {
			
 
				+    id: "script"
			
 
				+    properties {
			
 
				+      id: "my_property"
			
 
				+      value: "4712.0"
			
 
				+      type: PROPERTY_TYPE_NUMBER
			
 
				+    }
			
 
				+  }
			
 
				+----
			
 
				+
			
 
				+Conversely, in an embedded game object, any component properties are explicitly expressed as a *properties* property in the collection file:
			
 
				+
			
 
				+![Embedded script properties](images/building_blocks/building_blocks_properties_embedded.png)
			
 
				+
			
 
				+----
			
 
				+data: "components {\n  id: \"some_script\"\n  component: \"/a_simple_test/my_thing.script\"\n  position {\n    x: 0.0\n    y: 0.0\n    z: 0.0\n  }\n  rotation {\n    x: 0.0\n    y: 0.0\n    z: 0.0\n    w: 1.0\n  }\n  properties {\n    id: \"my_property\"\n    value: \"4713.0\"\n    type: PROPERTY_TYPE_NUMBER\n  }\n}\ncomponents {\n  id: \"sprite\"\n  component: \"/a_simple_test/my_heart.sprite\"\n  position {\n    x: 0.0\n    y: 0.0\n    z: 0.0\n  }\n  rotation {\n    x: 0.0\n    y: 0.0\n    z: 0.0\n    w: 1.0\n  }\n}\n"
			
 
				+----
			
 
				+
			
 
				+## Collections
			
 
				+
			
 
				+Collections are Defold's mechanism for creating templates, or what in other engines are called "prefabs". Collections are tree structures that holds game objects and other collections. A collection is _always_ stored on file and brought into the game in one of two ways:
			
 
				+
			
 
				+1. Either at build time by placing the collection in another collection in the editor.
			
 
				+2. At runtime by dynamically loading all resources gathered in the collection through a _collection proxy_ (See [Collection proxy documentation](/manuals/collection-proxy) for details).
			
 
				+
			
 
				+![Collection instances](images/building_blocks/building_blocks_collection_instances.png)
			
 
				+
			
 
				+Collections that have been placed in the editor cannot be modified. You cannot, for instance, add children to game objects that are part of the placed collection. Why you can't do that becomes clear when you look at the data that is stored for the collection instance. The data for the containing game objects is inside the _referenced_ collection file "my_collection.collection" and that is not what you're editing.
			
 
				+
			
 
				+While you can't modify the contents of a collection instance without editing the source collection file, the editor allows modification of property values such as script properties that are associated with components in the collection.
			
 
				+
			
 
				+![Properties in a collection](images/building_blocks/building_blocks_collection_properties.png)
			
 
				+----
			
 
				+collection_instances {
			
 
				+  id: "my_collection"
			
 
				+  collection: "/a_simple_test/my_collection.collection"
			
 
				+  position {
			
 
				+    x: -172.74739
			
 
				+    y: 149.61157
			
 
				+    z: 0.0
			
 
				+  }
			
 
				+  rotation {
			
 
				+    x: 0.0
			
 
				+    y: 0.0
			
 
				+    z: 0.0
			
 
				+    w: 1.0
			
 
				+  }
			
 
				+  scale: 1.0
			
 
				+  instance_properties {
			
 
				+    id: "my_gameobject"
			
 
				+    properties {
			
 
				+      id: "script"
			
 
				+      properties {
			
 
				+        id: "my_property"
			
 
				+        value: "4717.0"
			
 
				+        type: PROPERTY_TYPE_NUMBER
			
 
				+      }
			
 
				+    }
			
 
				+  }
			
 
				+}
			
 
				+----
			
 
				+
			
 
				+::: important
			
 
				+A common misunderstanding is that a game object's place in the collection hierarchy is connected to the runtime parent-child hierarchy (which is altered with the `set_parent` message). It is important to realize that they are two different things. Collections are a means of managing and grouping, whereas the parent-child hierarchy dynamically alters the scene graph which allows objects to be visually attached to each other. The place a game object has in the collection hierarchy dictates its id, but the id is static throughout the lifetime of the object. A thorough description on game object addressing can be found in the [Message passing documentation](/manuals/message-passing).
			
 
				+:::
			
 
				+
			
--- a/docs/manuals/en/camera.md
+++ b/docs/manuals/en/camera.md
@@ -0,0 +1,167 @@
 
				+Cameras
			
 
				+=======
			
 
				+:toc: macro
			
 
				+
			
 
				+toc::[]
			
 
				+
			
 
				+Defold contains a primitive camera component. This manual describes its functionality and intended use.
			
 
				+
			
 
				+A camera is a component type that you use to provide a view into your game world. Cameras are very simple objects that in essence does the following:
			
 
				+
			
 
				+1. They have a location in space -- either 2D or 3D.
			
 
				+2. They can be moved around in space -- by moving the containing game object.
			
 
				+3. They provide the render script with the data necessary to render with computed view and projection matrices.
			
 
				+
			
 
				+Cameras in OpenGL are expressed as coordinate systems with a viewer, or eye, position, a near and a far clipping plane. The near clipping plane equals the viewing plane, or the screen.
			
 
				+
			
 
				+![Camera planes](images/cameras/cameras_planes.png)
			
 
				+
			
 
				+A 3D camera usually have a viewing volume, a _frustum_, that is shaped like a cut off pyramid. The effect of this is that objects further away from the camera will be rendered smaller--the perspective will be realistic. The wider the _field of view_, the more the camera sees of the scenery, and the more dramatic will the difference between near and far object be.
			
 
				+
			
 
				+![Camera field of view](images/cameras/cameras_fov.png)
			
 
				+
			
 
				+## Creating a camera
			
 
				+
			
 
				+To create a camera, add a _Camera component_ to a game object:
			
 
				+
			
 
				+![Create camera component](images/cameras/cameras_create_component.png)
			
 
				+
			
 
				+The camera component has a set of properties that defines the camera frustum.
			
 
				+
			
 
				+![Camera properties](images/cameras/cameras_properties.png)
			
 
				+
			
 
				+::: important
			
 
				+The current default FOV value is misleading. It is not expressed in degrees but in radians. For a 45 degree FOV, change the value to 0.785 (PI / 4).
			
 
				+:::
			
 
				+
			
 
				+aspect_ratio
			
 
				+: The ratio between the frustum width and height. 1.0 means that you assume a quadratic view. 1.33 is good for a 4:3 view like 1024x768. 1.78 is good for a 16:9 view.
			
 
				+
			
 
				+fov
			
 
				+: The camera field of view expressed in _radians_.
			
 
				+
			
 
				+near_z
			
 
				+: The Z-value of the near clipping plane.
			
 
				+
			
 
				+far_z
			
 
				+: The Z-value of the far clipping plane.
			
 
				+
			
 
				+auto_aspect_ratio
			
 
				+: Set this to 1 to let the camera automatically set the aspect ratio based on the game's screen settings.
			
 
				+
			
 
				+
			
 
				+## Camera focus
			
 
				+
			
 
				+To activate the camera and have it feed its view and projection matrices, you send the component a `acquire_camera_focus` message:
			
 
				+
			
 
				+```lua
			
 
				+msg.post("#camera", "acquire_camera_focus")
			
 
				+```
			
 
				+
			
 
				+As soon as the camera component has camera focus, it will each frame send a `set_view_projection` message to the `@render` socket, i.e. to your render script:
			
 
				+
			
 
				+```lua
			
 
				+-- example.render_script
			
 
				+--
			
 
				+function update(self)
			
 
				+    ...
			
 
				+    render.set_view(self.view)
			
 
				+
			
 
				+    render.set_projection(self.projection)
			
 
				+    ...
			
 
				+end
			
 
				+
			
 
				+function on_message(self, message_id, message)
			
 
				+    if message_id == hash("set_view_projection") then
			
 
				+    	-- Camera view and projection arrives here. Store them.
			
 
				+        self.view = message.view
			
 
				+        self.projection = message.projection
			
 
				+    end
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+If you use both camera view and projection in your render script you will get a camera view into your game world with 3D perspective, even though your game content is strictly 2D. This is sometimes useful. You can, for instance, move the camera back to reveal more of the level. A simple camera script that measures the current camera move speed and pulls it back relative that speed could look like this:
			
 
				+
			
 
				+```lua
			
 
				+-- camera.script
			
 
				+--
			
 
				+function init(self)
			
 
				+	msg.post("#camera", "acquire_camera_focus")
			
 
				+
			
 
				+    -- Track current position and where someone told us to look at.
			
 
				+	self.pos = go.get_world_position()
			
 
				+	self.look_at = self.pos
			
 
				+    -- Store measured speed
			
 
				+	self.speed = 0
			
 
				+end
			
 
				+
			
 
				+function update(self, dt)
			
 
				+	-- Calculate a new position based on current pos interpolated towards current
			
 
				+	-- target position.
			
 
				+	self.pos = vmath.lerp(0.03, self.pos, self.look_at)
			
 
				+	
			
 
				+	-- Measure speed on the 2D plane (zero Z)
			
 
				+	local v1 = go.get_world_position()
			
 
				+	v1.z = 0
			
 
				+	local v2 = self.pos
			
 
				+	v2.z = 0
			
 
				+	local speed = vmath.length(v2 - v1)
			
 
				+
			
 
				+	-- Depending on how fast player is moving, pull camera back or push it forward.
			
 
				+	self.pos.z = 500 + speed * speed * 10
			
 
				+	go.set_position(self.pos)
			
 
				+end
			
 
				+
			
 
				+function on_message(self, message_id, message, sender)
			
 
				+    -- This camera reacts to "look_at" messages with a position as where
			
 
				+    -- to go.
			
 
				+	if message_id == hash("look_at") then	
			
 
				+		self.look_at = message.position
			
 
				+	end
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+![Camera speed distance](images/cameras/cameras_speed_distance.png)
			
 
				+
			
 
				+Of course, we're not limited to moving the camera around. We can also rotate it along its X, Y and Z axis.
			
 
				+
			
 
				+```lua
			
 
				+-- 0.314 radians is about 18 degrees.
			
 
				+go.set_rotation(vmath.quat_rotation_z(0.314) * vmath.quat_rotation_y(0.314))
			
 
				+```
			
 
				+
			
 
				+![Rotated camera](images/cameras/cameras_camera_rotated.png)
			
 
				+
			
 
				+## Orthographic projection
			
 
				+
			
 
				+For many 2D games, the business of having a camera that can move back and forth becomes a problem, especially if you have content that you would like to render pixel perfect. Instead of trying to place your camera at the perfect Z distance to get the view you want, you should instead set up a camera with _orthographic projection_. This means that the view of the camera is no longer dictated by a frustum, but by a much simpler box.
			
 
				+
			
 
				+![Orthographic projection](images/cameras/cameras_orthographic.png)
			
 
				+
			
 
				+Orthographic projection is unrealistic in that it does not alter the size of objects based on their distance. A person standing 10000 meters away will still render at the same size as the person standing right in front of the camera. However, this method of projecting graphics is sometimes useful and 2D games often benefit from using it. To use orthographic projection you just have to modify your render script:
			
 
				+
			
 
				+```lua
			
 
				+-- example.render_script
			
 
				+--
			
 
				+function update(self)
			
 
				+    ...
			
 
				+    render.set_view(self.view)
			
 
				+    -- Set up an orthographic projection based on the width and height of the
			
 
				+    -- game window.
			
 
				+	local w = render.get_width()
			
 
				+	local h = render.get_height()
			
 
				+	render.set_projection(vmath.matrix4_orthographic(- w / 2, w / 2, -h / 2, h / 2, -1000, 1000))
			
 
				+    ...
			
 
				+end
			
 
				+
			
 
				+function on_message(self, message_id, message)
			
 
				+    if message_id == hash("set_view_projection") then
			
 
				+    	-- Camera view and projection arrives here. We only need the view.
			
 
				+        self.view = message.view
			
 
				+    end
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+This is almost what the default render script does, with the difference that the above example centers the screen at the camera position.
			
 
				+
			
 
				+(Some of the graphic assets used are made by Kenney: http://kenney.nl/assets)
			
--- a/docs/manuals/en/clipping.md
+++ b/docs/manuals/en/clipping.md
@@ -0,0 +1,58 @@
 
				+Clipping
			
 
				+========
			
 
				+:location: documentation manuals gui
			
 
				+:type: manual
			
 
				+
			
 
				+GUI nodes with textures or text add graphics to the GUI. However, sometimes it is convenient to be able to _mask_ what is being shown, to be able to _remove_ particular parts of the graphics from the screen. This manual explains how to achieve that. 
			
 
				+
			
 
				+Say, for instance, that you want to create an on-screen HUD element containing a mini-map that the player can use to help orient herself in your game.
			
 
				+
			
 
				+![Minimap HUD](images/clipping/clipping_minimap.png)
			
 
				+
			
 
				+Using a pie node with clipping makes creating the minimap a very easy task:
			
 
				+
			
 
				+![Making the minimap](images/clipping/clipping_making_minimap.png)
			
 
				+
			
 
				+- Add a pie node. It will act as a "keyhole" for the map.
			
 
				+- Add a box node and apply the map texture to it.
			
 
				+- Child the box node to the pie node.
			
 
				+- Set the *Clipping* property of the pie node to "Stencil".
			
 
				+
			
 
				+![Clipping preview](images/clipping/clipping_preview.png)
			
 
				+
			
 
				+Now the parent node will act as a "keyhole" down to its children. Only graphics bound by the parent clipping node will show so the parent node will define the graphical outer bounds of the map. We are therefore free to move the map node around and whatever part is currently within the parent bounds will show.
			
 
				+
			
 
				+Clipping can be applied to box nodes and pie nodes. Text nodes can not clip other nodes. Two different types of clipping is available and a node can be set to *Visible clipper* which draws the clipper shape, and *Inverted clipper* which inverts how the clipper affects the clipping mask (see below for details).
			
 
				+
			
 
				+![Clipping properties](images/clipping/clipping_properties.png)
			
 
				+
			
 
				+Stencil clipping can be applied to box nodes and pie nodes. Stencils has some limitations:
			
 
				+
			
 
				+- The total number of stencil clippers can not exceed 256.
			
 
				+- The maximum nesting depth of child _stencil_ nodes is 8 levels deep. (Only nodes with stencil clipping count.)
			
 
				+- The maximum number of stencil node siblings is 127. For each level down a stencil hierarchy, the max limit is halved.
			
 
				+- Inverted nodes have a higher cost. There is a limit to 8 inverted clipping nodes and each will halve the max amount of non-inverted clipping nodes.
			
 
				+- Stencils render a stencil mask from the _geometry_ of the node (not the texture). It is possible to invert the mask by setting the *Inverted clipper* property.
			
 
				+
			
 
				+## Stencil mask
			
 
				+
			
 
				+To understand how stencil clipping works, it is useful to imagine how a hierarchy of stencils apply their individual clipping shapes, in turn down the hierarchy, to the total mask. The mask set of a clipping node is inherited to the children of that node and the children can never _extend_ the mask, only clip it. Let's look at a concrete example:
			
 
				+
			
 
				+![Clipping hierarchy](images/clipping/clipping_hierarchy.png)
			
 
				+
			
 
				+The hexagon and square shapes are both set to stencil clippers. Setting the *Inverted clipper* property inverts the mask as inherited to that node. For the hierarchy above, four combinations of normal and inverted clippers are possible:
			
 
				+
			
 
				+![Stencil masks](images/clipping/clipping_stencil_masks.png)
			
 
				+
			
 
				+If a node below an inverted node is also set to *Inverted clipper*, the part of the mask bound by the child node is in turn inverted. By childing inverted clippers to each other, it is thus possible to cut multiple holes in a node:
			
 
				+
			
 
				+![Two inverters cutting a node](images/clipping/clipping_two_inverters.png)
			
 
				+
			
 
				+## Layers
			
 
				+
			
 
				+Layers can be used to control rendering order (and batching) of nodes. When using layers and clipping nodes the usual layering order is overridden. Clipping order take precedence over layer order, meaning that regardless of what layer a node belongs to, it will be clipped according to the node hierarchy. Layers only affects the draw order of graphics--and furthermore, the layer set on a clipping node does only affect the draw order _in that clipper's hierarchy_.
			
 
				+
			
 
				+To illustrate, consider this clipper node "window_and_shadow" that has an inner shadow texture applied to it. By setting the node's *Visible clipper* property and then layering it ("layer2") in relation to the clipped "map" node ("layer0"), the clipper's texture is rendered on top of the child "map". Note that the layer set on "map", nor the one on "window_and_shadow", has any effect on its render order in relation to "blue_box" ("layer2") and "orange_box" ("layer1"). If you want to change the render order of "window_and_shadow" in relation to "blue_box" and "orange_box", simply change their order in the node tree.
			
 
				+
			
 
				+![Layers and clipping](images/clipping/clipping_layers.png)
			
 
				+
			
--- a/docs/manuals/en/collection-factory.md
+++ b/docs/manuals/en/collection-factory.md
@@ -0,0 +1,72 @@
 
				+= Collection factories
			
 
				+:location: documentation manuals resources
			
 
				+:type: manual
			
 
				+
			
 
				+The collection factory component is used to spawn ready made blueprint hierarchies of game objects (collections) into a running game. This manual explains how collection factories work and how to use them.
			
 
				+
			
 
				+Collections provide a powerful mechanism to create reusable templates, or "prefabs" in Defold. For an overview on Collections, see the [Building blocks documentation](/manuals/building-blocks#_collections). Collections can be placed in the editor and be cloned into the game at compile-time, and they can be dynamically inserted into your game in two ways:
			
 
				+
			
 
				+1. Loaded through collection proxies. This method essentially loads a new isolated world (including how physics interact) into a running game. The loaded collection is accessed through a new socket. All assets contained in the collection are loaded through the proxy when you message the proxy to start loading. This makes them very useful to, for instance, change levels in a game. For more information, see the [Collection proxy documentation](/manuals/collection-proxy).
			
 
				+
			
 
				+2. Collection factory components allow spawning of the content of a collection proxy into the current main collection. This is analogous to performing factory spawning of all game objects inside the collection and then building the parent-child hierarchy between the objects. Typical use cases is to spawn enemies consisting of multiple game objects (enemy + weapon, for instance).
			
 
				+
			
 
				+## Spawning a collection
			
 
				+
			
 
				+For the simple case, spawning a collection is performed exactly as when spawning a game object. Suppose we creating a planet sprite and want to spawn complex astronaut figures on the planet surface. We can then simply add a *Collection factory* to the "planet" gameobject and set "astronaut.collection" (supposing it exists) as the component's *prototype*:
			
 
				+
			
 
				+![Collection factory](images/collection_factory/collection_factory_factory.png)
			
 
				+
			
 
				+Spawning an astronaut is now a matter of sending a message to the factory:
			
 
				+
			
 
				+```
			
 
				+local astro = collectionfactory.create("#factory", nil, nil, {}, nil)
			
 
				+```
			
 
				+
			
 
				+The astronaut that is spawned is a tree of game objects, and we need to be able to address all those objects after spawning:
			
 
				+
			
 
				+![Collection to spawn](images/collection_factory/collection_factory_collection.png)
			
 
				+
			
 
				+The regular factory component returns an id to the spawned object. The collection factory returns a table that maps a hash of the collection-local id of each object to the runtime id of each object. A prefix "/collectionNN/" is added to the id to uniquely identify each instance:
			
 
				+
			
 
				+```
			
 
				+pprint(astro)
			
 
				+-- DEBUG:SCRIPT:
			
 
				+-- {
			
 
				+--   hash: [/probe2] = hash: [/collection0/probe2],
			
 
				+--   hash: [/probe1] = hash: [/collection0/probe1],
			
 
				+--   hash: [/astronaut] = hash: [/collection0/astronaut],
			
 
				+-- }
			
 
				+```
			
 
				+
			
 
				+Observe that the parent-child relations between "astronaut" and "probe" is not reflected in the id/path of the objects but only in the runtime scene-graph, i.e. how objects are transformed together. Re-parenting an object never changes its id.
			
 
				+
			
 
				+## Properties
			
 
				+
			
 
				+When spawning a collection, we can pass property parameters to each game object by constructing a table with pairs of collection-local object id:s and tables of script properties to set:
			
 
				+
			
 
				+```
			
 
				+-- planet.script
			
 
				+--
			
 
				+local props = {}
			
 
				+props[hash("/astronaut")] = { size = 10.0 }
			
 
				+props[hash("/probe1")] = { color = hash("red") }
			
 
				+props[hash("/probe1")] = { color = hash("green") }
			
 
				+local astro = collectionfactory.create("#factory", nil, nil, props, nil)
			
 
				+...
			
 
				+```
			
 
				+
			
 
				+Each spawned instance of "astronaut" gets its "size" property set to the passed value and each "probe" its "color" property:
			
 
				+
			
 
				+```
			
 
				+-- probe.script
			
 
				+--
			
 
				+go.property("color", hash("blue"))
			
 
				+
			
 
				+function init(self)
			
 
				+  ...
			
 
				+```
			
 
				+
			
 
				+By spawning a set of astronauts and carefully placing them and passing the right properties, we can now populate the planet:
			
 
				+
			
 
				+![Populated planet](images/collection_factory/collection_factory_game.png)
			
 
				+
			
--- a/docs/manuals/en/collection-proxy.md
+++ b/docs/manuals/en/collection-proxy.md
@@ -0,0 +1,323 @@
 
				+Collection Proxies
			
 
				+==================
			
 
				+
			
 
				+Defold organizes all game objects in collections. This manual explains how to dynamically load and unload collections into a running game.
			
 
				+
			
 
				+A collection can contain game objects and other collections (i.e. sub-collections). When Defold starts up it loads, initiates and enables a top level collection as defined in the project settings (see [Project settings](/manuals/project-settings)). Most templates have a preset "main.collection" that loads at startup.
			
 
				+
			
 
				+For many projects, containing the whole app in the top level collection is sufficient, but there are several cases (see below) where you will need a more powerful means of organizing your project: dynamically loading and unloading top level collections within your project.
			
 
				+
			
 
				+Collection proxies act as an outlet that serves on behalf of a collection file—you can communicate with a collection file that is not yet loaded by proxy.  You can tell it to load, initialize, enable, disable, finalize and unload.
			
 
				+
			
 
				+All communication with collection proxies regarding loading and unloading is done asynchronously: however, the actual loading and unloading is not implemented as a background process, so the engine will briefly pause when the actual loading and unloading happens.
			
 
				+
			
 
				+## Typical use cases
			
 
				+
			
 
				+Many games are separated into separate levels that are played one after the other. If your level content is manually built in the editor you will end up with a group of collections, each with a level inside (consisting of tilemaps, sprites etc). Collection proxies allow you to do this separation of content and then dynamically manage them through scripting.
			
 
				+
			
 
				+Possible uses of collection proxies are:
			
 
				+
			
 
				+* Loading/unloading of game levels.
			
 
				+* Loading/unloading of front end GUI.
			
 
				+* Loading/unloading of narrative "scenes" throughout a level.
			
 
				+* Loading/unloading of mini-games.
			
 
				+* Loading/unloading of user selected content (music, background images etc)
			
 
				+
			
 
				+::: sidenote
			
 
				+Loading/unloading ("streaming") of regions in a seamless large world is possible to implement with collection proxies, but know that the actual loading is synchronous (meaning that they do not happen in the background, but pauses the game until loading is done) and can span over several frames. Therefore, you would want to keep the world pieces small or find a way to  hide the loading pauses somehow.
			
 
				+:::
			
 
				+
			
 
				+## Worlds
			
 
				+
			
 
				+Through collection proxies is it thus possible to switch the top level collection, or to load more than one top level collection into the engine. When doing so it is important to know that each top level collection is a separate physical world. Physics interactions (collisions, triggers, ray-casts) happens between objects belonging to the same collection. There is no physics interaction happening between objects belonging to different top level collections.
			
 
				+
			
 
				+In the following example we have split the game world into two collections that we dynamically load through collection proxies. The loading and unloading of the two collections is controlled by a game object called "loader" that we put in our main collection "worlds". We configure the game to automatically load the "worlds.collection" file at startup (see [Project settings documentation](/manuals/project-settings) for details). The collection "worlds" will hold the "loader" object as well as the GUI elements that allow us to move our character around.
			
 
				+
			
 
				+![Worlds 1](images/collection_proxies/collection_proxy_worlds_loader.png)
			
 
				+
			
 
				+The first collection, "world1", is on the left with purple ground tiles. To the right of the "exit" sign is  the "world2" collection with green ground tiles.
			
 
				+
			
 
				+![Worlds 1](images/collection_proxies/collection_proxy_worlds_1.png)
			
 
				+
			
 
				+Our player character is set up with physics collision against all ground tiles in the level and that allows the player to roll the character on the ground. But let’s see what happens when the player reaches the end of the "world1" collection:
			
 
				+
			
 
				+![Worlds 2](images/collection_proxies/collection_proxy_worlds_2.png)
			
 
				+
			
 
				+The tiles in "world2" have exactly the same collision set up as in "world1", but since the player character game object belongs to "world1", no collision is registered and the character falls through the world.
			
 
				+
			
 
				+In games where levels are fully contained within a collection and the player is not expected to seamlessly move between the levels you will never encounter this aspect of collections as separate worlds.
			
 
				+
			
 
				+Later we’re going to look deeper into this example and explore how a game can use physics collision and triggers and yet dynamically load pieces of a game world that the player can move between. But first, let’s look at collection proxy basics.
			
 
				+
			
 
				+## Editing
			
 
				+
			
 
				+To set up a collection proxy you simply add a collection proxy component to a game object. You then name the proxy (give it an id) and tell it which collection file it acts on behalf of:
			
 
				+
			
 
				+![Editing](images/collection_proxies/collection_proxy_editing.png)
			
 
				+
			
 
				+## Naming collections
			
 
				+
			
 
				+Before you start communicating with your collection proxy, you should check the name of each of your collections. Each collection you create in the editor will automatically be assigned the name "default". As long as you’re not dynamically loading that collection through a proxy you can keep that name.
			
 
				+
			
 
				+![Naming](images/collection_proxies/collection_proxy_name.png)
			
 
				+
			
 
				+However, when you load more than one top level collection through collection proxies, each one must be addressable through the socket part of a URL, and that socket name must be unique:
			
 
				+
			
 
				+```lua
			
 
				+msg.post("world1:manager#script", "remove_player")
			
 
				+msg.post("world2:manager#script", "spawn_player")
			
 
				+```
			
 
				+
			
 
				+So a collection you want to load through a proxy should be renamed to a unique name. If you don’t give it a unique name the engine will signal a name collision error:
			
 
				+
			
 
				+----
			
 
				+ERROR:GAMEOBJECT: The collection 'default' could not be created since there is already a socket with the same name.
			
 
				+WARNING:RESOURCE: Unable to create resource: build/default/worlds/world1.collectionc
			
 
				+ERROR:GAMESYS: The collection /worlds/world1.collectionc could not be loaded.
			
 
				+----
			
 
				+
			
 
				+## Loading
			
 
				+
			
 
				+Loading a collection through a proxy is done by sending a message "load" to a proxy component in a game object:
			
 
				+
			
 
				+```lua
			
 
				+-- Tell the proxy "world1" to start loading.
			
 
				+msg.post("loader#world1", "load")
			
 
				+```
			
 
				+
			
 
				+The proxy will send back a message "proxy_loaded" when the loading is done. You can then initialize and enable the collection:
			
 
				+
			
 
				+```lua
			
 
				+function on_message(self, message_id, message, sender)
			
 
				+        if message_id == hash("proxy_loaded") then
			
 
				+                -- New world is loaded. Init and enable it.
			
 
				+                msg.post(sender, "init")
			
 
				+                msg.post(sender, "enable")
			
 
				+                ...
			
 
				+```
			
 
				+
			
 
				+Alternatively your logic can check the origin of the message an act accordingly. The collection proxy that sent the "proxy_loaded" is indicated in the fragment part of the sender URL:
			
 
				+
			
 
				+```lua
			
 
				+function on_message(self, message_id, message, sender)
			
 
				+        if message_id == hash("proxy_loaded") and sender.fragment == hash("myproxy1") then
			
 
				+                -- "myproxy1" is loaded. Let’s init and enable it.
			
 
				+                ...
			
 
				+```
			
 
				+
			
 
				+Initializing the collection through the proxy with the "init" message will recursively initialize all the objects contained in the collection. Enabling the collection through the proxy with the "enable" message recursively enables all the objects contained in the collection.
			
 
				+
			
 
				+(See [Application lifecycle](/manuals/application-lifecycle) for details on the lifespan of an object)
			
 
				+
			
 
				+Sending "enable" to a loaded proxy will automatically initialize the collection before it is enabled. So if you don’t need fine grained control through the initialization and enable steps you can just do:
			
 
				+
			
 
				+```lua
			
 
				+-- New world is loaded. Init and enable it.
			
 
				+msg.post(sender, "enable")
			
 
				+```
			
 
				+
			
 
				+In our platformer example we put a trigger in the "world1" collection at the point where we want to load "world2":
			
 
				+
			
 
				+![Trigger](images/collection_proxies/collection_proxy_trigger.png)
			
 
				+
			
 
				+We make the trigger part of a "worldswitch" game object that contains the switching logic, to it we tie two properties that allow us to reuse the object. Since the properties are hashes we need to construct URL objects to communicate with the proxies. Note that we want to send our messages to the collection "worlds", where we put our "loader" game object:
			
 
				+
			
 
				+```lua
			
 
				+go.property("selfworld", hash(""))
			
 
				+go.property("otherworld", hash(""))
			
 
				+
			
 
				+function init(self)
			
 
				+        -- Construct urls for the proxies. We're gonna use these later.
			
 
				+        self.selfurl = msg.url()
			
 
				+        self.selfurl.socket = "worlds"
			
 
				+        self.selfurl.path = hash("/loader")
			
 
				+        self.selfurl.fragment = self.selfworld
			
 
				+        self.otherurl = msg.url()
			
 
				+        self.otherurl.socket = "worlds"
			
 
				+        self.otherurl.path = hash("/loader")
			
 
				+        self.otherurl.fragment = self.otherworld
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+Here’s the setup in the "world2" collection:
			
 
				+
			
 
				+![Trigger world 2](images/collection_proxies/collection_proxy_trigger_2.png)
			
 
				+
			
 
				+The "exit" sign is placed in the exact same coordinates in both collections giving one tile of overlap between them. Also notice that there is a "player" object in "world2" as well as in "world1". Because each collection is its own physics world we need a separate player in each and we just make sure to transfer the position and input control from one player object to the other when we move between the worlds.
			
 
				+
			
 
				+So, when the player hits the trigger in "world1" we start by loading "world2":
			
 
				+
			
 
				+```lua
			
 
				+function on_message(self, message_id, message, sender)
			
 
				+        if message_id == hash("trigger_response") and message.enter then
			
 
				+                -- Player hits the world switch trigger.
			
 
				+                -- Load the next world as referenced through the
			
 
				+                -- previously constructed url.
			
 
				+                msg.post(self.url, "load")
			
 
				+                ...
			
 
				+```
			
 
				+We then enable the collection when it’s loaded:
			
 
				+
			
 
				+```lua
			
 
				+        elseif message_id == hash("proxy_loaded") then
			
 
				+                -- New world is loded. Enable it.
			
 
				+                msg.post(sender, "enable")
			
 
				+```
			
 
				+
			
 
				+And then it’s time to switch the player object. We start by sending the current player a message requesting the data we need, which is the current position of the player object:
			
 
				+
			
 
				+```lua
			
 
				+                -- We have to transfer the position of the player
			
 
				+                -- to the player in the other world.
			
 
				+                local currentsocket = ""
			
 
				+                -- We can't use the hashed properties to build
			
 
				+                -- strings:
			
 
				+                if self.selfworld == hash("world1") then
			
 
				+                        currentsocket = "world1"
			
 
				+                elseif self.selfworld == hash("world2") then
			
 
				+                        currentsocket = "world2"
			
 
				+                end
			
 
				+                msg.post(currentsocket .. ":" .. "/player#script", "request_player")
			
 
				+```
			
 
				+
			
 
				+We get a response back and pass the player data to the player in the newly loaded collection:
			
 
				+
			
 
				+```lua
			
 
				+        elseif message_id == hash("player_response") then
			
 
				+                -- We're getting player position back.
			
 
				+                -- Now we have to apply it to the other world's player.
			
 
				+                local othersocket = ""
			
 
				+                if self.otherworld == hash("world1") then
			
 
				+                        othersocket = "world1"
			
 
				+                elseif self.otherworld == hash("world2") then
			
 
				+                        othersocket = "world2"
			
 
				+                end
			
 
				+                -- Pass along the message we got back.
			
 
				+                msg.post(othersocket .. ":" .. "/player#script", "inherit_player", message)
			
 
				+        end
			
 
				+```
			
 
				+
			
 
				+The message "inherit_player" just inherits the position sent so the new player is repositioned to the same spot where the old player was (in the trigger, which is fine. It won’t detect the new player since they are parts of two different collections, and physical worlds)
			
 
				+
			
 
				+If we run the game we can move from "world1" to "world2", but the player object in "world1" is still present, and will fall through the world of "world2".
			
 
				+
			
 
				+![Loading 1](images/collection_proxies/collection_proxy_loading_1.png)
			
 
				+
			
 
				+But now we can control the player object of "world2" and roll the character further into the level:
			
 
				+
			
 
				+![Loading 2](images/collection_proxies/collection_proxy_loading_2.png)
			
 
				+
			
 
				+## Unloading
			
 
				+
			
 
				+Now we only have to clean up the world switch a bit. For illustrative purposes we will simply unload the collection we’re leaving. But first, let’s look at how unloading works.
			
 
				+
			
 
				+Unloading is handled conversely to loading:
			
 
				+
			
 
				+```lua
			
 
				+msg.post("loader#world1", "disable")
			
 
				+msg.post("loader#world1", "final")
			
 
				+msg.post("loader#world1", "unload")
			
 
				+```
			
 
				+
			
 
				+Disabling the collection through the proxy with "disable" sends recursively disables all the objects in the collection. Finalizing the collection through the proxy with a "final" message recursively finalizes all the objects in the collection and "unload" removes the collection from memory.
			
 
				+
			
 
				+When the proxy has unloaded the collection it will send back a "proxy_unloaded" message:
			
 
				+
			
 
				+```lua
			
 
				+if message_id == hash("unload_level") then
			
 
				+    local proxy = msg.url("#proxy")
			
 
				+    msg.post(proxy, "disable")
			
 
				+    msg.post(proxy, "final")
			
 
				+    msg.post(proxy, "unload")
			
 
				+elseif message_id == hash("proxy_unloaded") then
			
 
				+    -- Ok, the level is unloaded
			
 
				+    ...
			
 
				+```
			
 
				+
			
 
				+If you don’t need the finer grained control, you can send the "unload" message without first disabling and finalizing the collection. The proxy will then automatically disable and finalize the collection before it’s unloaded.
			
 
				+
			
 
				+Now back to our platformer example where the only thing we need to do is to send the messages to the right proxy. We do that right after we send the request for data to the new player object:
			
 
				+
			
 
				+```lua
			
 
				+...
			
 
				+msg.post(currentsocket .. ":" .. "/player#script", "request_player")
			
 
				+
			
 
				+-- Now it's time to ditch the world we left behind.
			
 
				+-- Normally you wouldn't do this on-screen but we're doing just that
			
 
				+-- to make the whole process clearer and clearly visible.
			
 
				+msg.post(self.selfurl, "disable")
			
 
				+msg.post(self.selfurl, "final")
			
 
				+msg.post(self.selfurl, "unload")
			
 
				+```
			
 
				+
			
 
				+And now the collection that is left will unload behind the player:
			
 
				+
			
 
				+![Unloading](images/collection_proxies/collection_proxy_unloading.png)
			
 
				+
			
 
				+In a real game you wouldn’t want to unload a collection that is still visible on screen. Moreover, you would want to make a smoother player object switch. This simple example just inherits the position of the old player, but the angular and linear velocity is just reset to zero. Depending on your player control you could inherit momentum and animation state of the player object, or you could mask the switch point somehow.
			
 
				+
			
 
				+## Input
			
 
				+
			
 
				+If you have objects in your loaded collection that require input actions, you need to make sure that the game object that contain the collection proxy acquires input. When the game object receives input messages these are propagated to the components of that object, i.e. the collection proxies. The input actions are sent via the proxy into the loaded collection.
			
 
				+
			
 
				+![Input](images/collection_proxies/collection_proxy_input.png)
			
 
				+
			
 
				+If we want to receive input action in objects belonging to either "world1" or "world2", we simply acquire input focus in the script for the "loader" game object:
			
 
				+
			
 
				+```lua
			
 
				+function init(self)
			
 
				+        -- Acquire input so collection objects will receive it.
			
 
				+        msg.post(".", "acquire_input_focus")
			
 
				+        ...
			
 
				+```
			
 
				+
			
 
				+Any object in either "world1" or "world2" (that is loaded) can now send "acquire_input_focus" and start receiving input actions. (For more information on input, see [Input](/manuals/input))
			
 
				+
			
 
				+## Time step
			
 
				+
			
 
				+Each collection proxy can individually control the update time step in relation to the application update frequency. You can set the global update frequency in the application project settings (it defaults to 60 frame updates per seconds), or it can be set by sending a message to the `@system` socket:
			
 
				+
			
 
				+```lua
			
 
				+msg.post("@system:", "set_update_frequency", { frequency = 60 } )
			
 
				+```
			
 
				+
			
 
				+Collection proxy updates can be scaled by altering the _time step_. This means that even though the game ticks at a steady 60 FPS, a proxy can update at a higher or lower pace, affecting physics and the "dt" variable passed to `update()`. You can also set the update mode, which allows you to control if the scaling should be performed discretely (which only makes sense with a scale factor below 1.0) or continuously.
			
 
				+
			
 
				+You control the scale factor and the scaling mode by sending the proxy a "set_time_step" message:
			
 
				+
			
 
				+```lua
			
 
				+-- update proxy collection at one-fifth-speed.
			
 
				+msg.post("#proxy", "set_time_step", {factor = 0.2, mode = 1}
			
 
				+```
			
 
				+
			
 
				+To see what's happening when changing the time step, we can create an object with the following code in a script component and put it in the collection we're altering the timestep of:
			
 
				+
			
 
				+```lua
			
 
				+function update(self, dt)
			
 
				+        print("update() with timestep (dt) " .. dt)
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+With a time step of 0.2, we get the following result in the console:
			
 
				+
			
 
				+----
			
 
				+INFO:DLIB: SSDP started (ssdp://192.168.0.102:54967, http://0.0.0.0:62162)
			
 
				+INFO:ENGINE: Defold Engine 1.2.37 (6b3ae27)
			
 
				+INFO:ENGINE: Loading data from: build/default
			
 
				+DEBUG:SCRIPT: update() with timestep (dt) 0
			
 
				+DEBUG:SCRIPT: update() with timestep (dt) 0
			
 
				+DEBUG:SCRIPT: update() with timestep (dt) 0
			
 
				+DEBUG:SCRIPT: update() with timestep (dt) 0
			
 
				+DEBUG:SCRIPT: update() with timestep (dt) 0.016666667535901
			
 
				+DEBUG:SCRIPT: update() with timestep (dt) 0
			
 
				+DEBUG:SCRIPT: update() with timestep (dt) 0
			
 
				+DEBUG:SCRIPT: update() with timestep (dt) 0
			
 
				+DEBUG:SCRIPT: update() with timestep (dt) 0
			
 
				+DEBUG:SCRIPT: update() with timestep (dt) 0.016666667535901
			
 
				+----
			
 
				+
			
 
				+`update()` is still called 60 times a second, but the "dt" value changes. We see that only 1/5 (0.2) of the calls to `update()` will have a "dt" of 1/60 (corresponding to 60 FPS) -- the rest is zero. All physics simulations will also be updated according to that dt and advance only in one fifth of the frames.
			
 
				+
			
 
				+See [set_time_step](/ref/collection-proxy#set_time_step) for more details.
			
 
				+
			
 
				+(Some of the graphic assets used are made by Kenney: http://kenney.nl/assets)
			
--- a/docs/manuals/en/debugging.md
+++ b/docs/manuals/en/debugging.md
@@ -0,0 +1,199 @@
 
				+Debugging
			
 
				+=========
			
 
				+:location: documentation manuals logic
			
 
				+:type: manual
			
 
				+
			
 
				+This manual explains the debugging facilities present in Defold.
			
 
				+
			
 
				+The simplest way to debug your game in Defold is to use [print debugging](http://en.wikipedia.org/wiki/Debugging#Techniques). The technique is simply to use `print()` or [pprint()](/ref/builtins#pprint) statements to watch variables or indicate the flow of execution. If a game object without a script acts weird, you can just attach a script to it with the sole purpose of debugging.
			
 
				+
			
 
				+Using any of the printing functions will print to the Console view in the Editor. You can also draw text on screen by posting `draw_text` messages to the `@render` socket:
			
 
				+
			
 
				+```lua
			
 
				+msg.post("@render:", "draw_text", {text = "My value: " .. my_val, position = vmath.vector3(200, 200, 0)})
			
 
				+```
			
 
				+
			
 
				+If you run into problems with spatial calculations, like movement and physics, it is often very helpful to visualize the calculations by drawing lines on the screen. Send `draw_line` messages to the `@render` socket:
			
 
				+
			
 
				+```lua
			
 
				+msg.post("@render:", "draw_line", {start_point = my_start, end_point = my_end, color = my_color})
			
 
				+```
			
 
				+
			
 
				+Lua comes with a debug library that is useful in some situations, particularly if you need to inspect the innards of your Lua environment. You can find more information about it on http://www.lua.org/pil/contents.html#23.
			
 
				+
			
 
				+## Debugging Lua scripts with ZeroBrane
			
 
				+
			
 
				+Defold engine comes with built-in support for debugging your Lua scripts through the free and open-source Lua IDE _ZeroBrane Studio_. ZeroBrane Studio needs to be installed in order to use the debugging features. The program is cross-platform and runs on both OSX and Windows.
			
 
				+
			
 
				+Download "ZeroBrane Studio" from http://studio.zerobrane.com
			
 
				+
			
 
				+## ZeroBrane configuration
			
 
				+
			
 
				+In order for ZeroBrane to find the files in your project, you need to point it to the location of your Defold project directory. A convenient way of finding this out is by using the *Show in Finder/Explorer* option in your Defold project.
			
 
				+
			
 
				+1. Right click on "game.project"
			
 
				+2. Choose *Show in Finder*, for OS X users, or *Show in Explorer* for Windows users
			
 
				+
			
 
				+OS X:
			
 
				+
			
 
				+![Show in Finder](images/debugging/showinfind.png)
			
 
				+
			
 
				+Windows:
			
 
				+
			
 
				+![Show in Explorer](images/debugging/showinwin.png)
			
 
				+
			
 
				+## To set up ZeroBrane
			
 
				+
			
 
				+To set up ZeroBrane, select menu:Project[Project Directory > Choose...]:
			
 
				+
			
 
				+![Auto completion](images/debugging/setup.png)
			
 
				+
			
 
				+Once this has been set up to match the current Defold project directory, it should be possible to see the directory tree of the Defold project in ZeroBrane, and to navigate and open the files.
			
 
				+
			
 
				+Other recommended, but not necessary configuration changes can be found further down in the document.
			
 
				+
			
 
				+## Starting the debugging server
			
 
				+
			
 
				+Before starting a debugging session, the ZeroBrane built-in debugging server needs to be started. The menu option for starting it can be found under the menu:Project menu. Just select menu:Project[Start Debugger Server]:
			
 
				+
			
 
				+![Auto completion](images/debugging/startdebug.png)
			
 
				+
			
 
				+## Connecting your application to the debugger
			
 
				+
			
 
				+Debugging can be started at any point in the lifetime of the Defold application, but needs to be actively initiated from Lua script. The Lua code to start a debugging session looks like this:
			
 
				+
			
 
				+```lua
			
 
				+local dbg = require "builtins.scripts.mobdebug"
			
 
				+dbg.start()
			
 
				+```
			
 
				+
			
 
				+By inserting the above code into the application, it will connect to ZeroBrane’s debugging server (through "localhost", by default) and pause at the next statement to be executed.
			
 
				+
			
 
				+::: sidenote
			
 
				+If your game exits when `dbg.start()` is called, it might be because ZeroBrane has detected a problem and sends the exit command to the game. For some reason, ZeroBrane needs a file opened to start the debug session, otherwise it will output:
			
 
				+"Can't start debugging without an opened file or with the current file not being saved ('untitled.lua')."
			
 
				+In ZeroBrane, open the file you added `dbg.start()` to fix this error.
			
 
				+:::
			
 
				+
			
 
				+::: sidenote
			
 
				+The debugging will only be enabled for the lua context from where debugging is initiated. Enabling "shared_state" in game.project means you can debug all your application no matter where you started.
			
 
				+:::
			
 
				+
			
 
				+Debugging session started in "<defold-dir>/branches/1610/1159/Main/".
			
 
				+
			
 
				+Now it it possible to use the debugging features available in ZeroBrane; you can step, inspect, add and remove breakpoints etc.
			
 
				+
			
 
				+![Auto completion](images/debugging/code.png)
			
 
				+
			
 
				+Should the connection attempt fail (possibly because the debugging server is not running), your application will continue to run as normal after the connection attempt has been made.
			
 
				+
			
 
				+## Remote debugging
			
 
				+
			
 
				+As debugging happens over regular network connections (TCP), this allows for debugging remotely. This means it is possible to debug your application while it is running on a mobile device.
			
 
				+
			
 
				+The only change needed is to the command which starts the debugging. By default, `start()` will try to connect to localhost, but for remote debugging, we need to manually specify the address to ZeroBrane’s debugging server, like this:
			
 
				+
			
 
				+```lua
			
 
				+local dbg = require "builtins.scripts.mobdebug"
			
 
				+dbg.start("192.168.5.101")
			
 
				+```
			
 
				+
			
 
				+This also means it is important to make sure to have network connectivity from the remote device, and that any firewalls or similar software allows TCP connections through on port 8172. Otherwise the application might stall when launching when it attempts to make the connection to your debugging server.
			
 
				+
			
 
				+## Other recommended ZeroBrane setting
			
 
				+
			
 
				+It is possible to make ZeroBrane automatically open Lua script files during debugging. This makes it possible to step into functions in other source files without having to open them manually.
			
 
				+
			
 
				+First step is to access the editor configuration file. Recommended is to change the user version of the file.
			
 
				+
			
 
				+- Select menu:Edit[Preferences > Settings: User]
			
 
				+- Add the following to the configuration file:
			
 
				++
			
 
				+----
			
 
				+– to automatically open files requested during debugging 
			
 
				+editor.autoactivate = true
			
 
				+----
			
 
				+- Restart ZeroBrane
			
 
				+
			
 
				+![Other recommended settings](images/debugging/otherrecommended.png)
			
 
				+
			
 
				+[[anchor-hr]]
			
 
				+## Hot reloading
			
 
				+
			
 
				+Defold allows you to perform hot reloading of resources. When developing a game this feature helps speed up certain task enormously. It allows you to change scripts in a game while it is running live. Common use-cases is to tweak gameplay parameters or to perform debugging on a running game.
			
 
				+
			
 
				+To reload a changed resource, simply select the menu item menu:Edit[Reload Resource] or press the corresponding shortcut on the keyboard:
			
 
				+
			
 
				+![Reloading resources](images/debugging/debugging_hot_reload.png)
			
 
				+
			
 
				+Every script component can define a `on_reload()` function. If it exists it will be called anytime a script is reloaded into the game from the editor:
			
 
				+
			
 
				+```lua
			
 
				+function on_reload(self)
			
 
				+    -- Print the current velocity
			
 
				+	print(self.velocity)
			
 
				+
			
 
				+    -- Zero the velocity
			
 
				+    self.velocity = vmath.vector3()
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+## Visual profiler
			
 
				+
			
 
				+The Defold engine is also able to display profiling information in a running game. This can be helpful when debugging or optimizing.
			
 
				+
			
 
				+```lua
			
 
				+function on_reload(self)
			
 
				+    -- Turn on profiler on hot reload.
			
 
				+	msg.post("@system:", "toggle_profile")
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+The profiler displays live information on the running application:
			
 
				+
			
 
				+![Visual profiler](images/debugging/debugging_profiling.png)
			
 
				+
			
 
				+## Web profiler
			
 
				+
			
 
				+While running the game, a web-based profiler can be accessed that provides detailed profiling information. It allows you to sample a series of data points and then analyze it in detail.
			
 
				+
			
 
				+To access the profiler:
			
 
				+
			
 
				+1. Start your game on your target device.
			
 
				+2. Open a web browser and point it to \http://<device IP>:8002 where <device IP> is the IP address of the device.
			
 
				+
			
 
				+If you are running your game on your desktop computer, _http://localhost:8002_ would bring up the profiler. You can find the IP numbers of your target devices in the menu:Project[Target] menu.
			
 
				+
			
 
				+![Web profiler](images/debugging/webprofiler_page.png)
			
 
				+
			
 
				+The profiler is divided into 4 sections that all give different views into the current sample data. To update the sample data, press the *Capture* button at the top.
			
 
				+
			
 
				+## Frames overview
			
 
				+
			
 
				+The frames overview plots the currently sampled 20 frames side by side. The height of each bar shows the time spent in the frame. The number on the left hand side shows the max time spent in a frame in the current sample data.
			
 
				+
			
 
				+![Frames overview](images/debugging/webprofiler_frames_overview.png)
			
 
				+
			
 
				+Below the frames overview is a detailed frame data view. You can click on any frame bar in the overview to show the data for that specific frame in the data view. The frame timechart at the bottom of the page also updates to show the clicked frame's data.
			
 
				+
			
 
				+## Frame data
			
 
				+
			
 
				+The frame data view is a table where all data for the currently selected frame is broken down into detail. You can view how many milliseconds is spent in each engine scope (to the left) and also see sample points within the scopes (middle column). On the right hand side is a table of counters. The numbers presented are counters so it is easy to, for instance, track the number of draw calls required for each frame in the sample data.
			
 
				+
			
 
				+![Frame data](images/debugging/webprofiler_frame_data.png)
			
 
				+
			
 
				+Ticking the checkbox associated with a sample point or counter adds that data to the plot below.
			
 
				+
			
 
				+## Frames plot
			
 
				+
			
 
				+The frames plot view displays a plot over all sampled frames using the data selected in the frame data table, frame number on the X axis and time in milliseconds on the Y axis. Each selected data point is drawn in the color specified in the frame data table.
			
 
				+
			
 
				+![Frames plot](images/debugging/webprofiler_frames_plot.png)
			
 
				+
			
 
				+## Frame time chart
			
 
				+
			
 
				+The frame time chart breaks the frame down visually making it is very easy to inspect where the engine spends its time during the selected frame.
			
 
				+
			
 
				+![Frame timechart](images/debugging/webprofiler_frame_timechart.png)
			
 
				+
			
 
				+(Some of the graphic assets used are made by Kenney: http://kenney.nl/assets)
			
--- a/docs/manuals/en/doctest.md
+++ b/docs/manuals/en/doctest.md
@@ -0,0 +1,211 @@
 
				+= Typography test
			
 
				+:source-highlighter: coderay
			
 
				+
			
 
				+This document is intended to test typography and styling of generated Asciidoc documents that are built against Defold Bootstrap 3 stylesheets.
			
 
				+
			
 
				+We begin by making sure we cover the usual typographic things like *stronger text*. There is also the thing with _slanted text that might be italic and nice_ but not always, depending on font.
			
 
				+
			
 
				+There is also the concept of em-dash that needs to be there--used quite a lot! Then sometimes there is a need to call out `go.function_word()` things and `variable` names.
			
 
				+
			
 
				+*_Bold italic text_* goes like this but who ever would want to use that? Also, we need to [be able to link to other documents](introduction). Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
			
 
				+
			
 
				+It is also convenient to be able to refer to command input and menu selections. For instance, to perform an action might require that you select "View > Zoom > Reset", or perhaps menu:File[Open Project], or menu:Meny[Item 1 > Sub 1 > Sub 2 > Sub 3] and then pressing <kbd>Option + C</kbd> or <kbd>SPACE</kbd> for that matter.
			
 
				+
			
 
				+[quote, Whoever said this thing, The book of many wisdoms]
			
 
				+____
			
 
				+Here comes a pretty long quotation rant from someone who believes himself (or herself) to be famous enough to warrant a quote in a document like this. Pretty poor sod if you ask me.
			
 
				+____
			
 
				+
			
 
				+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
			
 
				+
			
 
				+Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
			
 
				+
			
 
				+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
			
 
				+
			
 
				+## A second level headline
			
 
				+
			
 
				+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
			
 
				+
			
 
				+Define
			
 
				+: A term like this. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
			
 
				+
			
 
				+
			
 
				+Another term
			
 
				+: Second term just like this. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
			
 
				+
			
 
				+
			
 
				+Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
			
 
				+
			
 
				+## A second level headline that goes on for some time so it becomes long
			
 
				+
			
 
				+::: sidenote
			
 
				+Oh, I almost forgot to add one of those!
			
 
				+:::
			
 
				+
			
 
				+Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
			
 
				+
			
 
				+::: important
			
 
				+Oh, I almost forgot to add one of those!
			
 
				+:::
			
 
				+
			
 
				+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
			
 
				+
			
 
				+[WARNING]
			
 
				+:::
			
 
				+Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
			
 
				+* Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
			
 
				+* Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
			
 
				+* Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
			
 
				+:::
			
 
				+
			
 
				+## A third level headline that is a bit longer
			
 
				+
			
 
				+First a short paragraph, then a bullet list.
			
 
				+
			
 
				+* Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
			
 
				+* Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
			
 
				+* Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
			
 
				+* Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
			
 
				+** Sub bullets
			
 
				+** Another sub-bullet
			
 
				+** Let's do a third for good measure
			
 
				+* Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
			
 
				+* Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
			
 
				+* Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
			
 
				+
			
 
				+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
			
 
				+
			
 
				+- Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
			
 
				+- Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
			
 
				+.. Sublist entries should work here too.
			
 
				+.. Right? I think they are pretty useful.
			
 
				+.. If you agree, let's agree to agree.
			
 
				+- Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
			
 
				+- Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
			
 
				+
			
 
				+==== Fourth level headline that you should not really use
			
 
				+
			
 
				+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
			
 
				+
			
 
				+```lua
			
 
				+local pieces = { "ground0", "ground1", "ground2", "ground3",
			
 
				+                    "ground4", "ground5", "ground6" } <!--1-->
			
 
				+
			
 
				+function init(self) -- <2>
			
 
				+    self.speed = 6
			
 
				+end
			
 
				+
			
 
				+-- Here is a comment to test how they look
			
 
				+-- and a second line of text.
			
 
				+function update(self, dt) -- <3>
			
 
				+    for i, p in ipairs(pieces) do -- <4>
			
 
				+        local pos = go.get_position(p)
			
 
				+        if pos.x <> -228 then -- <5>
			
 
				+            pos.x = 1368 + (pos.x + 228)
			
 
				+        end
			
 
				+        pos.x = pos.x - self.speed
			
 
				+        go.set_position(pos, p)
			
 
				+    end
			
 
				+end
			
 
				+```
			
 
				+<1> Store the id:s of the ground game objects in a Lua table so we can iterate over them.
			
 
				+<2> The `init()` function is called when the game object comes to life in the game. We initiate a object local member variable that contains the speed of the ground.
			
 
				+<3> `update()` is called once each frame, typically 60 times per second.
			
 
				+<4> Iterate over all the ground game objects.
			
 
				+<5> Store the current position in a local variable, then if the current object is on the leftmost edge, move it to the rightmost edge.
			
 
				+
			
 
				+It is also very nice to be able to intruct people on command line input, like this:
			
 
				+
			
 
				+----
			
 
				+$ wget http://ftp.us.debian.org/debian/pool/main/o/openssl/libssl0.9.8_0.9.8o-4squeeze14_i386.deb  # <1>
			
 
				+$ sudo dpkg -i libssl0.9.8_0.9.8o-4squeeze14_i386.deb
			
 
				+----
			
 
				+<1> Some note here as well.
			
 
				+
			
 
				+## Let's do images
			
 
				+
			
 
				+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
			
 
				+
			
 
				+![A large image of sorts](images/doctest/large.png)
			
 
				+
			
 
				+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
			
 
				+
			
 
				+![A medium image of sorts](images/doctest/medium.png)
			
 
				+
			
 
				+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
			
 
				+
			
 
				+![A small image of sorts](images/doctest/small.png)
			
 
				+![A small image of sorts](images/doctest/small.png)
			
 
				+
			
 
				+## Table time!
			
 
				+
			
 
				+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
			
 
				+
			
 
				+|===
			
 
				+|Shortcut |Purpose
			
 
				+
			
 
				+|<kbd>F11</kbd>
			
 
				+|Toggle fullscreen
			
 
				+
			
 
				+|<kbd>Ctrl`T</kbd>
			
 
				+|Open a new tab
			
 
				+
			
 
				+Then another tab should be opened and switched to some magic state, I believe.
			
 
				+
			
 
				+|<kbd>Ctrl`Shift`N</kbd>
			
 
				+|New incognito window
			
 
				+
			
 
				+|<kbd>Ctrl ` `</kbd>
			
 
				+|Increase zoom
			
 
				+|===
			
 
				+
			
 
				+
			
 
				+[cols="2,6,2,2,2"]
			
 
				+|===
			
 
				+||Description|Type|go.get()|go.bananas()
			
 
				+
			
 
				+5`| *GAME OBJECT PROPERTIES*
			
 
				+
			
 
				+|*position*
			
 
				+|The local position of the game object.
			
 
				+|vector3
			
 
				+|yes
			
 
				+|yes
			
 
				+
			
 
				+|*rotation*
			
 
				+|The local rotation of the game object, expressed as a quartenion.
			
 
				+|quat
			
 
				+|yes
			
 
				+|yes
			
 
				+
			
 
				+|*euler*
			
 
				+|The local rotation of the game object, expressed as Euler angles in degrees.
			
 
				+|vector4
			
 
				+|yes
			
 
				+|yes
			
 
				+
			
 
				+|*scale*
			
 
				+|The local uniform scale of the game object, expressed as a multiplier. 1 is 100% (original) scale.
			
 
				+|number
			
 
				+|yes
			
 
				+|yes
			
 
				+
			
 
				+5`|&nbsp;
			
 
				+
			
 
				+5`|*SPRITE COMPONENT PROPERTIES*
			
 
				+
			
 
				+|*size*
			
 
				+|The non scaled size of the sprite--its size as taken from the source atlas.
			
 
				+|vector3
			
 
				+|yes
			
 
				+|no
			
 
				+
			
 
				+|*scale*
			
 
				+|Non uniform scaling of the sprite, expressed as a vector where each component contains a multiplier along each axis. To double the size in x and y, provide vmath.vector3(2.0, 2.0, 0)
			
 
				+|vector3
			
 
				+|yes
			
 
				+|yes
			
 
				+
			
 
				+|===
			
 
				+
			
 
				+
			
--- a/docs/manuals/en/extensions.md
+++ b/docs/manuals/en/extensions.md
@@ -0,0 +1,204 @@
 
				+Native extensions
			
 
				+=================
			
 
				+
			
 
				+If you need custom interaction with external software or hardware on a low level where Lua won't suffice, the Defold SDK allows you to write extensions to the engine in the C`+ language. Typical use cases for native extensions are:
			
 
				+
			
 
				+- Interaction with specific hardware, for instance the camera on mobile phones.
			
 
				+- Interaction with external low level API:s, for instance advertising network API:s that does not allow interaction through network API:s where Luasocket could be used.
			
 
				+- High performance calculations.
			
 
				+
			
 
				+## The build platform
			
 
				+
			
 
				+Defold provides a zero setup entry point to native extensions with a cloud based build solution. Any native extension that is developed and added to a game project becomes part of the ordinary project content. There is no need to build special versions of the engine and distribute to team members, that is handled automatically--any team member that builds and runs the project will get a project specific engine executable with all native extensions baked in.
			
 
				+
			
 
				+![Cloud build](images/extensions/cloud_build.png)
			
 
				+
			
 
				+## Project layout
			
 
				+
			
 
				+To create a new extension, create a folder in the project root. This folder will contain all settings, source code, libraries and resources associated with the extension. The extension builder recognizes the folder structure and collects any source files and libraries .
			
 
				+
			
 
				+![Project layout](images/extensions/layout.png)
			
 
				+
			
 
				+"ext.manifest"
			
 
				+: The extension folder _must_ contain an "ext.manifest" file. This file is a YAML format file that is picked up by the extension builder. A minimal manifest file should contain the name of the extension.
			
 
				+
			
 
				+
			
 
				+src
			
 
				+: This folder should contain all source code files.
			
 
				+
			
 
				+
			
 
				+include
			
 
				+: This optional folder contains any include files.
			
 
				+
			
 
				+
			
 
				+lib
			
 
				+: This optional folder contains any compiled libraries that the extension depends on. Library files should be placed in subfolders named by `platform`, or `architecure-platform`, depending on what architectures are supported by your libraries. Supported platforms are `ios`, `android+ and `osx`. Supported `arc-platform` pairs are `armv7-ios`, `arm64-ios`, `armv7-android` and `x86_64-osx`.
			
 
				+
			
 
				+
			
 
				+res
			
 
				+: This optional folder contains any extra resources that the extension depends on. Resource files should be placed in subfolders named by `platform`, or `architecure-platform` just as the "lib" subfolders. A subfolder `common` is also allowed, containing resource files common for all platforms.
			
 
				+
			
 
				+
			
 
				+## A simple example extension
			
 
				+
			
 
				+Let's build a very simple extension. First, we create a new root folder "myextension" and add a file "ext.manifest" containing the name of the extension:
			
 
				+
			
 
				+![Manifest](images/extensions/manifest.png)
			
 
				+
			
 
				+.ext.manifest
			
 
				+```yaml
			
 
				+name: "MyExtension"
			
 
				+```
			
 
				+
			
 
				+The extension consists of a single C`+ file, "myextension.cpp" that is created in the "src" folder.
			
 
				+
			
 
				+The Defold editor will not open `.cpp+ files by default so if you double click the file the system editor set for that file type is used. You can use the built in text editor by right-clicking the file and selecting "Open With > Text Editor". Note that Defold has no support for C`+ files so the editing experience is minimal.
			
 
				+
			
 
				+![C`+ file](images/extensions/cppfile.png)
			
 
				+
			
 
				+The extension source file contains the following code:
			
 
				+
			
 
				+.myextension.cpp
			
 
				+```cpp
			
 
				+// Extension lib defines
			
 
				+#define LIB_NAME "MyExtension"
			
 
				+#define MODULE_NAME "myextension"
			
 
				+
			
 
				+// include the Defold SDK
			
 
				+#include <dmsdk/sdk.h>
			
 
				+
			
 
				+static int Rot13(lua_State* L)
			
 
				+{
			
 
				+    int top = lua_gettop(L);
			
 
				+
			
 
				+    // Check and get parameter string from stack
			
 
				+    const char* str = luaL_checkstring(L, 1);
			
 
				+
			
 
				+    // Allocate new string
			
 
				+    int len = strlen(str);
			
 
				+    char *rot = (char *) malloc(len + 1);
			
 
				+
			
 
				+    // Iterate over the parameter string and create rot13 string
			
 
				+    for(int i = 0; i <= len; i`+) {
			
 
				+        const char c = str[i];
			
 
				+        if((c >= 'A' && c <= 'M') || (c >= 'a' && c <= 'm')) {
			
 
				+            // Between A-M just add 13 to the char.
			
 
				+            rot[i] = c ` 13;
			
 
				+        } else if((c >= 'N' && c <= 'Z') || (c >= 'n' && c <= 'z')) {
			
 
				+            // If rolling past 'Z' which happens below 'M', wrap back (subtract 13)
			
 
				+            rot[i] = c - 13;
			
 
				+        } else {
			
 
				+            // Leave character intact
			
 
				+            rot[i] = c;
			
 
				+        }
			
 
				+    }
			
 
				+
			
 
				+    // Put the rotated string on the stack
			
 
				+    lua_pushstring(L, rot);
			
 
				+
			
 
				+    // Free string memory. Lua has a copy by now.
			
 
				+    free(rot);
			
 
				+
			
 
				+    // Assert that there is one item on the stack.
			
 
				+    assert(top + 1 == lua_gettop(L));
			
 
				+
			
 
				+    // Return 1 item
			
 
				+    return 1;
			
 
				+}
			
 
				+
			
 
				+// Functions exposed to Lua
			
 
				+static const luaL_reg Module_methods[] =
			
 
				+{
			
 
				+    {"rot13", Rot13},
			
 
				+    {0, 0}
			
 
				+};
			
 
				+
			
 
				+static void LuaInit(lua_State* L)
			
 
				+{
			
 
				+    int top = lua_gettop(L);
			
 
				+
			
 
				+    // Register lua names
			
 
				+    luaL_register(L, MODULE_NAME, Module_methods);
			
 
				+
			
 
				+    lua_pop(L, 1);
			
 
				+    assert(top == lua_gettop(L));
			
 
				+}
			
 
				+
			
 
				+dmExtension::Result AppInitializeMyExtension(dmExtension::AppParams* params)
			
 
				+{
			
 
				+    return dmExtension::RESULT_OK;
			
 
				+}
			
 
				+
			
 
				+dmExtension::Result InitializeMyExtension(dmExtension::Params* params)
			
 
				+{
			
 
				+    // Init Lua
			
 
				+    LuaInit(params->m_L);
			
 
				+    printf("Registered %s Extension\n", MODULE_NAME);
			
 
				+    return dmExtension::RESULT_OK;
			
 
				+}
			
 
				+
			
 
				+dmExtension::Result AppFinalizeMyExtension(dmExtension::AppParams* params)
			
 
				+{
			
 
				+    return dmExtension::RESULT_OK;
			
 
				+}
			
 
				+
			
 
				+dmExtension::Result FinalizeMyExtension(dmExtension::Params* params)
			
 
				+{
			
 
				+    return dmExtension::RESULT_OK;
			
 
				+}
			
 
				+
			
 
				+
			
 
				+// Defold SDK uses a macro for setting up extension entry points:
			
 
				+//
			
 
				+// DM_DECLARE_EXTENSION(symbol, name, app_init, app_final, init, update, on_event, final)
			
 
				+
			
 
				+DM_DECLARE_EXTENSION(MyExtension, LIB_NAME, AppInitializeMyExtension, AppFinalizeMyExtension, InitializeMyExtension, 0, 0, FinalizeMyExtension)
			
 
				+```
			
 
				+
			
 
				+Note the macro `DM_DECLARE_EXTENSION` that is used to declare the various entry points into the extension code. For this simple example, there is no need for any "update" or "on_event" entry points, so +0+ is provided in those locations to the macro.
			
 
				+
			
 
				+Now it is just a matter of building the project ("Project > Build and Launch"). This will upload the extension to the extension builder which will produce a custom engine with the new extension included. If the builder encounters any errors, a dialog with the build errors will show.
			
 
				+
			
 
				+To test the extension, create a game object and add a script component with some test code:
			
 
				+
			
 
				+```lua
			
 
				+local s = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
			
 
				+local rot_s = myextension.rot13(s)
			
 
				+print(rot_s) --> nopqrstuvwxyzabcdefghijklmNOPQRSTUVWXYZABCDEFGHIJKLM
			
 
				+```
			
 
				+
			
 
				+And that's it! We have created a fully working native extension.
			
 
				+
			
 
				+## The ext.manifest file
			
 
				+
			
 
				+Apart from the name of the extension, the manifest file can contain platform specific compile flags, link flags, libs and frameworks. Here is an example:
			
 
				+
			
 
				+.ext.manifest
			
 
				+```yaml
			
 
				+name: "AdExtension"
			
 
				+
			
 
				+platforms:
			
 
				+    arm64-ios:
			
 
				+        context:
			
 
				+            frameworks: ["CoreGraphics", "CFNetwork", "GLKit", "CoreMotion", "MessageUI", "MediaPlayer", "StoreKit", "MobileCoreServices", "AdSupport", "AudioToolbox", "AVFoundation", "CoreGraphics", "CoreMedia", "CoreMotion", "CoreTelephony", "CoreVideo", "Foundation", "GLKit", "JavaScriptCore", "MediaPlayer", "MessageUI", "MobileCoreServices", "OpenGLES", "SafariServices", "StoreKit", "SystemConfiguration", "UIKit", "WebKit"]
			
 
				+            flags:      ["-stdlib=libc`+"]
			
 
				+            linkFlags:  ["-ObjC"]
			
 
				+            libs:       ["z", "c``", "sqlite3"]
			
 
				+
			
 
				+    armv7-ios:
			
 
				+        context:
			
 
				+            frameworks: ["CoreGraphics", "CFNetwork", "GLKit", "CoreMotion", "MessageUI", "MediaPlayer", "StoreKit", "MobileCoreServices", "AdSupport", "AudioToolbox", "AVFoundation", "CoreGraphics", "CoreMedia", "CoreMotion", "CoreTelephony", "CoreVideo", "Foundation", "GLKit", "JavaScriptCore", "MediaPlayer", "MessageUI", "MobileCoreServices", "OpenGLES", "SafariServices", "StoreKit", "SystemConfiguration", "UIKit", "WebKit"]
			
 
				+            flags:      ["-stdlib=libc``"]
			
 
				+            linkFlags:  ["-ObjC"]
			
 
				+            libs:       ["z", "c`+", "sqlite3"]
			
 
				+```
			
 
				+
			
 
				+## Known issues
			
 
				+
			
 
				+The native extension feature is in an alpha state, meaning that not all features are in place yet.
			
 
				+
			
 
				+- Platforms: We currently only support building extensions for: macOS, iOS and Android
			
 
				+- Android lacks support for .java and .jar archives
			
 
				+- Editor: The editor integration. There is no build process indication. Error reporting is rudimentary.
			
 
				+- Debugging: Currently, when building on iOS, the .dSYM files are not included in the build result
			
 
				+
			
--- a/docs/manuals/en/facebook.md
+++ b/docs/manuals/en/facebook.md
@@ -0,0 +1,161 @@
 
				+Facebook
			
 
				+========
			
 
				+
			
 
				+The Facebook APIs allows you to interact with Facebook's game connectivity features in a uniform way for games on iOS, Android and HTML5.
			
 
				+
			
 
				+The Defold Facebook APIs brings the various platform specific Facebook APIs under a unified set of functions that work the same on iOS, Android and HTML5 (through Facebook Canvas). To get started with Facebook connectivity in your games, you need a Facebook account.
			
 
				+
			
 
				+::: important
			
 
				+As of Defold 1.2.92, the Facebook API is redesigned with a new way of interacting with Facebook. The previous API:s still work so no breaking changes are introduced. However, the old API:s should be considered deprecated and not used in new applications.
			
 
				+:::
			
 
				+
			
 
				+## Registering as a Facebook developer
			
 
				+
			
 
				+To develop for Facebook requires that you sign up as a Facebook developer. This allows you to create Facebook applications that your Defold game can communicate with.
			
 
				+
			
 
				+* Head over to [Facebook for developers](https://developers.facebook.com)
			
 
				+* Log in with your Facebook account.
			
 
				+* Follow the instructions to register and verify your developer account.
			
 
				+
			
 
				+![Register as a developer](images/facebook/register_dev.png)
			
 
				+![ developer](images/facebook/register_verify.png)
			
 
				+
			
 
				+## Creating a Facebook app
			
 
				+
			
 
				+The next step is to create a Facebook application. The [menuseq]#My Apps# menu in the corner lists your apps, and there is a choice [menuseq]#Add a New App#.
			
 
				+
			
 
				+![Add new app](images/facebook/add_new_app_menu.png)
			
 
				+
			
 
				+You are presented with a selection of target platforms. Click *basic setup* to skip the wizards.
			
 
				+
			
 
				+::: sidenote
			
 
				+Most information provided through the wizards are irrelevant when developing on Defold. In particular, you usually don't need to edit "Info.plist" or "AndroidManifest.xml" yourself. Defold does that work for you.
			
 
				+:::
			
 
				+
			
 
				+![Add new app platform](images/facebook/add_new_app_platform.png)
			
 
				+
			
 
				+You can easily add, remove and change platform settings in the app dashboard. You are now asked to name your app and select *Display Name*, *Namespace* and *Category*. Again, these can all be edited in the app dashboard. When you have gone through this, Facebook creates an app with a unique app identifier for you. The *App ID* is not possible to change since it identifies this specific app.
			
 
				+
			
 
				+![New app id](images/facebook/new_app_id.png)
			
 
				+
			
 
				+![App dashboard settings](images/facebook/add_platform.png)
			
 
				+
			
 
				+Click the *Settings* tab. Notice the numerical *App ID*. That identifier needs to go into the [project settings](/manuals/project-settings) of your Defold game. Unfortunately this setting is hidden in the editor (this will change soon), but you easily add it. Right-click the "game.project" file in the *Project Explorer" and select "Open With > Text Editor".
			
 
				+
			
 
				+![Open project settings with](images/facebook/project_open_with.png)
			
 
				+
			
 
				+Add a section `[facebook]` and an entry `appid = 456788687846098` but with your application's *App ID*. Make sure you get the number right. Then save the file.
			
 
				+
			
 
				+![Game project](images/facebook/game_project.png)
			
 
				+
			
 
				+Now, back in the *Settings* tab on the Facebook app page, click *+ Add Platform* to add a new platform to the app. Each platform has a set of settings to fill in.
			
 
				+
			
 
				+![Select platform](images/facebook/select_platform.png)
			
 
				+
			
 
				+## iOS
			
 
				+
			
 
				+For iOS you need to specify the game's *bundle_identifier* as specified in "game.project".
			
 
				+
			
 
				+![iOS settings](images/facebook/settings_ios.png)
			
 
				+
			
 
				+## Android
			
 
				+
			
 
				+For Android you need to specify *Google Play Package Name*, which is the game's *package* identifier specified in "game.project". You should also generate hashes of the certificate(s) you use and enter them into the *Key Hashes* field. You can generate a hash from a "certificate.pem" with openssl:
			
 
				+
			
 
				+----
			
 
				+$ cat certificate.pem | openssl x509 -outform der | openssl sha1 -binary | openssl base64
			
 
				+----
			
 
				+
			
 
				+(See [Creating certificates and keys](/manuals/android/#_creating_certificates_and_keys) in the Android manual for details how to create your own signing files)
			
 
				+
			
 
				+![Android settings](images/facebook/settings_android.png)
			
 
				+
			
 
				+## Facebook Canvas
			
 
				+
			
 
				+For HTML5 games, the process is a bit different. Facebook needs access to your game content from somewhere. There are two options:
			
 
				+
			
 
				+![Facebook Canvas settings](images/facebook/settings_canvas.png)
			
 
				+
			
 
				+1. Use Facebook's *Simple Application Hosting*. Click *Yes* to select managed hosting. Select *uploaded assets* to open the hosted asset manager.
			
 
				++
			
 
				+![Simple hosting](images/facebook/simple_hosting.png)
			
 
				++
			
 
				+Select that you want to host a "HTML5 Bundle":
			
 
				++
			
 
				+![HTML5 bundle](images/facebook/html5_bundle.png)
			
 
				++
			
 
				+Compress your HTML5 bundle into a .7z or .zip archive and upload it to Facebook. Make sure to click *Push to production* to start serving the game.
			
 
				+
			
 
				+2. The alternative to Facebook hosting is to upload a HTML5 bundle of your game to some server of your choice that serves the game through HTTPS. Set the *Secure Canvas URL* to the URL of your game.
			
 
				+
			
 
				+The game now works through the Facebook URL provided as *Canvas Page*.
			
 
				+
			
 
				+## Testing the setup
			
 
				+
			
 
				+The following basic test can be used to see if things are set up properly.
			
 
				+
			
 
				+1. Create a new game object and attach a script component with a new script file to it.
			
 
				+2. Enter the following code in the script file:
			
 
				++
			
 
				+```lua
			
 
				+local function get_me_callback(self, id, response)
			
 
				+    -- The response table includes all the response data
			
 
				+    pprint(response)
			
 
				+end
			
 
				+
			
 
				+local function fb_login(self, data)
			
 
				+    if data.status == facebook.STATE_OPEN then
			
 
				+        -- Logged in ok. Let's try reading some "me" data through the
			
 
				+        -- HTTP graph API.
			
 
				+        local token = facebook.access_token()
			
 
				+        local url = "https://graph.facebook.com/me/?access_token=" .. token
			
 
				+        http.request(url, "GET", get_me_callback)
			
 
				+    elseif data.status == facebook.STATE_CLOSED_LOGIN_FAILED then
			
 
				+        -- Do something to indicate that login failed
			
 
				+    end
			
 
				+    if data.error then
			
 
				+        -- An error occurred
			
 
				+    else
			
 
				+        -- No error
			
 
				+    end
			
 
				+end
			
 
				+
			
 
				+function init(self)
			
 
				+    -- Log in with read permissions.
			
 
				+    local permissions = { "public_profile", "email" }
			
 
				+    facebook.login_with_read_permissions(permissions, fb_login)
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+Running this simple test should display something like the following in the console:
			
 
				+
			
 
				+----
			
 
				+DEBUG:SCRIPT: 
			
 
				+{
			
 
				+  status = 200,
			
 
				+  headers = {
			
 
				+    connection = keep-alive,
			
 
				+    date = Fri, 04 Nov 2016 13:54:33 GMT,
			
 
				+    etag = "0725a4f703fe6af27da183cfec0bb22637e331e0",
			
 
				+    access-control-allow-origin = *,
			
 
				+    content-length = 53,
			
 
				+    expires = Sat, 01 Jan 2000 00:00:00 GMT,
			
 
				+    content-type = text/javascript; charset=UTF-8,
			
 
				+    x-fb-debug = Pr1qUssb8Xa3x3r1t913hHMdefh69DSYYV5vcxeOB7O33mcfShIw+r7BoLpn147I2wzLF2CZRTpnR3/VYOtFpA==,
			
 
				+    facebook-api-version = v2.5,
			
 
				+    cache-control = private, no-cache, no-store, must-revalidate,
			
 
				+    pragma = no-cache,
			
 
				+    x-fb-trace-id = F03S5dtsdaS,
			
 
				+    x-fb-rev = 2664414,
			
 
				+  }
			
 
				+  response = {"name":"Max de Fold ","id":"14159265358979323"},
			
 
				+}
			
 
				+----
			
 
				+
			
 
				+* The full Defold Facebook APIs are documented in the [Facebook reference documentation](/ref/facebook).
			
 
				+* The Facebook Graph API is documented here: https://developers.facebook.com/docs/graph-api
			
 
				+
			
 
				+## Development caveats
			
 
				+
			
 
				+When developing it is very convenient to use the dev application. Unfortunately, the Facebook API does not yet work on the dev app due to how the bundled "Info.plist" file has to be constructed. However, any debug bundle works as a dev app so the workaround is to build the game with the proper Facebook project settings, put it on the device and then connect to the running game and stream data to it from the editor as usual.
			
 
				+
			
--- a/docs/manuals/en/factory.md
+++ b/docs/manuals/en/factory.md
@@ -0,0 +1,154 @@
 
				+Factory components
			
 
				+==================
			
 
				+
			
 
				+Factory components are used to dynamically spawn game objects from a pool of objects into the running game.
			
 
				+
			
 
				+When you add a factory component to a game object you specify in the *Prototype* property what game object file the factory should use as a blueprint for all new game objects it creates.
			
 
				+
			
 
				+![Factory component](images/factory/factory_component.png)
			
 
				+
			
 
				+![Factory component](images/factory/factory_collection.png)
			
 
				+
			
 
				+To trigger the creation of a game object, call `factory.create()`:
			
 
				+
			
 
				+.factory.script
			
 
				+```lua
			
 
				+local p = go.get_position()
			
 
				+p.y = vmath.lerp(math.random(), min_y, max_y)
			
 
				+local component = "#star_factory"
			
 
				+factory.create(component, p)
			
 
				+```
			
 
				+
			
 
				+![Spawned game object](images/factory/factory_spawned.png)
			
 
				+
			
 
				+`factory.create()` takes 5 parameters:
			
 
				+
			
 
				+url
			
 
				+: The id of the factory component that should spawn a new game object.
			
 
				+
			
 
				+[position]
			
 
				+: (optional) The world position of the new game object. This should be a `vector3`. If you do not specify a position, the game object is spawned at the position of the factory component.
			
 
				+
			
 
				+[rotation]
			
 
				+: (optional) The world rotation of the new game object. This should be a `quat`.
			
 
				+
			
 
				+[properties]
			
 
				+: (optiona) A Lua table with any script property values to initiate the game object with. See the [Script property manual](/manuals/script-properties) for information on script properties.
			
 
				+
			
 
				+[scale]
			
 
				+: (optional) The scale of the spawned game object. The scale can be expressed as a `number` (greater than 0) which specifies uniform scaling along all axis. You can also provide a `vector3` where each component specifies scaling along the corresponding axis.
			
 
				+
			
 
				+
			
 
				+For example:
			
 
				+
			
 
				+.factory.script
			
 
				+```lua
			
 
				+local p = go.get_position()
			
 
				+p.y = vmath.lerp(math.random(), min_y, max_y)
			
 
				+local component = "#star_factory"
			
 
				+-- Spawn with no rotation but double scale. Set the score of the star to 10.
			
 
				+factory.create(component, p, nil, { score = 10 }, 2.0) -- <1>
			
 
				+```
			
 
				+<1> Sets the "score" property of the star game object.
			
 
				+
			
 
				+.star.script
			
 
				+```lua
			
 
				+go.property("score", 1) -- <1>
			
 
				+
			
 
				+local speed = -240
			
 
				+
			
 
				+function update(self, dt)
			
 
				+    local p = go.get_position()
			
 
				+    p.x = p.x + speed * dt
			
 
				+    if p.x < -32 then
			
 
				+        go.delete()
			
 
				+    end
			
 
				+    go.set_position(p)
			
 
				+end
			
 
				+
			
 
				+function on_message(self, message_id, message, sender)
			
 
				+    if message_id == hash("collision_response") then
			
 
				+        msg.post("main#gui", "add_score", {amount = self.score}) -- <2>
			
 
				+        go.delete()
			
 
				+    end
			
 
				+end
			
 
				+```
			
 
				+<1> The "score" script property is defined with a default value.
			
 
				+<2> Reference the "score" script property as a value stored in "self".
			
 
				+
			
 
				+![Spawned game object with property and scaling](images/factory/factory_spawned2.png)
			
 
				+
			
 
				+::: sidenote
			
 
				+Defold does not currently support non uniform scaling of collision shapes. If you provide a non uniform scale value, for instance `vmath.vector3(1.0, 2.0, 1.0)` the sprite will scale correctly but the collision shapes won't
			
 
				+:::
			
 
				+
			
 
				+## Tracking spawned and parent objects
			
 
				+
			
 
				+When you call `factory.create()` you get back the id of the new game object, allowing you to store the id for future reference. One common use is to spawn objects and add their id:s to a table so you can delete them all at a later point, for instance when resetting a level layout:
			
 
				+
			
 
				+.spawner.script
			
 
				+```lua
			
 
				+self.spawned_coins = {}
			
 
				+
			
 
				+...
			
 
				+
			
 
				+-- Spawn a coin and store it in the "coins" table.
			
 
				+local id = factory.create("#coinfactory", coin_position)
			
 
				+table.insert(self.spawned_coins, id)
			
 
				+```
			
 
				+
			
 
				+And then later:
			
 
				+
			
 
				+.coin.script
			
 
				+```lua
			
 
				+-- Delete all spawned coins.
			
 
				+for _, coin_id = ipairs(self.spawned_coins) do
			
 
				+    go.delete(coin_id)
			
 
				+end
			
 
				+
			
 
				+-- or alternatively
			
 
				+go.delete_all(self.spawned_coins)
			
 
				+```
			
 
				+
			
 
				+It is also common that you want the spawned object to be aware of the game object that spawned it. One case would be a some type of autonomous object that can be spawned only one at a time. The spawned object then needs to inform the spawner when it is deleted or inactivated so another one can be spawned:
			
 
				+
			
 
				+.spawner.script
			
 
				+```lua
			
 
				+-- Spawn a drone and set its parent to the url of this script component
			
 
				+self.spawned_drone = factory.create("#dronefactory", drone_position, nil, { parent = msg.url() })
			
 
				+
			
 
				+...
			
 
				+
			
 
				+function on_message(self, message_id, message, sender)
			
 
				+    if message_id == hash("drone_dead") then
			
 
				+        self.spawed_drone = nil
			
 
				+    end
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+And the spawned object's logic:
			
 
				+
			
 
				+.drone.script
			
 
				+```lua
			
 
				+go.property("parent", msg.url())
			
 
				+
			
 
				+...
			
 
				+
			
 
				+function final(self)
			
 
				+    -- I'm dead.
			
 
				+    msg.post(self.parent, "drone_dead")
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+## Instance limits
			
 
				+
			
 
				+The project setting *max_instances* in *Collection related settings* limits the total number of game object instances that can exist in a world (the main.collection loaded at startup or any world loaded via a collection proxy). All game objects that exist in the world is counted agaist that limit and it does not matter if they are placed by hand in the editor or spawned in runtime through a script.
			
 
				+
			
 
				+![Max instances](images/factory/factory_max_instances.png)
			
 
				+
			
 
				+So if you set *max_instances* to 1024 and have 24 manually placed game objects in your main collection, you can spawn an additional 1000 game objects. And as soon as you delete a game object, you are free to spawn another instance.
			
 
				+
			
 
				+## Pooling of game objects
			
 
				+
			
 
				+It may seem like a good idea to save spawned game objects in a pool and reuse them. However, the engine is already doing object pooling under the hood so additional overhead will only slow things down. So delete game objects and spawn new ones, that is both faster and cleaner.
			
 
				+
			
--- a/docs/manuals/en/font.md
+++ b/docs/manuals/en/font.md
@@ -0,0 +1,139 @@
 
				+Font files
			
 
				+==========
			
 
				+
			
 
				+Fonts are used to render label components and text nodes in GUI scenes. This manual describes how Defold handles fonts and how to bring fonts onto the screen in your games.
			
 
				+
			
 
				+Font files in TrueType, OpenType or BMFont format can be added to your project and be automatically into a graphical format that Defold can render. Two font rendering techniques are available, bitmap and distance field, each with its specific benefits and drawbacks.
			
 
				+
			
 
				+## Creating a font
			
 
				+
			
 
				+To create a font for use in Defold, simply create a new Font file by selecting *File > New > Font File* (or right click in the *Project Explorer* and create the file).
			
 
				+
			
 
				+![Create font](images/font/fonts_create.png)
			
 
				+
			
 
				+You also need to import a font into your Defold project. Simply drag a TrueType or OpenType (or BMFont, see below) file into the *Project Explorer* and drop it in a good spot.
			
 
				+
			
 
				+::: sidenote
			
 
				+Shadow rendering of fonts is currently disabled by default because of performance reasons. It is fairly easy to write a custom shader that renders shadows (at some cost) if you need them. In the future, Defold will be able to select an appropriate shader based on used features.
			
 
				+:::
			
 
				+
			
 
				+*font*
			
 
				+: In the font editor, set this property to the imported TTF, OTF or *.fnt* file (you can click the *...* button to browse for the file). The editor will immediately create the font data and show a preview in the font editor.
			
 
				+
			
 
				+
			
 
				+*material*
			
 
				+: The material to use when rendering this font. Make sure to change this if you are creating a distance field font or a BMFont (see below for more on these).
			
 
				+
			
 
				+
			
 
				+*size*
			
 
				+: The target size of the glyphs in pixels.
			
 
				+
			
 
				+
			
 
				+*antialias*
			
 
				+: If the font should be antialiased when baked onto the target bitmap. Set to 0 if you want pixel perfect font rendering.
			
 
				+
			
 
				+
			
 
				+*alpha*
			
 
				+: The value of the alpha channel. 0.0--1.0 where 0.0 means transparent and 1.0 opaque.
			
 
				+
			
 
				+
			
 
				+*outline_alpha*
			
 
				+: The value of the alpha channel for the generated outline. 0.0--1.0.
			
 
				+
			
 
				+
			
 
				+*outline_width*
			
 
				+: The width of the generated outline in pixels. Set to 0 for no outline.
			
 
				+
			
 
				+
			
 
				+*shadow_alpha*
			
 
				+: The value of the alpha channel for the generated shadow. 0.0--1.0.
			
 
				+
			
 
				+
			
 
				+*shadow_blur*
			
 
				+: The blur radius in pixels for the generated shadow.
			
 
				+
			
 
				+
			
 
				+*shadow_x*
			
 
				+: The horizontal offset of the generated shadow.
			
 
				+
			
 
				+
			
 
				+*shadow_y*
			
 
				+: The vertical offset of the generated shadow.
			
 
				+
			
 
				+
			
 
				+*extra_characters*
			
 
				+: By default the font will include the ASCII printable characters (character codes 32-126). To manually include additional characters, list them in this property field.
			
 
				+
			
 
				+
			
 
				+*output_format*
			
 
				+: This property controls the type of font that is generated.
			
 
				+
			
 
				++
			
 
				+* `TYPE_BITMAP`. For OTF and TTF files, the imported font is converted into a font sheet texture where the bitmap data is used to render text nodes. The color channels are used to encode different aspects of the font, such as the face shape, outline and drop shadow. The preview shows the raw font texture with the font face in the red channel, the outline in the green channel and shadow in the blue channel. The pixel density of the font is fixed so it will look good in its generated size or scaled down. Bitmap fonts are very fast to render but size limited--scaling up a bitmap font quickly creates artifacts.
			
 
				+* `TYPE_DISTANCE_FIELD` The imported font is converted into a font sheet texture where the pixel data represent not screen pixels but distances to the font edge. See below for details.
			
 
				+
			
 
				+*all_chars*
			
 
				+: If you set this property to `true` all glyphs available in the source file are included in the output.
			
 
				+
			
 
				+
			
 
				+*cache_width*
			
 
				+: Set this to constrain the width of the glyph cache bitmap. When the engine renders text, it looks on the cache bitmap for a glyph. If it does not exist there it will be added to the cache before rendering. If the cache bitmap is too small to contain the glyphs the engine is asked to render, an error (`ERROR:RENDER: Out of available cache cells! Consider increasing cache_width or cache_height for the font.`) is signalled. If this value is 0 then the cache size is automatically.
			
 
				+
			
 
				+
			
 
				+*cache_height*
			
 
				+: Set this to constrain the height of the glyph cache bitmap. If this value is 0 then the cache size is automatically.
			
 
				+
			
 
				+
			
 
				+::: sidenote
			
 
				+The ASCII printable characters are:
			
 
				+space ! " # $ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ ` a b c d e f g h i j k l m n o p q r s t u v w x y z { | } ~
			
 
				+:::
			
 
				+
			
 
				+## Bitmap BMFonts
			
 
				+
			
 
				+In addition to generated bitmaps Defold supports prebaked bitmap "BMFont" format fonts. These fonts consists of a PNG font sheet with all the glyphs. In addition, a *.fnt* file contains information on where on the sheet each glyph can be found as well as size and kerning information.
			
 
				+
			
 
				+These types of fonts provide no performance improvement from bitmap fonts generated from TrueType or OpenType font files, but can include arbitrary graphics, coloring and shadows right in the image.
			
 
				+
			
 
				+Add the generated *.fnt* and *.png* files to your Defold project. These files should reside in the same folder. Create a new font file and set the *font* property to the *.fnt* file. Make sure that *output_format* is set to "TYPE_BITMAP". Defold will not generate a bitmap but use the one provided in the PNG.
			
 
				+
			
 
				+::: sidenote
			
 
				+To create a BMFont, you need to use a tool that can generate the appropriate files. Several options exist:
			
 
				+
			
 
				+* [Bitmap Font Generator](http://www.angelcode.com/products/bmfont/), a Windows only tool provided by AngelCode.
			
 
				+* [Shoebox](http://renderhjs.net/shoebox/), a free Adobe Air based app for Windows and MacOS.
			
 
				+* [Hiero](https://github.com/libgdx/libgdx/wiki/Hiero), an open source Java based tool.
			
 
				+* [Glyph Designer](https://71squared.com/glyphdesigner), a commercial MacOS tool from 71 Squared.
			
 
				+* [bmGlyph](https://www.bmglyph.com), a commercial MacOS tool from Sovapps.
			
 
				+:::
			
 
				+
			
 
				+![BMFont](images/font/fonts_bmfont.png)
			
 
				+
			
 
				+## Distance field fonts
			
 
				+
			
 
				+To create a distance field font, simply select "TYPE_DISTANCE_FIELD" as *output_format*. This creates a distance field map for the font. When the engine renders the font, a special shader is required to interprets the distance data and use that to create a sharp font edge. Distance field fonts are more resource intensive than bitmap fonts, but allow for much greater sizing flexibility.
			
 
				+
			
 
				+![Distance field font](images/font/fonts_distance_field.png)
			
 
				+
			
 
				+Make sure to change the *material* property of the font to "builtins/fonts/font-df.material" (or any other material that can handle the distance field data) when you create the font--or the font will not use the correct shader when it is rendered to screen.
			
 
				+
			
 
				+![Distance field font material](images/font/fonts_distance_field_material.png)
			
 
				+
			
 
				+## Artifacts and best practices
			
 
				+
			
 
				+Generally, bitmap fonts are best when the font is rendered with no scaling. They are faster to render to screen than distance field fonts.
			
 
				+
			
 
				+Distance field fonts respond very good to upscaling. Bitmap fonts, on the other hand, being just pixelated images will increase in size so the pixels will grow as the font is scaled, resulting in blocky artifacts. The following is a scaled sample at font size 48 pixels. The text has been scaled up roughly 8 times.
			
 
				+
			
 
				+![Font type comparison](images/font/fonts_comparison.png)
			
 
				+
			
 
				+When scaling down, the situation is the opposite. The pixel texture can be scaled down and be antialiased by the rendering hardware. The following is a zoom of the same sample font at size 48 pixels. The text has been scaled down to half the size:
			
 
				+
			
 
				+![Font type comparison, scale down](images/font/fonts_comparison_scaledown.png)
			
 
				+
			
 
				+Distance field fonts will produce other types of artifacts in certain situations. If the font glyphs contain very thin lines and you render the font at a small size (the *size* property), the resulting distance field texture is not dense enough to hold the data required to express critical points in the glyphs. Text may then render like this:
			
 
				+
			
 
				+![Thin line artifacts](images/font/fonts_thin_line_artifacts.png)
			
 
				+
			
 
				+To remedy the problem, create the font at a larger size.
			
 
				+
			
--- a/docs/manuals/en/gui-pie.md
+++ b/docs/manuals/en/gui-pie.md
@@ -0,0 +1,32 @@
 
				+Pie nodes
			
 
				+=========
			
 
				+
			
 
				+Pie nodes can be used to create circular or ellipsoid objects. In its simplest form, a pie node is simply a circle or ellipse inscribed in the node bounding box. If the width and height is identical, the circle's diameter will be that value. If the width and height differ, the node is instead an ellipse with the node width being the horizontal extent of the ellipse and the height being the vertical extent. The texture set for the node is applied straight, with the corners of the texture correlating to the corners of the node bounding box.
			
 
				+
			
 
				+![Pie node](images/gui/gui_pie_create.png)
			
 
				+
			
 
				+Pie nodes have a set of properties that makes it possible to use them to create a wide range of shapes. All of these properties can be changed programmatically (see [GUI API documentation](/ref/gui) for details) and some can be animated.
			
 
				+
			
 
				+![Pie properties](images/gui/gui_pie_properties.png)
			
 
				+
			
 
				+Inner radius
			
 
				+: The inner radius of the node, expressed along the X axis.
			
 
				+
			
 
				+Outer bounds
			
 
				+: Extend the node to the outer radius ("Ellipse") or to the node's bounding box ("Rectangle").
			
 
				+
			
 
				+Perimeter vertices
			
 
				+: The number of segments that will be used to build the shape, expressed as the number of vertices required to fully circumscribe the 360 degree perimeter of the node.
			
 
				+
			
 
				+Pie fill angle
			
 
				+: How much of the pie should be filled. Expressed as an counter-clockwise angle starting from the right.
			
 
				+
			
 
				+
			
 
				+![Radius and angle](images/gui/gui_pie_radius_angle.png)
			
 
				+
			
 
				+The *Outer bounds* extend the shape to the node bounding box. Together with an *Inner radius* and/or a *Pie fill angle*, some pretty complex shapes can be created.
			
 
				+
			
 
				+![Rectangle bounds](images/gui/gui_pie_rectangular.png)
			
 
				+
			
 
				+![Rectangle bounds and angle](images/gui/gui_pie_rectangular_angle.png)
			
 
				+
			
--- a/docs/manuals/en/gui-spine.md
+++ b/docs/manuals/en/gui-spine.md
@@ -0,0 +1,70 @@
 
				+GUI Spine nodes
			
 
				+===============
			
 
				+
			
 
				+Spine bone animations are available in GUI animations as well as in game objects. This manual explains how to use imported Spine animation data in GUI scenes.
			
 
				+
			
 
				+::: important
			
 
				+Currently, Spine nodes do not support Spine events. For game objects with *SpineModel* components that contain events on the animation timeline, messages are sent to the game object. This is not supported with Spine nodes.
			
 
				+:::
			
 
				+
			
 
				+Any imported Spine bone animation is available in GUI scenes as well as in game objects (through the *SpineModel* component). In order to work with Spine bone animations in Defold, you first have to import the animation data and set up a Spine Scene resource. The [Spine animation](/manuals/spine) documentation describes how to do that.
			
 
				+
			
 
				+To make the contents of a Spine Scene resource available in a GUI scene, add it to the scene by right-clicking the *Spine Scenes* section of the scene in the *Outline* and select menu:Add Spine Scene[]. Choose the Spine Scene you wish to use in the scene.
			
 
				+
			
 
				+![Add Spine Scene](images/gui/gui_spine_add_scene.png)
			
 
				+
			
 
				+![Added Spine Scene](images/gui/gui_spine_added_scene.png)
			
 
				+
			
 
				+Now, if you create a Spine node (right click in the *Nodes* section of the *Outline* and select menu:Add Spine Node[]) you are able to set the properties of the new Spine node accordingly:
			
 
				+
			
 
				+![Spine node](images/gui/gui_spine_node.png)
			
 
				+
			
 
				+Spine Scene
			
 
				+: The Spine Scene to use as a data source for this node.
			
 
				+
			
 
				+
			
 
				+Spine Default Animation
			
 
				+: The animation to automatically start playing when the scene is initialized.
			
 
				+
			
 
				+
			
 
				+Skin
			
 
				+: The skin to use for the animation when the scene is initialized.
			
 
				+
			
 
				+
			
 
				+## Runtime animation control
			
 
				+
			
 
				+Spine nodes can be controlled in runtime through script. To start an animation on a node, simply call the `[gui.play_spine()](/ref/gui#gui.play_spine)` function:
			
 
				+
			
 
				+```lua
			
 
				+local catnode = gui.get_node("cat_note")
			
 
				+local blend_time = 0.3
			
 
				+gui.play_spine(catnode, hash("run"), gui.PLAYBACK_ONCE_FORWARD, blend_time, function(self, node)
			
 
				+    print("Animation done!")
			
 
				+end)
			
 
				+```
			
 
				+
			
 
				+## The bone hierarchy
			
 
				+
			
 
				+The individual bones in the Spine skeleton exist as GUI nodes. The nodes are named according to their names in the Spine setup.
			
 
				+
			
 
				+![Spine bone names](images/gui/gui_spine_bones.png)
			
 
				+
			
 
				+To, for instance, attach another node to an existing bone node, fetch the bone node by name with the `[gui.get_spine_bone()](/ref/gui#gui.get_spine_bone)` and attach the child:
			
 
				+
			
 
				+```lua
			
 
				+-- Attach a text node to the tail of the cat
			
 
				+local cat = gui.get_node("cat_node")
			
 
				+local textnode = gui.new_text_node(vmath.vector3(400, 0, 0), "Hello tail!")
			
 
				+local tail = gui.get_spine_bone(cat, "tail")
			
 
				+gui.set_parent(textnode, tail)
			
 
				+```
			
 
				+
			
 
				+All bones are also accessible through `[go.get_node()](/ref/gui#gui.get_node)`, by the bone name prefixed by the name of the name of the Spine node and a slash "/":
			
 
				+
			
 
				+```lua
			
 
				+-- Attach a text node to the tail of the cat
			
 
				+local textnode = gui.new_text_node(vmath.vector3(400, 0, 0), "Hello tail!")
			
 
				+local tail = gui.get_node("cat_node/tail")
			
 
				+gui.set_parent(textnode, tail)
			
 
				+```
			
 
				+
			
--- a/docs/manuals/en/gui-templates.md
+++ b/docs/manuals/en/gui-templates.md
@@ -0,0 +1,46 @@
 
				+Templates
			
 
				+=========
			
 
				+:location: documentation manuals gui
			
 
				+:type: manual
			
 
				+
			
 
				+GUI templates provide a simple but powerful mechanism to create reusable visual GUI components based on shared templates or "prefabs". This manual explains the feature and how to use it.
			
 
				+
			
 
				+GUI templates are GUI scenes that are inserted into another GUI scene as a compound node, much like sub-collections can be placed inside other collections. But while a placed sub-collection can override the position of the sub-collection's root and any defined script-properties, a GUI template node can override any property values. Also, like sub-collections, GUI template nodes does not exist as a runtime concept, only as an editing tool.
			
 
				+
			
 
				+## Creating and using a template
			
 
				+
			
 
				+Since a GUI template is a plain GUI scene, there's nothing special about how they are created. Suppose we want to create and use a button template. We can then make a default button in a GUI scene and save it in a file:
			
 
				+
			
 
				+![Button template](images/gui-templates/gui-templates-button.png)
			
 
				+
			
 
				+Now we can add any number of instances of the button to another GUI scene. Create or open a new scene and select menu:Gui[Add Template Node], alternatively right-click *Nodes* in the *Outline* and select *Add Templat* from the drop-down.
			
 
				+
			
 
				+![Add template](images/gui-templates/gui-templates-add-template.png)
			
 
				+
			
 
				+Select the GUI scene file to use as template, in this case "button.gui". You can add any number of nodes, each an instance based on the same template. If we change the template, each instance updates immediately in the editor, reflecting the changes. Notice that all nodes present in the template node is accessible in the *Outline* view. Nodes under a template node are automatically named with a prefix "[template node id]/".
			
 
				+
			
 
				+![Node instances](images/gui-templates/gui-templates-instances.png)
			
 
				+
			
 
				+## Overloading properties
			
 
				+
			
 
				+Each instance node can overload any of the properties set in the template. Simply mark the node you wish to edit and change the property you want to alter. Nodes that has any overloaded properties are marked green in the *Outline* view. An overloaded property is marked blue. Click the blue property name to reset the property's value to the default.
			
 
				+
			
 
				+![Overloaded properties](images/gui-templates/gui-templates-overloaded.png)
			
 
				+
			
 
				+## Layers
			
 
				+
			
 
				+Layers behave as expected. Any property settings done to a particular layout in the template file is reflected in the layout of the instance nodes, given that the layer exists. Conversely, overloads to the template node instances affects the layer that is currently selected.
			
 
				+
			
 
				+![Overloading in layers](images/gui-templates/gui-templates-layers.png)
			
 
				+
			
 
				+## Scripting
			
 
				+
			
 
				+Writing Lua scripts to manipulate or query nodes added through the template node mechanism works exactly as usual. Just remember to address the nodes by their _full_ name, including the template node base prefix:
			
 
				+
			
 
				+```lua
			
 
				+if gui.pick_node(gui.get_node("button_ok/frame"), x, y) then
			
 
				+    -- Do something...
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+Note though that there is no template node present during runtime. All nodes under a template node are added to the game but the template node itself exists only in the editor. Also, if you add a script to the template GUI scene, the script will be ignored, only one script is tied to each GUI scene and is set on the scene root node in the *Outline* view as usual.
			
--- a/docs/manuals/en/gui-text.md
+++ b/docs/manuals/en/gui-text.md
@@ -0,0 +1,61 @@
 
				+GUI text nodes
			
 
				+==============
			
 
				+
			
 
				+Fonts are used to render text nodes in GUI scenes. This manual describes how to bring text into GUI scenes.
			
 
				+
			
 
				+## Adding text nodes
			
 
				+
			
 
				+The fonts that you wish to use in GUI text nodes must be added to the GUI component. Either right-click the *Fonts* folder, use the *GUI* top menu or press the corresponding keyboard shortcut.
			
 
				+
			
 
				+![Fonts](images/gui-text/fonts.png)
			
 
				+
			
 
				+Text nodes have a set of special properties:
			
 
				+
			
 
				+*Font*
			
 
				+: Any text node you create must have the *Font* property set.
			
 
				+
			
 
				+
			
 
				+*Text*
			
 
				+: This property contains the text displayed.
			
 
				+
			
 
				+
			
 
				+*Line Break*
			
 
				+: Text alignment follows the pivot setting and setting the this property allows the text to flow over several lines. The width of the node determines where the text will wrap.
			
 
				+
			
 
				+
			
 
				+## Alignment
			
 
				+
			
 
				+By setting the node pivot you can change the adjust mode for the text.
			
 
				+
			
 
				+*Center*
			
 
				+: If the pivot is set to "Center", "North" or "South", the text is center-aligned.
			
 
				+
			
 
				+*Left*
			
 
				+: If the pivot is set to any of the "West" modes, the text is left-aligned.
			
 
				+
			
 
				+*Right*
			
 
				+: If the pivot is set to any of the "East" modes, the text is right-aligned.
			
 
				+
			
 
				+
			
 
				+![Text alignment](images/gui-text/align.png)
			
 
				+
			
 
				+## Modifying text nodes in runtime
			
 
				+
			
 
				+Text nodes respond to any generic node manipulation functions for setting size, pivot, color and so forth. A few text node only functions exist:
			
 
				+
			
 
				+* To change the font of a text node, use the `[gui.set_font()](/ref/gui/#gui.set_font)` function.
			
 
				+* To change the line break behavior of a text node, use the `[gui.set_line_break()](/ref/gui/#gui.set_line_break)` function.
			
 
				+* To change the content of a text node, use the `[gui.set_text()](/ref/gui/#gui.set_text)` function.
			
 
				+
			
 
				+```lua
			
 
				+function on_message(self, message_id, message, sender)
			
 
				+    if message_id == hash("set_score") then
			
 
				+        local s = gui.get_node("score")
			
 
				+        gui.set_text(s, message.score)
			
 
				+    end
			
 
				+end
			
 
				+```
			
 
				+![Set text](images/gui-text/score_gui.png)
			
 
				+
			
 
				+![Set text](images/gui-text/score.png)
			
 
				+
			
--- a/docs/manuals/en/gui.md
+++ b/docs/manuals/en/gui.md
@@ -0,0 +1,437 @@
 
				+GUI
			
 
				+===
			
 
				+:location: documentation manuals gui
			
 
				+:type: manual
			
 
				+
			
 
				+Defold provides you with a custom GUI editor and powerful scripting possibilities that are tailor made for the construction and implementation of user interfaces. This manual goes through those features.
			
 
				+
			
 
				+A graphical user interface in Defold is a game object component that you build and attach to a game object and place in a collection. This component has the following properties:
			
 
				+
			
 
				+* It has simple, but powerful, layout features that allow resolution and aspect ratio independent rendering of your user interface.
			
 
				+* It can have logic behavior attached to it through a gui script.
			
 
				+* It is rendered in a separate pass from the rest of the game, on top of other content.
			
 
				+* It is rendered against a screen-space coordinate system that is independent of camera view so even if you have a moving camera, your GUI elements will stay put on the screen.
			
 
				+
			
 
				+The GUI is not part of the collection’s coordinate system but is rendered independently of the game view. Because of this it is not placed in a particular location in the collection editor, nor does it have a visual representation in the collection editor. However, the GUI component have to reside in a game object that has a location in a collection. Changing that location has no effect on the GUI.
			
 
				+
			
 
				+::: sidenote
			
 
				+The rendering behavior can be changed in the render script but it is usually desirable to use this arrangement since the user interface is a separate visual "layer" on top of the game view and you usually want HUD items and menus on certain spots on screen.
			
 
				+:::
			
 
				+
			
 
				+## Nodes
			
 
				+
			
 
				+A GUI component is built from a set of nodes. A node is a visual object that is either:
			
 
				+
			
 
				+* A Box node, a rectangle filled with a color or texture
			
 
				+* A Text node. See the [Text node documentation](/manuals/gui-text) for details
			
 
				+* A Pie node. See the [Pie node documentation](/manuals/gui-pie) for details
			
 
				+* A Template node. See the [Template node documentation](/manuals/gui-templates) for details
			
 
				+* A Spine node. See the [Spine node documentation](/manuals/gui-spine) for details
			
 
				+
			
 
				+Nodes are simple and don’t contain any logic. They can be translated (moved) and ordered in parent-child hierarchies either in the editor or at runtime through scripting. 
			
 
				+You have direct access to all nodes in your GUI component from the script code.
			
 
				+Nodes can be animated with script (see <<anchor-a, Property animation>> below) and animation can be run on nodes (flipbook animations on Box nodes and bone animations on Spine nodes).
			
 
				+
			
 
				+Add nodes by right-clicking on the "Nodes" folder and selecting either "Add Box", "Add Text", "Add Pie", "Add Template" or "Add Spine Node".
			
 
				+
			
 
				+![Add nodes](images/gui/gui_add_nodes.png)
			
 
				+
			
 
				+You can also use the GUI top menu, or the keyboard shortcuts ‘I’ and ‘O’ for box and text nodes.
			
 
				+Placed nodes are moved and rotated in the same way game objects are translated in the collection editor.
			
 
				+
			
 
				+## Node properties
			
 
				+
			
 
				+Each node has an extensive set of properties that control its appearance:
			
 
				+
			
 
				+* Position, Rotation, Scale, Size (can be animated)
			
 
				+* Color, Outline, Shadow (can be animated)
			
 
				+* Blend mode
			
 
				+* Adjust mode, Pivot, Xanchor, Yanchor
			
 
				+* Font, Text, Line-break (for text nodes)
			
 
				+* Index, Layer, Parent
			
 
				+* Clipping (for box and pie nodes) (See the [Clipping documentation](/manuals/clipping) for details)
			
 
				+
			
 
				+These properties can be modified in the editor's properties tab (except index and parenting), or through script (see [GUI API reference](/ref/gui)).
			
 
				+
			
 
				+Each of these properties can also be animated in script (see <<anchor-a, Property animation>> below).
			
 
				+
			
 
				+## Textures and flip book animations
			
 
				+
			
 
				+You can use images and animations from texture atlases or tile sources as part of your GUI interface component. To do so, an image resource (atlas or tile source) must first be added, then all images and animations included in the resource can be applied to GUI nodes. You add textures either by right clicking the "Textures" folder, through the "GUI" top menu, or with keyboard shortcuts.
			
 
				+
			
 
				+Textures that has been added to the GUI can be applied to box and pie nodes.
			
 
				+
			
 
				+![Textures](images/gui/gui_texture.png)
			
 
				+
			
 
				+The selected texture animation (or single frame image) will automatically play when the GUI component is drawn on screen.
			
 
				+
			
 
				+Note that the color of the box node will tint the animation. The tint color is multiplied onto the image data, meaning that if you set the color to white (the default) no tint is applied.
			
 
				+
			
 
				+![Tinted texture](images/gui/gui_tinted_texture.png)
			
 
				+
			
 
				+::: sidenote
			
 
				+Box nodes are always rendered, even if they do not have a texture assigned to them, got an alpha set to 0 or are sized 0, 0, 0. Box nodes should always have a texture assigned to the. If you need an empty node, set its size to 0, 0, 0 and make sure to assign a texture to it.
			
 
				+:::
			
 
				+
			
 
				+[[anchor-slice9]]
			
 
				+## Slice-9 texturing
			
 
				+
			
 
				+Many GUIs and HUDs feature elements that are context sensitive in regards to their size. Panels and dialogs often need to be resized to fit the containing content and that will cause problems as soon as you apply texturing to the scaled node. Let's say that you want to use a large set of buttons where the width is determined by the amount of text you write on the button. Making a box node, applying a texture and then scale it will result in deformation:
			
 
				+
			
 
				+![GUI bad scaling](images/gui/gui_scaling.png)
			
 
				+
			
 
				+Defold contains a feature called _slice-9_ texturing that is intended to be used in situations like this. It works by allowing you to preserve the size of parts of the node texture when the node is scaled. A button texture is divided into bits and applied to the node so that the end bits don't scale as you change the horizontal size of the button node:
			
 
				+
			
 
				+![Sliced scaling](images/gui/gui_slice9_scaling.png)
			
 
				+
			
 
				+You can thus make buttons of any width using this simple technique. The *Slice9* box node property is used to control how the texture is sliced:
			
 
				+
			
 
				+![Slice 9 properties](images/gui/gui_slice9_properties.png)
			
 
				+
			
 
				+The slicing is controlled by 4 numbers that specify the margin width, in pixels, which will be preserved as the node is resized. Corner segments are never scaled, only moved; edge segments are scaled along one axis, and the center segment is scaled both horizontally and vertically as needed. The margins are set clockwise, starting on the left hand side:
			
 
				+
			
 
				+![Slice 9 property sections](images/gui/gui_slice9_sections.png)
			
 
				+
			
 
				+Due to the way mipmapping works in the renderer, scaling of texture segments can sometimes look incorrect. This happens when you _scale down_ segments below the original texture size. The renderer then selects a lower resolution mipmap for the segment, resulting in visual artifacts.
			
 
				+
			
 
				+![Slice 9 mipmapping](images/gui/gui_slice9_mipmap.png)
			
 
				+
			
 
				+It is easy to avoid this problem, but it implies some constraints to the source texture: simply make sure that the texture's segments that will be scaled are small enough never to be scaled down, only up.
			
 
				+
			
 
				+::: sidenote
			
 
				+It might also be tempting to use a 1 pixel wide bottom or top edge segment to save texture memory. However, doing so might result in other unwanted artifacts, because of texture filtering. If you make the edge wider so that edge segments start and stop with similar neighbor pixels you will typically get nicer results.
			
 
				+:::
			
 
				+
			
 
				+## Index: rendering order
			
 
				+
			
 
				+All nodes are rendered in the order they are listed under the "Nodes" folder. The node on top of the list is drawn first and will appear behind any other node. The last node in the list is drawn last, meaning it will appear in front of all other nodes. Drag nodes in the list to change their index order.
			
 
				+
			
 
				+You can also change and group the ordering of nodes with layers (see below).
			
 
				+
			
 
				+If you set the Z-value on a node the draw order will not change. The Z-values on nodes are ignored.
			
 
				+
			
 
				+## Parent-child hierarchies
			
 
				+
			
 
				+A node is made the child of another node by dragging it onto the node that you wish to be the child's parent. A node with a parent inherits the transform (change in position, rotation and scale) applied to the parent and relative to the parent pivot (see below). Children are drawn after their parents, so they will appear in front of the parent node. Use layers to change the draw order of parent and child nodes and to optimize the rendering of nodes (see "Batch Rendering" below)
			
 
				+
			
 
				+## Layers
			
 
				+
			
 
				+Layers give fine grained control over how nodes are drawn. If you assign a layer to a node it will be drawn as part of that layer. The layer drawing order takes precedence over the regular node order.
			
 
				+
			
 
				+![Layers](images/gui/gui_layers.png)
			
 
				+
			
 
				+In this example the orange box node "box2" is part of layer "front" which is drawn last according to the layer order list. This means that all nodes that are part of "front" will be drawn on top of nodes that are part of layer "back" and nodes without layers set.
			
 
				+
			
 
				+Both "box1" and "box3" are set to layer "back". The drawing order within a layer is determined by the node’s index, it’s place in the node list. "box1" comes before "box3" and is thus drawn first, behind "box3".
			
 
				+
			
 
				+::: important
			
 
				+A child node with unset layer will implicitly inherit the layer setting of its parent node.
			
 
				+:::
			
 
				+Not setting a layer on a node implicitly adds it to the "null" layer, which is drawn before any other layer.
			
 
				+
			
 
				+## Batch rendering
			
 
				+
			
 
				+In order to render your GUI as efficiently as possible, there are steps that you can take that will permit the engine to organise drawing of your GUI nodes in batches, reducing the overall number of drawcalls that the engine must create. If groups of nodes meet the following conditions, then they may be handled within a single batch:
			
 
				+
			
 
				+- If they are all box nodes, they use the same atlas for textures.
			
 
				+- The nodes must be rendered with the same blend mode.
			
 
				+- If they are text nodes, they use same font.
			
 
				+- They must be rendered in sequence. That means that they must appear next to each other in the node list, or be part of the same layer (see the example below for details)
			
 
				+- In addition, clipping nodes always break the batch and each stencil scope also breaks the batch.
			
 
				+
			
 
				+The ability to arrange nodes in hierarchies is powerful and makes it easy to group complex hierarchies of nodes into manageable units. But hierarchies can effectively break batch rendering. Let’s look at a simple example:
			
 
				+
			
 
				+![Batch hierarchy](images/gui/gui_batch_hierarchy.png)
			
 
				+
			
 
				+Here we have built two buttons each out of three nodes. We have a box node with a shadow texture, a box node with a shaded button texture and a text node with the button text. We have put these nodes in logical manageable hierarchies. The button graphics is drawn with "alpha" blend mode and the shadow with "multiply" blend mode.
			
 
				+
			
 
				+When the rendering pipeline walks through the list of nodes, it is forced to set up a separate batch for each separate node. This is because walking through the list the nodes with graphics share the same atlas, but because the shadow nodes use different blend modes than the buttons, the batch is broken at each node. So, all in all these two buttons will require six separate batches.
			
 
				+
			
 
				+We can do better, though. By carefully assigning layers to our nodes, we can render our buttons much more efficiently. For this example we create three layers:
			
 
				+
			
 
				+   . Shadow
			
 
				+   . Button
			
 
				+   . Text
			
 
				+
			
 
				+We assign the nodes to the corresponding layer and make sure the layers are placed in correct render order in the Layers-list:
			
 
				+
			
 
				+![Batch layers](images/gui/gui_batch_layers.png)
			
 
				+
			
 
				+Since the layer drawing order takes precedence over the regular node order the nodes are now drawn in the following order:
			
 
				+
			
 
				+   . play_block_shadow
			
 
				+   . quit_block_shadow
			
 
				+   . play_block
			
 
				+   . quit_block
			
 
				+   . play
			
 
				+   . quit
			
 
				+
			
 
				+The nodes that share atlas, blend mode or font now sit adjacent to each other and the rendering pipeline can batch these nodes into three batches instead of six. A 50% performance win.
			
 
				+
			
 
				+Now, imagine that we scale our little example up and expand the GUI to 10 buttons. If we make sure to properly assign the right layer to each new nodes, the engine will still render them in three batches, but this time instead of 30.
			
 
				+
			
 
				+## Script
			
 
				+
			
 
				+To control the logic of your GUI and animate nodes you use Lua scripts. GUI scripts work the same as regular game object scripts, but are saved as a different file type and have access to a different set of functions: all in the "gui" module.
			
 
				+
			
 
				+You create a GUI Script File in your project and attach it to the GUI component by selecting the root GUI component in the outline view and then choosing a script file in the properties view.
			
 
				+
			
 
				+![Script](images/gui/gui_script.png)
			
 
				+
			
 
				+The script file is by default equipped with functions just as game object scripts:
			
 
				+
			
 
				+```lua
			
 
				+function init(self)
			
 
				+end
			
 
				+
			
 
				+function final(self)
			
 
				+end
			
 
				+
			
 
				+function update(self, dt)
			
 
				+end
			
 
				+
			
 
				+function on_message(self, message_id, message, sender)
			
 
				+end
			
 
				+
			
 
				+function on_input(self, action_id, action)
			
 
				+end
			
 
				+
			
 
				+function on_reload(self)
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+GUI components can thus receive input and messages just as game objects. You send messages to a GUI component by addressing the component in the fragment part of the URL:
			
 
				+
			
 
				+```lua
			
 
				+local msgdata = { score = 4711, stars = 3, health = 6 }
			
 
				+msg.post("hud#gui", "set_stats", msgdata)
			
 
				+```
			
 
				+
			
 
				+## Handling different resolutions and aspect ratios
			
 
				+
			
 
				+GUI components are rendered separately and on top of other game content and there are some mechanisms in place to make life easier for game developers that target device that have screens of different resolutions and aspect ratios.
			
 
				+
			
 
				+Your Defold game project specifies a target resolution in the "game project" settings, however one or more of your target devices might have a different screen resolution and aspect ratio. In this case this means that your game will be up- or downscaled to fit the target screen.
			
 
				+
			
 
				+Defold deals with the scaling of any GUI components differently to other game content. It also provides you with a set of simple, but powerful tools to lay out your user interface independently of resolution and/or aspect ratio.
			
 
				+
			
 
				+Let’s illustrate with a little experiment and create a game app with a GUI. The display size is set to a square with dimensions 1024x1024. The game contains a GUI component with a level menu on top of some imagery. This is how it looks when run on a computer:
			
 
				+
			
 
				+![Square](images/gui/gui_square.png)
			
 
				+
			
 
				+Now, if we run the same app on the iPad (with a very different screen size and aspect ratio of 4:3) we get the following result:
			
 
				+
			
 
				+![iPad square](images/gui/gui_ipad.png)
			
 
				+
			
 
				+We see that on the iPad the game is stretched out to fill the screen. The octopus in the background is deformed, but the GUI elements are not. The text nodes are rendered with the correct aspect ratio and keeps their location in the center of the screen.
			
 
				+
			
 
				+You can easily simulate changes to the screen resolution and aspect ratio by changing the window size of your running Defold game. Running the game on a device with a different resolution and aspect ratio is equivalent to changing the window. When the window changes size it triggers redrawing and re-positioning of GUI components, according to a set of adjustment and anchoring rules that give you good control over your user interface layout.
			
 
				+
			
 
				+## Adjust mode
			
 
				+
			
 
				+When the window is resized and the resolution and aspect ratio is changed, all nodes are reshaped and adjusted according to how their Adjust Mode property is set. This property can be either of the following three settings:
			
 
				+
			
 
				+   . Fit. This is the default. The node is uniformly scaled proportionally against what would be the resized node's bounding box width or height, whichever is smallest.
			
 
				+   . Zoom. The node is uniformly scaled proportionally against what would be the resized node's bounding box width or height, whichever is largest.
			
 
				+   . Stretch. The node is reshaped proportionally.
			
 
				+
			
 
				+It’s perhaps easiest to understand the adjust modes by looking at the following example that contains a GUI component with a couple of nodes:
			
 
				+
			
 
				+- A background box node that has a grid texture for reference. This node has *Adjust Mode* set to "Stretch".
			
 
				+- Three 256x256 pixel box nodes with a square Defold logo texture. One each with *Adjust Mode* "Fit", "Zoom" and "Stretch".
			
 
				+
			
 
				+![Adjust mode](images/gui/gui_adjust.png)
			
 
				+
			
 
				+Now let’s see what happens to the box nodes when the window is resized:
			
 
				+
			
 
				+![Resized window](images/gui/gui_adjust_resize.png)
			
 
				+
			
 
				+The "Stretch" node is just deformed to the new shape whereas the "Fit" and "Zoom" nodes keep their aspect ratio. The "Fit" node is fit inside the would-be reshaped bounding box (the grid square that it's in) and the "Zoom" node covers the would-be reshaped bounding box.
			
 
				+
			
 
				+Text nodes behave in exactly the same way. The adjust mode applies to the invisible text bounding box that controls the shape of the text.
			
 
				+
			
 
				+## Anchors
			
 
				+
			
 
				+Anchors control the behavior of a node’s position _inside the would-be reshaped bounding box_ when the window is resized. New nodes are created _anchorless_, meaning that they are positioned relative to the center of the screen.
			
 
				+
			
 
				+## Node repositioning without anchors
			
 
				+
			
 
				+The default behavior of a created node is the following
			
 
				+
			
 
				+   * The GUI component’s coordinate system is uniformly scaled and centered inside the resized window.
			
 
				+   * The node keeps its position in this scaled coordinate system.
			
 
				+
			
 
				+This means that all non-anchored nodes will keep their relative distance, in relation to the screen center. To illustrate, if the window gets wider, the added width (relatively) gets distributed equally on the sides of the GUI:
			
 
				+
			
 
				+![No anchor size up](images/gui/gui_no_anchor_sizeup.png)
			
 
				+
			
 
				+Similarly, if the window is shrunk and gets relatively narrower, the added height (relatively) is distributed equally above and below the GUI:
			
 
				+
			
 
				+![No anchor size down](images/gui/gui_no_anchor_sizedown.png)
			
 
				+
			
 
				+## Node repositioning with anchors
			
 
				+
			
 
				+By setting the Xanchor and/or the Yanchor properties you can lock the position of nodes relative to the edges of the _would-be reshaped bounding box_.
			
 
				+
			
 
				+   * Xanchor set to "Left" will lock the horizontal position of the node against the left edge of the box.
			
 
				+   * Xanchor set to "Right" will lock the horizontal position of the node against the right edge of the box.
			
 
				+   * Yanchor set to "Top" will lock the vertical position of the node against the top edge of the box.
			
 
				+   * Yanchor set to "Bottom" will lock the vertical position of the node against the bottom edge of the box.
			
 
				+
			
 
				+In practice this means that if you set the Xanchor property to "Right" and the Yanchor property to "Top", the node will keep its position relative to the top right corner of its reshaped box. The distance to the right edge and the top edge will be kept constant. However, the default *Pivot* is "Center" which keeps the center point. Often you want to anchor against an edge and then you should adjust the *Pivot* accordingly.
			
 
				+
			
 
				+![Anchor top right](images/gui/gui_anchor_topright.png)
			
 
				+
			
 
				+This example shows a node that has "Top" and "Right" anchoring. It is "Fit" adjusted and has *Pivot* set to "North East". When the window stretch, the node is fit inside the "would-be" reshaped box (the blue dotted rectangle) and also anchored.
			
 
				+
			
 
				+## Pivot
			
 
				+
			
 
				+Each node has a position, scale and rotation inside the GUI coordinate system. A node is placed on that position so that its pivot is at the set coordinate and any rotation is done around that same pivot. For text nodes the text will be aligned according to the pivot setting.
			
 
				+
			
 
				+The default positioning and rotation of nodes happen against the center of the node—it has the *Pivot* property set to "Center". You can change the pivot of a node to any of one of the following settings:
			
 
				+
			
 
				+* Center
			
 
				+* North, South, East, West
			
 
				+* North West, North East, South West, South East
			
 
				+
			
 
				+The following image illustrates the position of each pivot setting:
			
 
				+
			
 
				+![Pivot points](images/gui/pivot_points.png)
			
 
				+
			
 
				+If you change the pivot of a node, the node will be moved so that the new pivot will be at the given position. Text nodes are aligned so that "Center" sets the text center-aligned, "West" sets the text left-aligned and "East" sets the text right-aligned.
			
 
				+
			
 
				+## GUI scripts
			
 
				+
			
 
				+Since GUI nodes have no logic in themselves but are controlled by a GUI script attached to the GUI component, you have to get direct script control of the nodes. This is done by obtaining a node reference using the node’s id. The reference is usually stored in a variable and then used to manipulate the node:
			
 
				+
			
 
				+```lua
			
 
				+-- Obtain a reference to the "magic" text node
			
 
				+local magicnode = gui.get_node("magic")
			
 
				+-- Change the color of the node to orange
			
 
				+local orange = vmath.vector4(1.0, 0.3, 0.0, 1.0)
			
 
				+gui.set_color(magicnode, orange)
			
 
				+```
			
 
				+
			
 
				+As soon as you have obtained the reference to a node by the `gui.get_node()` function you can call any of the many manipulation functions in the GUI module to reposition, resize, change appearance of, reorder in draw-order, or move in the parent-child hierarchy. All node properties are accessible through scripting.
			
 
				+
			
 
				+## Node id:s
			
 
				+
			
 
				+Each node must have a unique id. If you create a box node, it will have a default id "box" and a text node has the id "text". You should change the id of each created node right away to a more descriptive, unique name. If the Defold GUI editor detects an id name collision, an error is signalled.
			
 
				+
			
 
				+## Dynamically created nodes
			
 
				+
			
 
				+To create a new node with script in runtime you have two options. You either create the node from scratch:
			
 
				+
			
 
				+```lua
			
 
				+-- Create a new, white box node at position 300, 300 with size 150x200
			
 
				+local new_position = vmath.vector3(300, 300, 0)
			
 
				+local new_size = vmath.vector3(150, 200, 0)
			
 
				+local new_boxnode = gui.new_box_node(new_position, new_size)
			
 
				+-- Add a text node at the same position
			
 
				+local new_textnode = gui.new_text_node(new_position, "Hello!")
			
 
				+```
			
 
				+
			
 
				+With the newly created nodes' references stored in variables you are now free to manipulate the nodes:
			
 
				+
			
 
				+```lua
			
 
				+-- Rotate the text node 10 degrees (around the z-axis)
			
 
				+gui.set_rotation(new_textnode, vmath.vector3(0, 0, 10))
			
 
				+```
			
 
				+
			
 
				+If we put this code in the GUI script’s init() function and run the game we get the following:
			
 
				+
			
 
				+![Script create node](images/gui/gui_script_create_nodes.png)
			
 
				+
			
 
				+The alternative way to create new nodes is to clone an existing node:
			
 
				+
			
 
				+```lua
			
 
				+-- Clone the magic text node
			
 
				+local magicnode = gui.get_node("magic")
			
 
				+local magic2 = gui.clone(magicnode)
			
 
				+-- The new node is right on top of the original. Let's move it.
			
 
				+gui.set_position(magic2, vmath.vector3(300, 300, 0))
			
 
				+```
			
 
				+
			
 
				+## Dynamic node IDs
			
 
				+
			
 
				+Dynamically created nodes do not have an id assigned to them. This is by design. The reference that is returned from `gui.new_box_node()`, `gui.new_text_node()`, `gui.new_pie_node()` and `gui.clone()` is the only thing necessary to be able to access the node and you should keep track of that reference.
			
 
				+
			
 
				+```lua
			
 
				+-- Add a text node
			
 
				+local new_textnode = gui.new_text_node(vmath.vector3(100, 100, 0), "Hello!")
			
 
				+-- "new_textnode" contains the reference to the node.
			
 
				+-- The node has no id, and that is fine. There's no reason why we want
			
 
				+-- to do gui.get_node() when we already have the reference.
			
 
				+```
			
 
				+
			
 
				+[[anchor-a]]
			
 
				+## Property animation
			
 
				+
			
 
				+Several of the node properties can be fully asynchronously animated. To animate a property, you use the `gui.animate()` function and supply the following parameters:
			
 
				+
			
 
				+----
			
 
				+gui.animate(node, property, to, easing, duration [,delay] [,complete_function] [,playback])
			
 
				+----
			
 
				+
			
 
				+::: sidenote
			
 
				+See [go.animate()](/ref/go#go.animate) for details on the parameters.
			
 
				+:::
			
 
				+
			
 
				+The "property" parameter is usually given as a constant (`gui.PROP_POSITION` etc), but can also be supplied as described in the Properties guide (see [Properties](/manuals/properties)). This is handy if you want to animate just a specific component of a compound property value.
			
 
				+
			
 
				+For instance, the "color" property describes a, RGBA value, encoded in a vector4 value with one component for each color component red, green and blue, and the last one for alpha. The vector components are named respectively "x", "y", "z" and "w" and the alpha is thus in the "w" component.
			
 
				+
			
 
				+To fade up and down the alpha value of a node we can do that with the following piece of code:
			
 
				+
			
 
				+```lua
			
 
				+function fadeup(self, node)
			
 
				+        gui.animate(node, "color.w", 1.0, gui.EASING_LINEAR,
			
 
				+0.3, 0, fadedown, gui.PLAYBACK_ONCE_FORWARD)
			
 
				+end
			
 
				+
			
 
				+function fadedown(self, node)
			
 
				+        gui.animate(node, "color.w", 0.0, gui.EASING_LINEAR,
			
 
				+0.3, 0, fadeup, gui.PLAYBACK_ONCE_FORWARD)
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+Now we can call either `fadeup()` or `fadedown()` and supply the node we want the alpha animated on. Note that we use the "complete_function" property to supply the function to call when the animation is done, effectively chaining an endless loop of fade up and fade downs.
			
 
				+
			
 
				+## Render script
			
 
				+
			
 
				+The default render script is a Lua script that handles all rendering of your game content (see [Rendering documentation](/manuals/rendering) for details). It is set up to render GUI nodes on top of the rest of a game in a separate pass:
			
 
				+
			
 
				+```lua
			
 
				+...
			
 
				+render.set_view(vmath.matrix4())
			
 
				+render.set_projection(vmath.matrix4_orthographic(0,
			
 
				+render.get_window_width(), 0,
			
 
				+render.get_window_height(), -1, 1))
			
 
				+render.draw(self.gui_pred)
			
 
				+render.draw(self.text_pred)
			
 
				+...
			
 
				+```
			
 
				+
			
 
				+The view is a normal identity matrix and the projection is orthographic. You can create custom render scripts for your project by copying the "default.render_script" and "default.render" render file from the "builtins/render" folder, changing them as you wish and then specifying your custom renderer under the "bootstrap" section of the project settings (see [Project settings](/manuals/project-settings)).
			
 
				+
			
 
				+To illustrate, you can render all GUI components with a 3D "camera" view and perspective projection:
			
 
				+
			
 
				+```lua
			
 
				+-- Set up a view to get a 3D positioned camera.
			
 
				+local w = render.get_window_width() * 0.5
			
 
				+local h = render.get_window_height() * 0.5
			
 
				+local view = vmath.matrix4_look_at(vmath.vector3(w-25, h-10, 70),
			
 
				+vmath.vector3(w, h, -250),
			
 
				+vmath.vector3(0, 1.0, 0))
			
 
				+render.set_view(view)
			
 
				+-- Perspective projection
			
 
				+render.set_projection(vmath.matrix4_perspective(2.5, 4/3, 0.1, 1000))
			
 
				+
			
 
				+render.draw(self.gui_pred)
			
 
				+render.draw(self.text_pred)
			
 
				+```
			
 
				+
			
 
				+This now affects all GUI components that are rendered. Here’s a version of our previous level menu with the modified render-script:
			
 
				+
			
 
				+![Render script](images/gui/gui_renderscript.png)
			
 
				+
			
--- a/docs/manuals/en/html5.md
+++ b/docs/manuals/en/html5.md
@@ -0,0 +1,284 @@
 
				+HTML5
			
 
				+=====
			
 
				+
			
 
				+This manual describes the process of creating HTML5 canvas applications, along with known issues and limitations.
			
 
				+
			
 
				+## Project configuration
			
 
				+
			
 
				+The "game.project" file has some settings specific to HTML5 targets: they may be found in the *html5* section:
			
 
				+
			
 
				+![Project settings](images/html5/html5_project_settings.png)
			
 
				+
			
 
				+## Customizing heap size
			
 
				+
			
 
				+Defold support for HTML5 is powered by Emscripten (See http://en.wikipedia.org/wiki/Emscripten). In short, it creates a sandbox of memory for the heap in which the application operates. By default, the engine allocates a generous amount of memory (256MB). This should be more than sufficient for the typical game. As part of your optimization process, you may choose to use a smaller value. To do this, follow these steps:
			
 
				+
			
 
				+1. Set *custom_heap_size* to a preferred value. It should be expressed in bytes.
			
 
				+2. Enable the override by checking *set_custom_heap_size*
			
 
				+3. Create your HTML5 bundle (see below)
			
 
				+
			
 
				+## Monitoring memory usage
			
 
				+
			
 
				+During development, you may track the use of application memory by creating bundles that include a special memory tracking component. This feature is enabled by checking *include_dev_tool*. For further details, see below.
			
 
				+
			
 
				+## Application cache
			
 
				+
			
 
				+You may opt to save application data within the _HTML5 application cache_ (See https://developer.mozilla.org/en-US/docs/Web/HTML/Using_the_application_cache), as it may improve loading times and reduce network traffic. Most commonly, this features is not used during development as the browser will prefer cached data over any new content you create. If you use the feature during testing, note that building a new bundle will alter the cache manifest, leading to new data being fetched. All browsers provide the means to clear this cache.
			
 
				+
			
 
				+## Creating HTML5 content
			
 
				+
			
 
				+Creating HTML5 content with Defold is simple and follows the same pattern as all other supported platforms: select *Project > Bundle > HTML5 Application...* from the menu:
			
 
				+
			
 
				+![Build HTML5](images/html5/html5_build_launch.png)
			
 
				+
			
 
				+You will be prompted to select a folder in which to create your application. After the export process completes, you will find all of the files needed to run the application.
			
 
				+
			
 
				+![Application files](images/html5/html5_files.png)
			
 
				+
			
 
				+## Testing HTML5 Content
			
 
				+
			
 
				+Install your content into a directory accessible to a web server. The testing environment available to you will depend upon your project: from this environment simply open the .html page of your application.
			
 
				+
			
 
				+![Application](images/html5/html5_goat.png)
			
 
				+
			
 
				+You may also launch HTML content directly from the editor, which opens the application in a local browser. Depending on the functionality of your game, you may prefer to test your application from a web server instead.
			
 
				+
			
 
				+## Known issues and limitations
			
 
				+
			
 
				+Live update
			
 
				+: Defold applications must run their own miniature web server in order to receive live updates from the editor. This is not possible within a pure browser application.
			
 
				+
			
 
				+
			
 
				+CORS
			
 
				+: Cross-origin resource sharing (See http://en.wikipedia.org/wiki/Cross-origin_resource_sharing) is not enabled in the QA environment, limiting the ability of browsers to interact with web APIs. There are two possible workarounds: when using Chrome, start it with the ‘--disable-web-security’ flag; you can create a proxy server.
			
 
				+
			
 
				+
			
 
				+Safari (IndexedDB)
			
 
				+: Persistent user data is stored locally using _IndexedDB API_ (see https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API). This HTML5 feature is not supported in the current version of Safari, so data will not be stored between sessions when using this browser. It will be included in the next update.
			
 
				+
			
 
				+
			
 
				+Internet Explorer 11 (audio)
			
 
				+: Defold handles audio playback using HTML5 _WebAudio_ (see http://www.w3.org/TR/webaudio), which is not currently supported by Internet Explorer 11. Applications will fall back to a null audio implementation when using this browser.
			
 
				+
			
 
				+
			
 
				+Internet Explorer 11 (WebGL)
			
 
				+: Microsoft has not completed work implementing the _WebGL_ API (see https://www.khronos.org/registry/webgl/specs/latest/). Therefore, it does not perform as well as other browsers.
			
 
				+
			
 
				+
			
 
				+Internet Explorer 11 (Full screen)
			
 
				+: Full screen mode is unreliable in the browser.
			
 
				+
			
 
				+
			
 
				+## Customizing HTML5 applications
			
 
				+
			
 
				+When generating an HTML5 version of your application, Defold provides a default web page that will house your application. It references style and script resources that dictate how your application is presented.
			
 
				+
			
 
				+In general, the time required to fetch all resources required to launch an application is not negligible. For this reason, Defold HTML5 applications implement a splash screen feature that is loaded separately from the main application and that will show while the main application loads.
			
 
				+
			
 
				+Unless overridden, Defold will produce a default page, consisting of:
			
 
				+
			
 
				+- An HTML5 canvas for your application
			
 
				+- A button to access fullscreen mode
			
 
				+- Splash screen content and logic
			
 
				+- Development tools, if required
			
 
				+
			
 
				+Each time the application is exported, this content is created afresh. If you wish to customize any of these elements you must make modifications to your project settings. To do so, open the *game.project* in the Defold editor and scroll to the *html5* section:
			
 
				+
			
 
				+![HTML5 settings](images/html5/html5_styling_settings.png)
			
 
				+
			
 
				+These settings allow you to add a custom HTML file, stylesheet and splash image.
			
 
				+
			
 
				+::: sidenote
			
 
				+To get started, you can begin by exporting the application once with the default settings. You then copy the exported HTML and CSS back into your project. Once copied, make the changes to the settings, as described above, and start editing the files.
			
 
				+:::
			
 
				+
			
 
				+You have considerable freedom to make changes or additions to this content, but some restrictions apply:
			
 
				+
			
 
				+- The canvas should not be styled with any border or padding. If you do, mouse input coordinates will be wrong.
			
 
				+- If Facebook support is required then the script tag that loads the Javascript SDK should appear before the main application script.
			
 
				+
			
 
				+## Splash screens
			
 
				+
			
 
				+By default, a splash screen is implemented. If you wish to customize or remove the splash screen then there are a few features that require attention:
			
 
				+
			
 
				+- HTML markup
			
 
				+- CSS styling
			
 
				+- Javascript logic
			
 
				+
			
 
				+Although the implementation of any associated Javascript is a matter of preference, Defold applications will send information back to you if you implement a "SplashControl" object that contains the following methods:
			
 
				+
			
 
				+onSetMessage(text)
			
 
				+: This callback receives text that is intended for display to the user.
			
 
				+
			
 
				+
			
 
				+onSetProgress(current, max)
			
 
				+: As the application is loaded, this callback receives the current progress. "current" contains the amount of data that has been loaded and "max" contains the total amount of data to load.
			
 
				+
			
 
				+
			
 
				+onDismissSplash()
			
 
				+: This callback is invoked by the application when the application is loaded and it is about to begin execution and render to the canvas (i.e. the splash screen should be dismisses).
			
 
				+
			
 
				+
			
 
				+The default implementation also contains logic to deal with window resizing events. If you wish to change or replace the implementation, the main module provides two helper functions:
			
 
				+
			
 
				+Module.matchToCanvas(id)
			
 
				+: Accepts the id of a DOM element and adjusts its styled "width" and "height" properties to match the proportions of the canvas. The "marginTop" property is set to a value that centers the canvas vertically in the browser window.
			
 
				+
			
 
				+
			
 
				+Module.setMarginTop(id, sourcePixels)
			
 
				+: Set the "marginTop" property of element "id" to a value "sourcePixels" that is expressed at a scale relative to the project settings application height. Internally, "sourcePixels" is multiplied by _scale_ before it's assigned to the top margin. The _scale_ is the actual browser window pixel height divided by the application pixel height as specified in the project settings.
			
 
				+
			
 
				+
			
 
				+::: important
			
 
				+These methods are not available until the module script is loaded. See the default generated HTML file for example usage.
			
 
				+:::
			
 
				+
			
 
				+::: sidenote
			
 
				+When focusing on splash screen development, you can comment out any code related to loading and running the engine to speed up the process.
			
 
				+:::
			
 
				+
			
 
				+## Tokens
			
 
				+
			
 
				+{% verbatim %}
			
 
				+When your HTML5 application is created, the HTML and CSS files are passed through a compiler that is capable of replacing certain tokens with values that depend upon your project settings. These tokens are always encased in either double or triple curly braces (`{{TOKEN}}` or `{{{TOKEN}}}`), depending on whether character sequences should be escaped or not. This feature can be useful if you either make frequent changes to your project settings or intend for material to be reused in other projects.
			
 
				+
			
 
				+Whether HTML or CSS content, the following tokens are all supported:
			
 
				+
			
 
				+DEFOLD_DISPLAY_WIDTH
			
 
				+: (HTML or CSS) Writes the value specified in your project settings for display width.
			
 
				+
			
 
				+
			
 
				+```javascript
			
 
				+function doSomething() {
			
 
				+    var x = {{DEFOLD_DISPLAY_WIDTH}};
			
 
				+    // ...
			
 
				+}
			
 
				+```
			
 
				+
			
 
				+DEFOLD_DISPLAY_HEIGHT
			
 
				+: (HTML or CSS) Writes the value specified in your project settings for display height.
			
 
				+
			
 
				+
			
 
				+```javascript
			
 
				+function doSomething() {
			
 
				+    var y = {{DEFOLD_DISPLAY_HEIGHT}};
			
 
				+}
			
 
				+```
			
 
				+
			
 
				+DEFOLD_SPLASH_IMAGE
			
 
				+: (HTML or CSS) Writes the filename of the splash image file.
			
 
				+
			
 
				+
			
 
				+```html
			
 
				+<image class="splashImage" src="{{DEFOLD_SPLASH_IMAGE}}"></image>
			
 
				+```
			
 
				+
			
 
				+The following tokens are only supported when processing HTML files:
			
 
				+
			
 
				+DEFOLD_APP_TITLE
			
 
				+: (HTML) Generates a string based on your project’s title.
			
 
				+
			
 
				+
			
 
				+```html
			
 
				+<head>
			
 
				+    <title>{{DEFOLD_APP_TITLE}}</title>
			
 
				+</head>
			
 
				+```
			
 
				+
			
 
				+DEFOLD_JS
			
 
				+: (HTML) Corresponds to the name of the main application javascript file.
			
 
				+
			
 
				+
			
 
				+DEFOLD_MODULE_JS
			
 
				+: (HTML) Corresponds to the name of the bootstrap javascript file. It is this file that loads the application assets and coordinates the activity of the splash screen.
			
 
				+
			
 
				+
			
 
				+```html
			
 
				+<script type='text/javascript' src="{{DEFOLD_MODULE_JS}}"></script>
			
 
				+```
			
 
				+
			
 
				+DEFOLD_CSS
			
 
				+: (HTML) This is the filename of the CSS file that is output during export, either using the default or the template specified in your project settings.
			
 
				+
			
 
				+
			
 
				+```html
			
 
				+<head>
			
 
				+    <link rel="stylesheet" type="text/css" href="{{DEFOLD_CSS}}"></style>
			
 
				+</head>
			
 
				+```
			
 
				+
			
 
				+DEFOLD_DEV_HEAD
			
 
				+: (HTML) Creates a custom HTML fragment, used in the `<head>` section of your HTML document, content depending upon your project settings. Note the use of triple braces, as it is important that this character sequence should not be escaped.
			
 
				+
			
 
				+
			
 
				+```html
			
 
				+<head>
			
 
				+    {{{DEFOLD_DEV_HEAD}}}
			
 
				+</head>
			
 
				+```
			
 
				+
			
 
				+DEFOLD_DEV_INLINE
			
 
				+: (HTML) Creates a custom HTML fragment, used in the `<body>` section of your HTML document, content depending upon your project settings.
			
 
				+
			
 
				+
			
 
				+```html
			
 
				+{{{DEFOLD_DEV_INLINE}}}
			
 
				+<script type="text/javascript" src="//connect.facebook.net/en_US/sdk.js"></script>
			
 
				+<!-- etc. -->
			
 
				+```
			
 
				+
			
 
				+::: important
			
 
				+It is important that this inline block appear before the main application script is loaded. Since it includes HTML tags, this macro should appear in triple braces to prevent character sequences being escaped.
			
 
				+:::
			
 
				+
			
 
				+DEFOLD_JS_INIT
			
 
				+: (HTML) This tag, once processed, adds code to load the Defold application. Should development options also be enabled, it also performs initialization of any associated modules.
			
 
				+
			
 
				+
			
 
				+```html
			
 
				+{{{DEFOLD_DEV_INLINE}}}
			
 
				+<script type="text/javascript" src="//connect.facebook.net/en_US/sdk.js"></script>
			
 
				+{{DEFOLD_JS_INIT}}
			
 
				+```
			
 
				+
			
 
				+::: important
			
 
				+If you wish to use the Facebook SDK then the tag to load this should appear before the `{{{DEFOLD_JS_INIT}}}` tag. This macro should also be enclosed in triple braces, as it too contains HTML tags and should not be escaped.
			
 
				+:::
			
 
				+
			
 
				+{% endverbatim %}
			
 
				+
			
 
				+## HTML5 Memory Tracker
			
 
				+
			
 
				+In development, HTML5 bundles can be created that include a simple memory tracking tool. To include it in your application, open your "game.project" file and scroll to the *html5* section.
			
 
				+
			
 
				+![Include devtool](images/html5/html5_devtool_include.png)
			
 
				+
			
 
				+By enabling the *include_dev_tool* option, the bundling process will automatically include and enabled this tool. *Remember to cancel this option before creating release candidates!*
			
 
				+
			
 
				+## Tool features
			
 
				+
			
 
				+Launch your application in a browser as normal, and the tool will appear on screen.
			
 
				+
			
 
				+![Devtool example](images/html5/html5_devtool_goatgold.png)
			
 
				+
			
 
				+You may enable or disable the various sections of memory reporting by pressing the toggle switches. The sections contain the following information:
			
 
				+
			
 
				+Heap
			
 
				+: The overall size of the heap memory. This may be configured by setting a custom heap size. Tuning this value will be useful when creating a release that makes optimum use of resources.
			
 
				+
			
 
				+Dynamic
			
 
				+: Measures the current and peak levels of dynamic memory allocation, alongside overall counts of allocation and free operations being performed by the application.
			
 
				+
			
 
				+Static
			
 
				+: Summarizes memory allocated for statically included data, built directly into the application.
			
 
				+
			
 
				+Stack
			
 
				+: Monitors the overall amount of memory allocated to the code for stack use. You should expect the used value to consistently report zero during normal operation, other values may indicate a bug in the engine.
			
 
				+
			
 
				+
			
 
				+It is most likely that the first two sections will be most relevant during development. In particular, best performing applications will not make frequent requests to dynamically allocate memory.
			
 
				+
			
 
				+## Known limitations
			
 
				+
			
 
				+The memory tracking tool works by patching the functions `malloc()` and `free()`, and doing so at the earliest possible moment. This patch is not performed before methods are declared to global constructors, meaning that dynamic allocations made during this early phase of the application will not be tracked in the usage or peak data. Values relating to the dynamic memory area and locations will, however, be accurate.
			
 
				+
			
--- a/docs/manuals/en/iap.md
+++ b/docs/manuals/en/iap.md
@@ -0,0 +1,190 @@
 
				+In-app purchases
			
 
				+================
			
 
				+:location: documentation manuals extensions
			
 
				+:type: manual
			
 
				+
			
 
				+In-app purchases (or in-app billing) allows you to charge your players or app users for extra content or functionality. This manual explains Defold's API available for this functionality.
			
 
				+
			
 
				+Defold provides a unified, simple to use interface to Apple's iOS Appstore "in-app purchases" and Google Play's or Amazon's "in-app billing" on Android devices. Facebook Canvas "game payments" is supported for Facebook Canvas. These services gives you the opportunity to sell products as:
			
 
				+
			
 
				+* Standard in-app products (one time billing) of consumables or non-consumables and
			
 
				+* Subscriptions (recurring, automated billing)
			
 
				+
			
 
				+::: important
			
 
				+The current Defold interface allows full interaction with Apple's Storekit functionality. For Google Play and Facebook Canvas, the interface is identical, meaning that you can run the same code on either platform. However, some process flow might differ from platform to platform. Also note that there is currently no support for OS X purchases through Mac Appstore.
			
 
				+:::
			
 
				+
			
 
				+Detailed documentation from Apple, Google, Amazon and Facebook can be found here:
			
 
				+
			
 
				+* [In-App Purchase Programming Guide](https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/StoreKitGuide/Introduction.html).
			
 
				+* [Google Play In-app Billing documentation](http://developer.android.com/google/play/billing/index.html).
			
 
				+* [Amazon In-app Purchase documentation](https://developer.amazon.com/public/apis/earn/in-app-purchasing).
			
 
				+* [Facebook game payments documentation](https://developers.facebook.com/docs/payments).
			
 
				+
			
 
				+## Testing Google Play Billing with static responses
			
 
				+
			
 
				+On Android it is recommended that you start implementing IAP in your app by using static responses from Google Play. This enables you to verify that everything in your app works correctly before you publish the app. Four reserved product IDs exist for testing static In-app Billing responses:
			
 
				+
			
 
				+android.test.purchased
			
 
				+: Google Play responds as though you successfully purchased an item. The response includes a JSON string, which contains fake purchase information (for example, a fake order ID).
			
 
				+
			
 
				+android.test.canceled
			
 
				+: Google Play responds as though the purchase was canceled. This can occur when an error is encountered in the order process, such as an invalid credit card, or when you cancel a user's order before it is charged.
			
 
				+
			
 
				+android.test.refunded
			
 
				+: Google Play responds as though the purchase was refunded.
			
 
				+
			
 
				+android.test.item_unavailable
			
 
				+: Google Play responds as though the item being purchased was not listed in your application's product list.
			
 
				+
			
 
				+
			
 
				+## Setting up your app for purchases/billing
			
 
				+
			
 
				+The procedure on iOS and Android is similar:
			
 
				+
			
 
				+1. Make sure you are a registered Apple or Google Play developer.
			
 
				+2. Set up your project so it works on your target device. See the [iOS development](/manuals/ios) and [Android development](/manuals/android) guides.
			
 
				+3. Set up the app for testing:
			
 
				+    * For Android, this is done on the [Google Play Developer Console](https://play.google.com/apps/publish/).
			
 
				+    * For iOS, this is done on [iTunes Connect](https://itunesconnect.apple.com/). Make sure that your App ID (created in the "Member Center" on https://developer.apple.com) has "In-App Purchase" enabled.
			
 
				++
			
 
				+![iTunes Connect and Google Play Dev Console](images/iap/itunes_connect_google_play.png)
			
 
				++
			
 
				+4. For Google Play, you need to _upload and publish_ an alpha *.apk* file. For iTunes Connect, you should _not upload_ the development binary to iTunes Connect until the application is ready for App Review approval. If you upload a not binary to iTunes Connect and it is not fully functional, Apple will likely reject it.
			
 
				+5. Create products for your app.
			
 
				++
			
 
				+![iTunes Products](images/iap/itunes_products.png)
			
 
				++
			
 
				+![Google Play Products](images/iap/google_play_products.png)
			
 
				++
			
 
				+6. Add test users.
			
 
				+    * The iTunes Connect page *Users and Roles* allow you to add users that can do test purchases in the _sandbox environment_. You should sign your app with a Developer certificate and use the sandbox account in Appstore on the test device.
			
 
				+    * On Google Play Developer Console, choose *Settings > Account Details* where you can add user emails to the License Testing section. Separate the emails by commas. This allows your testers to use test purchases that don’t actually cost real money.
			
 
				+    * On Google Play, you also need to set up a Google Group for your testers. Google uses Groups to manage testers that can download your app from the Alpha and Beta stores. Click on the *Alpha Testing* tab and then *Manage list of testers* to add your Google Group as Alpha testers. The app must have passed through alpha publishing before you can see the opt-in link.
			
 
				+
			
 
				+![Alpha testers](images/iap/alpha_testers.png)
			
 
				+
			
 
				+The procedure on Facebook:
			
 
				+
			
 
				+1. Make sure you are a registered Facebook developer. Go to [Facebook for developers](https://developers.facebook.com/), "My Apps" and "Register as a developer", follow the steps.
			
 
				+2. Facebook has extensive payment functionality and requires support of both synchronous and asynchronous payments. More info here [Payment overview](https://developers.facebook.com/docs/payments/overview)
			
 
				+3. Set up app hosting and callback server:
			
 
				+    * You will need to set up a secure canvas URL hosting your project. How this works is explained here [Games on Facebook](https://developers.facebook.com/docs/games/gamesonfacebook/hosting).
			
 
				+    * The next step is to set up your callback server. Follow the steps here [Setting up your callback server](https://developers.facebook.com/docs/payments/realtimeupdates#yourcallbackserver).
			
 
				+4. Set up you canvas app. Follow the steps on [Facebook Developer Dashboard](https://developers.facebook.com/quickstarts/?platform=canvas).
			
 
				+5. Add test users. This is done in the "Canvas Payments" section of the app dashboard.
			
 
				+6. Create products for your app [Defining products](https://developers.facebook.com/docs/payments/implementation-guide/defining-products/).
			
 
				+
			
 
				+
			
 
				+## Asynchronous transactions
			
 
				+
			
 
				+The IAP API is asynchronous, meaning that after each request that your program sends to the server, the program will not halt and wait for a response. Instead, the program continues as ordinary and when the response arrives, a _callback_ function is invoked where you can react to the response data.
			
 
				+
			
 
				+To fetch all product information available:
			
 
				+
			
 
				+```lua
			
 
				+local COINS_ID = "com.defold.examples.coins"
			
 
				+local LOGO_ID = "com.defold.examples.logo"
			
 
				+
			
 
				+local function product_list(self, products, error)
			
 
				+	if error == nil then
			
 
				+		for i,p in pairs(products) do
			
 
				+			print(p.ident)
			
 
				+			print(p.title)
			
 
				+			print(p.description)
			
 
				+			print(p.currency_code)
			
 
				+			print(p.price_string)
			
 
				+		end
			
 
				+	else
			
 
				+		print(error.error)
			
 
				+	end
			
 
				+end
			
 
				+
			
 
				+function init(self)
			
 
				+	-- Initiate a fetch of products
			
 
				+	iap.list({ COINS_ID, LOGO_ID }, product_list)
			
 
				+end
			
 
				+```
			
 
				+
			
 
				+To perform actual transactions, first register a function that will listen to transaction results, then call the store function at the appropriate time:
			
 
				+
			
 
				+```lua
			
 
				+    local function iap_listener(self, transaction, error)
			
 
				+	    if error == nil then
			
 
				+            if transaction.state == iap.TRANS_STATE_PURCHASING then
			
 
				+                print("Purchasing...")
			
 
				+            elseif transaction.state == iap.TRANS_STATE_PURCHASED then
			
 
				+                print("Purchased!")
			
 
				+            elseif transaction.state == iap.TRANS_STATE_UNVERIFIED then
			
 
				+                print("Unverified!")
			
 
				+            elseif transaction.state == iap.TRANS_STATE_FAILED then
			
 
				+                print("Failed!")
			
 
				+            elseif transaction.state == iap.TRANS_STATE_RESTORED then
			
 
				+                print("Restored")
			
 
				+            end
			
 
				+        else
			
 
				+            print(error.error)
			
 
				+        end
			
 
				+    end
			
 
				+
			
 
				+    function on_message(self, message_id, message, sender)
			
 
				+
			
 
				+        ...
			
 
				+    	-- Register the function that will listen to IAP transactions.
			
 
				+        iap.set_listener(iap_listener)
			
 
				+        -- Initiate a purchase of a coin...
			
 
				+        iap.buy(COINS_ID)
			
 
				+        ...
			
 
				+
			
 
				+    end
			
 
				+```
			
 
				+
			
 
				+The device operating system will automatically show a pop-up window allowing the user to go through with the purchase. The interface clearly indicates when you are running in the test/sandbox environment.
			
 
				+
			
 
				+![Confirm purchase](images/iap/ios_confirm_purchase.png)
			
 
				+
			
 
				+![Android purchase](images/iap/android_purchase.png)
			
 
				+
			
 
				+![Confirm purchase](images/iap/ios_purchase_done.png)
			
 
				+
			
 
				+## Synchronous payments
			
 
				+
			
 
				+Most payment providers only supports synchronous payments. This means that the client (your application) will receive a notification when the payment is complete, TRANS_STATE_PURCHASED. This is the final state of the payment, meaning no more callbacks will be done on this transaction.
			
 
				+
			
 
				+## Asynchronous payments
			
 
				+
			
 
				+Some payment providers requires supporting asynchronous payments. This means that the client (your application) will only receive a notification when the payment is initiated. In order to verify completion of payment, further communication have to be done from developer server (or client) with the payment provider in order to verify.
			
 
				+In the case of an initiated asynchronous payment the iap listener will receive the state TRANS_STATE_UNVERIFIED to indicate this (as opposed to TRANS_STATE_PURCHASED). This is the final state of the payment, meaning no more callbacks will be done on this transaction.
			
 
				+
			
 
				+## Purchase fulfillment
			
 
				+
			
 
				+In order to complete a purchase from a payment provider, the application needs to signal a purchase fulfillment to the provider telling the provider the purchase has gone through (for example by developer server-side verification).
			
 
				+Iap support both auto-completion where fulfillment is automatically signaled to the provider when a purchase is complete (this is the default behavior). You can also disable the auto completion in the game project settings. You are then required to call iap.finish() when the transaction is complete, which will signal purchase fulfillment to the provider.
			
 
				+
			
 
				+## Transaction receipt
			
 
				+
			
 
				+The receipt is a signed chunk of data that can be sent to the App Store to verify that the payment was successfully processed. This is most useful when designing a store that uses a separate server to verify that payment was processed.
			
 
				+
			
 
				+## Troubleshooting
			
 
				+
			
 
				+## Android iap.list() returns "failed to fetch product"
			
 
				+
			
 
				+You need to upload and publish an *.apk* on the alpha or beta channels on Google Play Developer Console. Also make sure that the _time and date_ on your device is correct.
			
 
				+
			
 
				+## iOS iap.list() returns nothing
			
 
				+
			
 
				+Make sure that you’ve requested an iOS Paid Applications account, and all proper documentation has been filed. Without proper authorization, your iOS app purchasing (even test purchases) will not work.
			
 
				+
			
 
				+Check that the AppId you have on the "Member Center" has in-app purchases activated and that you are signing your app (or the dev-app) with a provisioning profile that is up to date with the AppId (check the "Enabled Services:" field in the provisioning profile details in the "Certificates, Identifiers & Profiles" area of "Member Center")
			
 
				+
			
 
				+Wait. It can take a few hours for the In-App product IDs are propagated to the Sandbox environment.
			
 
				+
			
 
				+## iOS iap.list() fails logging error "Unexpected callback set"
			
 
				+
			
 
				+iap.list does not support nested calls. Calling iap.list from an iap.list callback function will be ignored with the engine logging this error.
			
 
				+
			
 
				+## On iOS, the "price_string" field contains '~' characters
			
 
				+
			
 
				+The '~' characters are placeholders where no matching character could be found in the font file. The "price_string" field returned in the product list when using `iap.list()` is formatted with _non breaking space_ (\u00a0) between the value and the currency denominator. If you render this string in the GUI, you need to add the character to the font's *extra_characters* field. On Mac OS X you can type non breaking spaces by pressing *Option-<SPACE>*. See http://en.wikipedia.org/wiki/Non-breaking_space for more information.
			
 
				+
			
 
				+
			
--- a/docs/manuals/en/images/2dgraphics/2dgraphics_animsheet.png
+++ b/docs/manuals/en/images/2dgraphics/2dgraphics_animsheet.png
--- a/docs/manuals/en/images/2dgraphics/2dgraphics_atlas.png
+++ b/docs/manuals/en/images/2dgraphics/2dgraphics_atlas.png
--- a/docs/manuals/en/images/2dgraphics/2dgraphics_atlas_add.png
+++ b/docs/manuals/en/images/2dgraphics/2dgraphics_atlas_add.png
--- a/docs/manuals/en/images/2dgraphics/2dgraphics_component_position.png
+++ b/docs/manuals/en/images/2dgraphics/2dgraphics_component_position.png
--- a/docs/manuals/en/images/2dgraphics/2dgraphics_gameobject_position.png
+++ b/docs/manuals/en/images/2dgraphics/2dgraphics_gameobject_position.png
--- a/docs/manuals/en/images/2dgraphics/2dgraphics_import1.png
+++ b/docs/manuals/en/images/2dgraphics/2dgraphics_import1.png
--- a/docs/manuals/en/images/2dgraphics/2dgraphics_import2.png
+++ b/docs/manuals/en/images/2dgraphics/2dgraphics_import2.png
--- a/docs/manuals/en/images/2dgraphics/2dgraphics_tilemap.png
+++ b/docs/manuals/en/images/2dgraphics/2dgraphics_tilemap.png
--- a/docs/manuals/en/images/2dgraphics/2dgraphics_tilemap_go.png
+++ b/docs/manuals/en/images/2dgraphics/2dgraphics_tilemap_go.png
--- a/docs/manuals/en/images/2dgraphics/2dgraphics_tiles_pick.png
+++ b/docs/manuals/en/images/2dgraphics/2dgraphics_tiles_pick.png
--- a/docs/manuals/en/images/2dgraphics/2dgraphics_tilesource.png
+++ b/docs/manuals/en/images/2dgraphics/2dgraphics_tilesource.png
--- a/docs/manuals/en/images/2dgraphics/2dgraphics_tilesource_add_animation.png
+++ b/docs/manuals/en/images/2dgraphics/2dgraphics_tilesource_add_animation.png
--- a/docs/manuals/en/images/2dgraphics/2dgraphics_tilesource_animation.png
+++ b/docs/manuals/en/images/2dgraphics/2dgraphics_tilesource_animation.png
--- a/docs/manuals/en/images/2dgraphics/2dgraphics_tilesource_collision.png
+++ b/docs/manuals/en/images/2dgraphics/2dgraphics_tilesource_collision.png
--- a/docs/manuals/en/images/3dgraphics/add_animation.png
+++ b/docs/manuals/en/images/3dgraphics/add_animation.png
--- a/docs/manuals/en/images/3dgraphics/animationset.png
+++ b/docs/manuals/en/images/3dgraphics/animationset.png
--- a/docs/manuals/en/images/android/apk_file.png
+++ b/docs/manuals/en/images/android/apk_file.png
--- a/docs/manuals/en/images/android/dmengine_on_device.png
+++ b/docs/manuals/en/images/android/dmengine_on_device.png
--- a/docs/manuals/en/images/android/download_dmengine.png
+++ b/docs/manuals/en/images/android/download_dmengine.png
--- a/docs/manuals/en/images/android/sign_bundle.png
+++ b/docs/manuals/en/images/android/sign_bundle.png
--- a/docs/manuals/en/images/android/sign_bundle2.png
+++ b/docs/manuals/en/images/android/sign_bundle2.png
--- a/docs/manuals/en/images/android/usb_debugging.png
+++ b/docs/manuals/en/images/android/usb_debugging.png
--- a/docs/manuals/en/images/animation/animsheet.png
+++ b/docs/manuals/en/images/animation/animsheet.png
--- a/docs/manuals/en/images/animation/blender_animation.png
+++ b/docs/manuals/en/images/animation/blender_animation.png
--- a/docs/manuals/en/images/animation/bounce.gif
+++ b/docs/manuals/en/images/animation/bounce.gif
--- a/docs/manuals/en/images/animation/frog_runloop.gif
+++ b/docs/manuals/en/images/animation/frog_runloop.gif
--- a/docs/manuals/en/images/animation/model_hierarchy.png
+++ b/docs/manuals/en/images/animation/model_hierarchy.png
--- a/docs/manuals/en/images/animation/property_animation.png
+++ b/docs/manuals/en/images/animation/property_animation.png
--- a/docs/manuals/en/images/animation/runloop.gif
+++ b/docs/manuals/en/images/animation/runloop.gif
--- a/docs/manuals/en/images/animation/spine_animation.png
+++ b/docs/manuals/en/images/animation/spine_animation.png
--- a/docs/manuals/en/images/animation/spine_events.png
+++ b/docs/manuals/en/images/animation/spine_events.png
--- a/docs/manuals/en/images/animation/spine_model_hierarchy.png
+++ b/docs/manuals/en/images/animation/spine_model_hierarchy.png
--- a/docs/manuals/en/images/animation/spine_model_ingame.png
+++ b/docs/manuals/en/images/animation/spine_model_ingame.png
--- a/docs/manuals/en/images/animation/wiggle.gif
+++ b/docs/manuals/en/images/animation/wiggle.gif
--- a/docs/manuals/en/images/application_lifecycle/application_lifecycle_final.png
+++ b/docs/manuals/en/images/application_lifecycle/application_lifecycle_final.png
--- a/docs/manuals/en/images/application_lifecycle/application_lifecycle_init.png
+++ b/docs/manuals/en/images/application_lifecycle/application_lifecycle_init.png
--- a/docs/manuals/en/images/application_lifecycle/application_lifecycle_overview.png
+++ b/docs/manuals/en/images/application_lifecycle/application_lifecycle_overview.png
--- a/docs/manuals/en/images/application_lifecycle/application_lifecycle_update.png
+++ b/docs/manuals/en/images/application_lifecycle/application_lifecycle_update.png
--- a/docs/manuals/en/images/building_blocks/building_blocks.png
+++ b/docs/manuals/en/images/building_blocks/building_blocks.png
--- a/docs/manuals/en/images/building_blocks/building_blocks_collection_instances.png
+++ b/docs/manuals/en/images/building_blocks/building_blocks_collection_instances.png
--- a/docs/manuals/en/images/building_blocks/building_blocks_collection_properties.png
+++ b/docs/manuals/en/images/building_blocks/building_blocks_collection_properties.png
--- a/docs/manuals/en/images/building_blocks/building_blocks_gameobject_alter.png
+++ b/docs/manuals/en/images/building_blocks/building_blocks_gameobject_alter.png
--- a/docs/manuals/en/images/building_blocks/building_blocks_gameobject_clones.png
+++ b/docs/manuals/en/images/building_blocks/building_blocks_gameobject_clones.png
--- a/docs/manuals/en/images/building_blocks/building_blocks_gameobject_file.png
+++ b/docs/manuals/en/images/building_blocks/building_blocks_gameobject_file.png
--- a/docs/manuals/en/images/building_blocks/building_blocks_gameobject_instance.png
+++ b/docs/manuals/en/images/building_blocks/building_blocks_gameobject_instance.png
--- a/docs/manuals/en/images/building_blocks/building_blocks_gameobject_instance_child.png
+++ b/docs/manuals/en/images/building_blocks/building_blocks_gameobject_instance_child.png
--- a/docs/manuals/en/images/building_blocks/building_blocks_properties.png
+++ b/docs/manuals/en/images/building_blocks/building_blocks_properties.png
--- a/docs/manuals/en/images/building_blocks/building_blocks_properties_embedded.png
+++ b/docs/manuals/en/images/building_blocks/building_blocks_properties_embedded.png
--- a/docs/manuals/en/images/cameras/cameras_camera_rotated.png
+++ b/docs/manuals/en/images/cameras/cameras_camera_rotated.png
--- a/docs/manuals/en/images/cameras/cameras_create_component.png
+++ b/docs/manuals/en/images/cameras/cameras_create_component.png
--- a/docs/manuals/en/images/cameras/cameras_fov.png
+++ b/docs/manuals/en/images/cameras/cameras_fov.png
--- a/docs/manuals/en/images/cameras/cameras_orthographic.png
+++ b/docs/manuals/en/images/cameras/cameras_orthographic.png
--- a/docs/manuals/en/images/cameras/cameras_planes.png
+++ b/docs/manuals/en/images/cameras/cameras_planes.png
--- a/docs/manuals/en/images/cameras/cameras_properties.png
+++ b/docs/manuals/en/images/cameras/cameras_properties.png
--- a/docs/manuals/en/images/cameras/cameras_speed_distance.png
+++ b/docs/manuals/en/images/cameras/cameras_speed_distance.png
--- a/docs/manuals/en/images/clipping/clipping_hierarchy.png
+++ b/docs/manuals/en/images/clipping/clipping_hierarchy.png
--- a/docs/manuals/en/images/clipping/clipping_layers.png
+++ b/docs/manuals/en/images/clipping/clipping_layers.png
--- a/docs/manuals/en/images/clipping/clipping_making_minimap.png
+++ b/docs/manuals/en/images/clipping/clipping_making_minimap.png
--- a/docs/manuals/en/images/clipping/clipping_minimap.png
+++ b/docs/manuals/en/images/clipping/clipping_minimap.png
--- a/docs/manuals/en/images/clipping/clipping_preview.png
+++ b/docs/manuals/en/images/clipping/clipping_preview.png
--- a/docs/manuals/en/images/clipping/clipping_properties.png
+++ b/docs/manuals/en/images/clipping/clipping_properties.png
--- a/docs/manuals/en/images/clipping/clipping_stencil_masks.png
+++ b/docs/manuals/en/images/clipping/clipping_stencil_masks.png
--- a/docs/manuals/en/images/clipping/clipping_two_inverters.png
+++ b/docs/manuals/en/images/clipping/clipping_two_inverters.png
--- a/docs/manuals/en/images/clipping/clipping_types.png
+++ b/docs/manuals/en/images/clipping/clipping_types.png
--- a/docs/manuals/en/images/collection_factory/collection_factory_collection.png
+++ b/docs/manuals/en/images/collection_factory/collection_factory_collection.png
--- a/docs/manuals/en/images/collection_factory/collection_factory_factory.png
+++ b/docs/manuals/en/images/collection_factory/collection_factory_factory.png
--- a/docs/manuals/en/images/collection_factory/collection_factory_game.png
+++ b/docs/manuals/en/images/collection_factory/collection_factory_game.png
--- a/docs/manuals/en/images/collection_proxies/collection_proxy_editing.png
+++ b/docs/manuals/en/images/collection_proxies/collection_proxy_editing.png
--- a/docs/manuals/en/images/collection_proxies/collection_proxy_input.png
+++ b/docs/manuals/en/images/collection_proxies/collection_proxy_input.png
--- a/docs/manuals/en/images/collection_proxies/collection_proxy_loading_1.png
+++ b/docs/manuals/en/images/collection_proxies/collection_proxy_loading_1.png
--- a/docs/manuals/en/images/collection_proxies/collection_proxy_loading_2.png
+++ b/docs/manuals/en/images/collection_proxies/collection_proxy_loading_2.png
--- a/docs/manuals/en/images/collection_proxies/collection_proxy_name.png
+++ b/docs/manuals/en/images/collection_proxies/collection_proxy_name.png
--- a/docs/manuals/en/images/collection_proxies/collection_proxy_trigger.png
+++ b/docs/manuals/en/images/collection_proxies/collection_proxy_trigger.png