Rearranged some docs and split up some

docs/en/en.json

@@ -220,6 +220,14 @@
                         "path": "/manuals/animation",
                         "name": "Animation"
                     },
+                    {
+                        "path": "/manuals/atlas",
+                        "name": "Atlas"
+                    },
+                    {
+                        "path": "/manuals/font",
+                        "name": "Font"
+                    },
                     {
                         "path": "/manuals/graphics",
                         "name": "Graphics"
@@ -228,6 +236,10 @@
                         "path": "/manuals/resource",
                         "name": "Resource management"
                     },
+                    {
+                        "path": "/manuals/tilesource",
+                        "name": "Tile source"
+                    },
                     {
                         "path": "/manuals/adapting-graphics-to-screen-size",
                         "name": "Adapting to different screen sizes"
@@ -242,8 +254,8 @@
                 "name": "COMPONENTS",
                 "items": [
                     {
-                        "path": "/manuals/atlas",
-                        "name": "Atlas"
+                        "path": "/manuals/components",
+                        "name": "Overview"
                     },
                     {
                         "path": "/manuals/collection-factory",
@@ -257,10 +269,6 @@
                         "path": "/manuals/camera",
                         "name": "Camera"
                     },
-                    {
-                        "path": "/manuals/font",
-                        "name": "Font"
-                    },
                     {
                         "path": "/manuals/factory",
                         "name": "Factory"
@@ -285,10 +293,6 @@
                         "path": "/manuals/sound",
                         "name": "Sound"
                     },
-                    {
-                        "path": "/manuals/tilemap",
-                        "name": "Tilemap"
-                    },
                     {
                         "path": "/manuals/spine",
                         "name": "Spine animation"
@@ -296,6 +300,14 @@
                     {
                         "path": "/manuals/spinemodel",
                         "name": "Spine model"
+                    },
+                    {
+                        "path": "/manuals/sprite",
+                        "name": "Sprite"
+                    },
+                    {
+                        "path": "/manuals/tilemap",
+                        "name": "Tilemap"
                     }
                 ]
             },
@@ -347,6 +359,10 @@
             {
                 "name": "GAME LOGIC",
                 "items": [
+                    {
+                        "path": "/manuals/script",
+                        "name": "Scripts"
+                    },
                     {
                         "path": "/manuals/properties",
                         "name": "Properties"
@@ -355,6 +371,10 @@
                         "path": "/manuals/script-properties",
                         "name": "Script properties"
                     },
+                    {
+                        "path": "/manuals/lua",
+                        "name": "Lua in Defold"
+                    },
                     {
                         "path": "/manuals/input",
                         "name": "Input"
@@ -393,10 +413,6 @@
                         "path": "/manuals/writing-code",
                         "name": "Writing code"
                     },
-                    {
-                        "path": "/manuals/lua",
-                        "name": "Lua in Defold"
-                    },
                     {
                         "path": "/manuals/hot-reload",
                         "name": "Hot reloading"

docs/en/manuals/animation.md

@@ -5,32 +5,41 @@ brief: This manual describes Defold's animation support.
 
 # Animation
 
-Defold has built in support for many types of animation that you can use as a source of graphics for object components:
+Defold has built in support for many types of animation that you can use as a source of graphics for 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.
+* Flip-book animation
+* Spine animation
+* 3D skinned animation
+* Property animation
+
+## 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](/manuals/atlas), or as a [Tile Source](/manuals/tilesource) with all frames laid out in a horizontal sequence.
 
   ![Animation sheet](images/animation/animsheet.png){.inline}
   ![Run loop](images/animation/runloop.gif){.inline}
 
-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.
+## 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){.inline}
   ![Run loop](images/animation/frog_runloop.gif){.inline}
 
-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.
+## 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 [Model documentation](/manuals/model).
 
   ![Blender animation](images/animation/blender_animation.png){.inline srcset="images/animation/[email protected] 2x"}
   ![Wiggle loop](images/animation/suzanne.gif){.inline}
 
-Property animation
-: All numeric properties (numbers, vector3, vector4 and quaterions) and shader constants can be animated with 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
+
+All numeric properties (numbers, vector3, vector4 and quaterions) and shader constants can be animated with 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){.inline srcset="images/animation/[email protected] 2x"}
   ![Bounce loop](images/animation/bounce.gif){.inline}

docs/en/manuals/building-blocks.md

@@ -64,30 +64,9 @@ Game objects are either added in-place in a collection, or added to a collection
 
 ## Components
 
-Components are used to give specific expression and/or functionality to game objects. Components have to be contained inside game objects and are affected by the position, rotation and scale of the game object that contains the component:
+:[components](../shared/components.md)
 
-![Components](images/building_blocks/components.png){srcset="images/building_blocks/[email protected] 2x"}
-
-Many components have type specific properties that can be manipulated and there are component type specific functions available for interacting with them in runtime:
-
-```lua
--- disable the can "body" sprite
-msg.post("can#body", "disable")
-
--- play "hoohoo" sound on "bean" in 1 second
-sound.play("bean#hoohoo", { delay = 1, gain = 0.5 } )
-```
-
-Components are either added in-place in a game object, or added to a game object as a reference to a component file:
-
-<kbd>Right-click</kbd> the game object in the *Outline* view and select <kbd>Add Component</kbd> (add in-place) or <kbd>Add Component File</kbd> (add as file reference).
-
-In most cases it makes most sense to create components in-place, but the following component types must be created in separate resource files before being added by reference to a game object:
-
-* Script
-* GUI
-* Particle FX
-* Tile Map
+Refer to the [component overview](/manuals/components.md) for a list of all available component types.
 
 ## Objects added in-place or by reference
 

docs/en/manuals/components.md

@@ -0,0 +1,52 @@
+---
+title: Game object components
+brief: This manual gives an overview of the components and how to use them.
+---
+
+#  Components
+
+:[components](../shared/components.md)
+
+## Component types
+
+Defold supports the following component types:
+
+* [Collection factory](/manuals/collection-factory) - Spawn collections
+* [Collection proxy](/manuals/collection-proxy) - Load and unload collections
+* [Collision object](/manuals/physics) - 2D and 3D physics
+* [Camera](/manuals/camera) - Change the viewport and projection of the game world
+* [Factory](/manuals/factory) - Spawn game objects
+* [GUI](/manuals/gui) - Render a graphical user interface
+* [Label](/manuals/label) - Render a piece of text
+* [Model](/manuals/model) Show a 3D model (with optional animations)
+* [Particle FX](/manuals/particlefx) -  Spawn particles
+* [Script](/manuals/script) - Add game logic
+* [Sound](/manuals/sound) - Play sound or music
+* [Spine model](/manuals/spine-model) - Render a spine animation
+* [Sprite](/manuals/sprite) - Show a 2D image (with optional flipbook animation)
+* [Tilemap](/manuals/tilemap) - Show a grid of tiles
+
+## Enabling and disabling components
+
+The components of a game object are enabled when the game object is created. If you wish to disable a component this is done by sending a `disable` message to the component:
+
+```lua
+-- disable the component with id 'weapon' on the same game object as this script
+msg.post("#weapon", "disable")
+
+-- disable the component with id 'shield' on the 'enemy' game object
+msg.post("enemy#shield", "disable")
+
+-- disable all components on the current game object
+msg.post(".", "disable")
+
+-- disable all components on the 'enemy' game object
+msg.post("enemy", "disable")
+```
+
+To enable a component again you can post an `enable` message to the component:
+
+```lua
+-- enable the component with id 'weapon'
+msg.post("#weapon", "enable")
+```

docs/en/manuals/graphics.md

@@ -5,7 +5,7 @@ brief: This manual outlines Defold's support for graphical elements.
 
 # Graphics
 
-Defold is a full 3D engine, but it is designed and built with strong support for 2D games. The editor is currently best suited for making 2D games. 
+Defold is a full 3D engine, but it is designed and built with strong support for 2D games. The editor is currently best suited for making 2D games.
 
 ## Importing Image Files
 
@@ -17,18 +17,22 @@ Defold supports images in the PNG and JPEG image formats. For models, Defold use
 
 ## Image resources
 
-In Defold, there are two types of resource that are used as an image source for visual components:
+In Defold, there are two types of resources that are used as an image source for visual components:
 
 ![atlas](images/icons/atlas.png){.icon} Atlas
 : An atlas contains a list of separate images files, which are automatically combined into a larger texture image. Atlases can contain still images and *Animation Groups*, sets of images that together form a flipbook animation.
 
   ![atlas](images/graphics/atlas.png){srcset="images/graphics/[email protected] 2x"}
 
+Learn more about the atlas resource in the [Atlas manual](/manuals/atlas).
+
 ![tile source](images/icons/tilesource.png){.icon} Tile Source
 : A tile source references an image file that is already made out to consist of smaller sub-images ordered on a uniform grid. Another term commonly used for this type of compound image is _sprite sheet_. Tile sources can contain flipbook animations, defined by the first and last tile for the animation. It is also possible to use an image to automatically attach collision shapes to tiles.
 
   ![tile source](images/graphics/tilesource.png){srcset="images/graphics/[email protected] 2x"}
 
+Learn more about the tile source resource in the [Tile source manual](/manuals/tilesource).
+
 ## Visual components
 
 There are several component types that get their image data from atlas or tile source image resources:
@@ -38,24 +42,29 @@ There are several component types that get their image data from atlas or tile s
 
   ![sprite](images/graphics/sprite.png){srcset="images/graphics/[email protected] 2x"}
 
+Learn more about sprites in the [Sprite manual](/manuals/sprite).
 
 ![tile map](images/icons/tilemap.png){.icon} Tile map
 : A tilemap component pieces together a map from tiles (image and collision shapes) that come from a tile source. Tile maps cannot use atlas sources.
 
   ![tilemap](images/graphics/tilemap.png){srcset="images/graphics/[email protected] 2x"}
 
+Learn more about tilemaps in the [Tilemap manual](/manuals/tilemap).
 
 ![particle effect](images/icons/particlefx.png){.icon} Particle fx
-: Particles that are spawned from a particle emitter consist of a still image or a flipbook animation from an atlas or tile source. 
+: Particles that are spawned from a particle emitter consist of a still image or a flipbook animation from an atlas or tile source.
 
   ![particles](images/graphics/particles.png){srcset="images/graphics/[email protected] 2x"}
 
+Learn more about particle effects in the [Particle fx manual](/manuals/particlefx).
 
 ![gui](images/icons/gui.png){.icon} GUI
 : GUI box nodes and pie nodes can use still images and flip book animations from atlases and tile sources.
 
   ![gui](images/graphics/gui.png){srcset="images/graphics/[email protected] 2x"}
 
+Learn more about GUIs in the [GUI manual](/manuals/gui).
+
 ![spine](images/icons/spine-model.png){.icon} Spine model
 : Spine models gets their data from Spine scene resources. Those contain two pieces of data:
 
@@ -64,6 +73,7 @@ There are several component types that get their image data from atlas or tile s
 
   ![spine](images/graphics/spine.png){srcset="images/graphics/[email protected] 2x"}
 
+Learn more about Spine models in the [Spine model manual](/manuals/spine-model).
 
 
 ## 3D graphics
@@ -71,10 +81,12 @@ There are several component types that get their image data from atlas or tile s
 Models get its image data directly from an image file that is mapped onto the model according to the model's UV map:
 
 ![model](images/icons/model.png){.icon} Model
-: 3D models 
+: 3D models
 
   ![model](images/graphics/model.png){srcset="images/graphics/[email protected] 2x"}
 
+Learn more about models in the [Model manual](/manuals/model).
+
 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.
 

docs/en/manuals/importing-assets.md

@@ -7,7 +7,7 @@ brief: This manual covers how to import and edit assets in Defold using external
 
 A game project usually consists of a large number of external assets that are produced in various specialized programs for producing graphics, 3D models, sound files, animations and so forth. Defold is built for a workflow where you work in your external tools and then import the assets into Defold as they are finalized. When the assets are imported into Defold they can be used by the various component types to create flipbook animations, tilemaps, particle effects and many other things:
 
-* Images can be used to create texture atlases and tile sources which in turn can be used by visual components such as sprites, tilemaps and particle effects. Read more about this in the [Graphics manual](/manuals/graphics/#_importing_image_files).
+* Images can be used to create texture [atlases](/manuals/atlas) and tile sources which in turn can be used by visual components such as [sprites](/manuals/sprite), [tilemaps](/manuals/tilemap) and [particle effects](/manuals/particlefx). Read more about this in the [Graphics manual](/manuals/graphics/#_importing_image_files).
 * Sounds can be used by the [Sound component](/manuals/sound) to play sounds.
 * Spine animation data is used by the [Spine component](/manuals/spinemodel) to show and animate Spine models.
 * Fonts are used by the [Label component](/manuals/label) and by [text nodes](/manuals/gui-text) in a GUI.

docs/en/manuals/lua.md

@@ -502,142 +502,6 @@ function update(self, dt)
 end
 ```
 
-## Defold scripts
-
-The Defold editor supports Lua script editing with syntax coloring and auto-completion. To fill out Defold function names, press *Ctrl+Space* to bring up a list of the functions matching what you are typing.
-
-![Auto completion](images/lua/completion.png){srcset="images/lua/[email protected] 2x"}
-
-There are three types of Lua script in Defold, each has different Defold libraries available.
-
-Logic scripts
-: Extension _.script_. Run by script components in game objects. Logic scripts are usually used to control game objects and the logic that binds the game together with level loading, game rules and so forth. Logic scripts have access to all Defold library functions except [GUI](/ref/gui) and [Render](/ref/render) functions.
-
-
-GUI scripts
-: Extension _.gui_script_. Run by GUI components and usually containing the logic required to display GUI elements like heads up displays, menus etc. GUI scripts have access to the [GUI](/ref/gui) library functions.
-
-
-Render scripts
-: Extension _.render_script_. Run by the rendering pipeline and containing the logic required to render all app/game graphics each frame. Render scripts have access to the [Render](/ref/render) library functions.
-
-
-## Script execution and callbacks
-
-Defold executes Lua scripts as part of the engine lifecycle and exposes the lifecycle through a set of predefined callback functions. When you add a script component to a game object the script becomes part of the game object's and its component(s) lifecycle. The script is evaluated in the Lua context when it is loaded, then the engine executes the following functions and passes a reference to the current script component instance as parameter. You can use this `self` reference to store state in the component instance. `self` is a userdata object that acts like a Lua table but you can't iterate over it with `pairs()` or `ipairs()`.
-
-`init(self)`
-: Called when the component is initialized.
-
-  ```lua
-  function init(self)
-      -- These variables are available through the lifetime of the component instance
-      self.my_var = "something"
-      self.age = 0
-  end
-  ```
-
-`final(self)`
-: Called when the component is deleted. This is useful for cleaning up purposes, for instance if you have spawned game objects that should be deleted when the component is deleted.
-
-  ```lua
-  function final(self)
-      if self.my_var == "something" then
-          -- do some cleanup
-      end
-  end
-  ```
-
-`update(self, dt)`
-: Called once each frame. `dt` contains the delta time since the last frame.
-
-  ```lua
-  function update(self, dt)
-      self.age = self.age + dt -- increase age with the timestep
-  end
-  ```
-
-`on_message(self, message_id, message, sender)`
-: When messages are sent to the script component through [`msg.post()`](/ref/msg#msg.post) the engine calls this function of the receiver component.
-
-`on_input(self, action_id, action)`
-: If this component has acquired input focus (see [`acquire_input_focus`](/ref/go/#acquire_input_focus)) the engine calls this function when input is registered.
-
-`on_reload(self)`
-: This function is called when the script is reloaded through the hot reload editor function (<kbd>Edit ▸ Reload Resource</kbd>). It is very useful for debugging, testing and tweaking purposes.
-
-  ```lua
-  function on_reload(self)
-      print(self.age) -- print the age of this game object
-  end
-  ```
-
-## Reactive logic
-
-A game object with a script component implements some logic. Often, that logic is dependent on some external factor. An enemy AI might react to the player being within a certain radius from the AI; a door might unlock and open as a result of player interaction, etc, etc.
-
-The `update()` function allows you to implement complex behaviors defined as a state machine running each frame---sometimes that is the adequate approach. But there is a cost associated with each call to `update()`. Unless you really need the function you should delete it and instead try to build your logic _reactively_. It is cheaper to passively wait for some message to trigger a response than it is to actively probe the game world for data to respond to. Furthermore, solving a design problem reactively also often leads to cleaner and more stable design and implementation.
-
-Let's look at a concrete example. Suppose that you want a script component to send a message 2 seconds after it has been initiated. It should then wait for a certain response message and after receiving the response, it should send another message 5 seconds later. The non reactive code for that would look something like this:
-
-```lua
-function init(self)
-    -- Counter to keep track of time.
-    self.counter = 0
-    -- We need this to keep track of our state.
-    self.state = "first"
-end
-
-function update(self, dt)
-    self.counter = self.counter + dt
-    if self.counter >= 2.0 and self.state == "first" then
-        -- send message after 2 seconds
-        msg.post("some_object", "some_message")
-        self.state = "waiting"
-    end
-    if self.counter >= 5.0 and self.state == "second" then
-        -- send message 5 seconds after we received "response"
-        msg.post("another_object", "another_message")
-        -- Nil the state so we don’t reach this state block again.
-        self.state = nil
-    end
-end
-
-function on_message(self, message_id, message, sender)
-    if message_id == hash("response") then
-        -- “first” state done. enter next
-        self.state = "second"
-        -- zero the counter
-        self.counter = 0
-    end
-end
-```
-
-Even in this quite simple case we get fairly tangled up logic. It's possible to make this look better with the help of coroutines in a module (see below), but let's instead try to make this reactive and use a built in timing mechanism.
-
-```lua
-local function send_first()
-	msg.post("some_object", "some_message")
-end
-
-function init(self)
-	-- Wait 2s then call send_first()
-	timer.delay(2, false, send_first)
-end
-
-local function send_second()
-	msg.post("another_object", "another_message")
-end
-
-function on_message(self, message_id, message, sender)
-	if message_id == hash("response") then
-		-- Wait 5s then call send_second()
-		timer.delay(5, false, send_second)
-	end
-end
-```
-
-This is cleaner and easier to follow. We get rid of internal state variables that are often hard to follow through the logic---and which might lead to subtle bugs. We also dispose of the `update()` function completely. That relieves the engine from calling our script 60 times a second, even if it's just idling.
 
 ## Lua contexts in Defold
 

docs/en/manuals/script.md

@@ -0,0 +1,150 @@
+---
+title: Writing game logic in scripts
+brief: This manual describes how to add game logic using the script component.
+---
+
+#  Scripts
+
+The Script component allows you to create game logic using the [Lua programming language](/manuals/lua). Scripts are added to game objects exactly like any other [component](/manuals/components) and Defold will execute the Lua code as part of the engine lifecycle functions.
+
+
+## Script types
+
+There are three types of Lua script in Defold, each has different Defold libraries available.
+
+Logic scripts
+: Extension _.script_. Run by script components in game objects. Logic scripts are usually used to control game objects and the logic that binds the game together with level loading, game rules and so forth. Logic scripts have access to all Defold library functions except [GUI](/ref/gui) and [Render](/ref/render) functions.
+
+
+GUI scripts
+: Extension _.gui_script_. Run by GUI components and usually containing the logic required to display GUI elements like heads up displays, menus etc. GUI scripts have access to the [GUI](/ref/gui) library functions.
+
+
+Render scripts
+: Extension _.render_script_. Run by the rendering pipeline and containing the logic required to render all app/game graphics each frame. Render scripts have access to the [Render](/ref/render) library functions.
+
+
+## Script execution and callbacks
+
+Defold executes Lua scripts as part of the engine lifecycle and exposes the lifecycle through a set of predefined callback functions. When you add a script component to a game object the script becomes part of the game object's and its component(s) lifecycle. The script is evaluated in the Lua context when it is loaded, then the engine executes the following functions and passes a reference to the current script component instance as parameter. You can use this `self` reference to store state in the component instance. `self` is a userdata object that acts like a Lua table but you can't iterate over it with `pairs()` or `ipairs()`.
+
+`init(self)`
+: Called when the component is initialized.
+
+  ```lua
+  function init(self)
+      -- These variables are available through the lifetime of the component instance
+      self.my_var = "something"
+      self.age = 0
+  end
+  ```
+
+`final(self)`
+: Called when the component is deleted. This is useful for cleaning up purposes, for instance if you have spawned game objects that should be deleted when the component is deleted.
+
+  ```lua
+  function final(self)
+      if self.my_var == "something" then
+          -- do some cleanup
+      end
+  end
+  ```
+
+`update(self, dt)`
+: Called once each frame. `dt` contains the delta time since the last frame.
+
+  ```lua
+  function update(self, dt)
+      self.age = self.age + dt -- increase age with the timestep
+  end
+  ```
+
+`on_message(self, message_id, message, sender)`
+: When messages are sent to the script component through [`msg.post()`](/ref/msg#msg.post) the engine calls this function of the receiver component.
+
+`on_input(self, action_id, action)`
+: If this component has acquired input focus (see [`acquire_input_focus`](/ref/go/#acquire_input_focus)) the engine calls this function when input is registered.
+
+`on_reload(self)`
+: This function is called when the script is reloaded through the hot reload editor function (<kbd>Edit ▸ Reload Resource</kbd>). It is very useful for debugging, testing and tweaking purposes.
+
+  ```lua
+  function on_reload(self)
+      print(self.age) -- print the age of this game object
+  end
+  ```
+
+
+## Reactive logic
+
+A game object with a script component implements some logic. Often, that logic is dependent on some external factor. An enemy AI might react to the player being within a certain radius from the AI; a door might unlock and open as a result of player interaction, etc, etc.
+
+The `update()` function allows you to implement complex behaviors defined as a state machine running each frame---sometimes that is the adequate approach. But there is a cost associated with each call to `update()`. Unless you really need the function you should delete it and instead try to build your logic _reactively_. It is cheaper to passively wait for some message to trigger a response than it is to actively probe the game world for data to respond to. Furthermore, solving a design problem reactively also often leads to cleaner and more stable design and implementation.
+
+Let's look at a concrete example. Suppose that you want a script component to send a message 2 seconds after it has been initiated. It should then wait for a certain response message and after receiving the response, it should send another message 5 seconds later. The non reactive code for that would look something like this:
+
+```lua
+function init(self)
+    -- Counter to keep track of time.
+    self.counter = 0
+    -- We need this to keep track of our state.
+    self.state = "first"
+end
+
+function update(self, dt)
+    self.counter = self.counter + dt
+    if self.counter >= 2.0 and self.state == "first" then
+        -- send message after 2 seconds
+        msg.post("some_object", "some_message")
+        self.state = "waiting"
+    end
+    if self.counter >= 5.0 and self.state == "second" then
+        -- send message 5 seconds after we received "response"
+        msg.post("another_object", "another_message")
+        -- Nil the state so we don’t reach this state block again.
+        self.state = nil
+    end
+end
+
+function on_message(self, message_id, message, sender)
+    if message_id == hash("response") then
+        -- “first” state done. enter next
+        self.state = "second"
+        -- zero the counter
+        self.counter = 0
+    end
+end
+```
+
+Even in this quite simple case we get fairly tangled up logic. It's possible to make this look better with the help of coroutines in a module (see below), but let's instead try to make this reactive and use a built in timing mechanism.
+
+```lua
+local function send_first()
+	msg.post("some_object", "some_message")
+end
+
+function init(self)
+	-- Wait 2s then call send_first()
+	timer.delay(2, false, send_first)
+end
+
+local function send_second()
+	msg.post("another_object", "another_message")
+end
+
+function on_message(self, message_id, message, sender)
+	if message_id == hash("response") then
+		-- Wait 5s then call send_second()
+		timer.delay(5, false, send_second)
+	end
+end
+```
+
+This is cleaner and easier to follow. We get rid of internal state variables that are often hard to follow through the logic---and which might lead to subtle bugs. We also dispose of the `update()` function completely. That relieves the engine from calling our script 60 times a second, even if it's just idling.
+
+
+## Editor support
+
+The Defold editor supports Lua script editing with syntax coloring and auto-completion. To fill out Defold function names, press *Ctrl+Space* to bring up a list of the functions matching what you are typing.
+
+![Auto completion](images/script/completion.png){srcset="images/script/[email protected] 2x"}

docs/en/manuals/sprite.md

@@ -0,0 +1,12 @@
+---
+title: Showing 2D images
+brief: This manual describes how to show 2D images and animations using the sprite component.
+---
+
+#  Sprites
+
+A Sprite component is a simple image or flipbook animation that is displayed on screen.
+
+![sprite](images/graphics/sprite.png){srcset="images/graphics/[email protected] 2x"}
+
+The Sprite component can use either an [Atlas](/manuals/atlas) or a [Tile Source](/manuals/tilesource) for it's graphics.

docs/en/manuals/tilemap.md

@@ -7,104 +7,9 @@ brief: This manual details Defold's support for 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.
 
-Before you can make a tile map you need to create a tile source.
+Before you can create a tile map you need to create a Tile Source. Refer to the [Tile Source manual](/manuals/tilesource) to learn how to create a Tile Source.
 
-## Creating a tile source
-
-You need an image containing all the tiles. Each tile must have the exact same dimensions and be placed in a grid. Defold supports _spacing_ between the tiles and a _margin_ around each tile.
-
-![tile image](images/tilemap/small_map.png){srcset="images/tilemap/[email protected] 2x"}
-
-Once you have the source image created, you can create a Tile Source:
-
-- Import the image to your project by dragging it into a project location in the *Assets* browser.
-- Create a new tile source file (<kbd>right click</kbd> a location in the *Assets* browser, then select <kbd>New... ▸ Tile Source</kbd>).
-- Name the new file.
-- The file now opens in the tile source editor.
-- 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 *Properties* to match the source image. When everything is correct the tiles will line up perfectly.
-
-![Creating a Tile Source](images/tilemap/tilesource.png){srcset="images/tilemap/[email protected] 2x"}
-
-Size
-: The size of the source image.
-
-Tile Width
-: The width of each tile.
-
-Tile Height
-: The height of each tile.
-
-Tile Margin
-: The number of pixels surrounding each tile (orange in the image above).
-
-Tile Spacing
-: The number of pixels between each tile (blue in the image above).
-
-Inner Padding
-: Specifies how many empty pixels should be automatically added around the tile in the resulting texture used when the game is run.
-
-Extrude Border
-: Specifies how many times the edge pixels should be automatically replicated around the tile in the resulting texture used when the game is run.
-
-Collision
-: Specifies the image to use to automatically generate collision shapes for tiles.
-
-## Tile source flip-book animations
-
-To define an animation in a tile source the animation frame tiles 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 have a default animation named "anim". You can add new animations by <kbd>right clicking</kbd> the tile source root in the *Outline* and selecting <kbd>Add ▸ Animation</kbd>.
-
-Selecting an animation displays the animation *Properties*.
-
-![Tile Source animation](images/tilemap/animation.png){srcset="images/tilemap/[email protected] 2x"}
-
-Id
-: The identity of the animation. Must be unique for the tile source.
-
-Start Tile
-: The first tile of the animation. Numbering starts at 1 in the top left corner and goes to the right, line by line down to the bottom right corner.
-
-End Tile
-: The last tile of the animation.
-
-Playback
-: Specifies how the animation should play:
-
-  - `None` does not play back at all, the first image is displayed.
-  - `Once Forward` plays the animation one time from the first to the last image.
-  - `Once Backward` plays the animation one time from the last to the first image.
-  - `Once Ping Pong` plays the animation one time from the first to the last image and then back to the first image.
-  - `Loop Forward` plays the animation repeatedly from the first to the last image.
-  - `Loop Backward` plays the animation repeatedly from the last to the first image.
-  - `Loop Ping Pong` plays the animation repeatedly from the first to the last image and then back to the first image.
-
-Fps
-: The playback speed of the animation, expressed in frames per second (FPS).
-
-Flip horizontal
-: Flips the animation horizontally.
-
-Flip vertical
-: Flips the animation vertically.
-
-## Tile source collision shapes
-
-Defold uses an image specified in the *Collision* property to generate a _convex_ shape for each tile. The shape will outline the part of the tile that has color information, i.e. is not 100% transparent.
-
-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.
-
-The tile source outline lists collision groups that you have added to the tile source. New tile source files will get one "default" collision group added. You can add new groups by <kbd>right clicking</kbd> the tile source root in the *Outline* and selecting <kbd>Add ▸ Collision Group</kbd>.
-
-To select the tile shapes that should belong to a certain group, select the group in th *Outline*, then click each tile that you wish to assign to the group. The outline of the tile and shape is colored with the group's color. The color is automatically assigned to the group in the editor.
-
-![Collision Shapes](images/tilemap/collision.png){srcset="images/tilemap/[email protected] 2x"}
-
-To remove a tile from its collision group, select the tile source root element in the *Outline*, then click the tile.
-
-
-## Tile maps
-
-A *Tile Map* is a component that allows you to assemble, or _paint_, tiles from a tile source onto a 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.
+## Creating a tile map
 
 To create a new tile map:
 
@@ -153,4 +58,3 @@ if tile == 2 then
     tilemap.set_tile("/level#map", "ground", x, y, 4)
 end
 ```
-

docs/en/manuals/tilesource.md

@@ -0,0 +1,100 @@
+---
+title: Defold tile source manual
+brief: This describes how to use and create a tile source.
+---
+
+# Tile source
+
+A *Tile Source* can be used by a [Tilemap component](/manuals/tilemap) to paint tiles onto a grid area or it can be used as the graphics source for a [Sprite](/manuals/sprite) or [Particle Effect component](/manuals/particlefx). You can also use the *Collision Shapes* from the tile source in a Tilemap for [collision detection and physics simulation](/manuals/physics).
+
+## Creating a tile source
+
+You need an image containing all the tiles. Each tile must have the exact same dimensions and be placed in a grid. Defold supports _spacing_ between the tiles and a _margin_ around each tile.
+
+![tile image](images/tilemap/small_map.png){srcset="images/tilemap/[email protected] 2x"}
+
+Once you have the source image created, you can create a Tile Source:
+
+- Import the image to your project by dragging it into a project location in the *Assets* browser.
+- Create a new tile source file (<kbd>right click</kbd> a location in the *Assets* browser, then select <kbd>New... ▸ Tile Source</kbd>).
+- Name the new file.
+- The file now opens in the tile source editor.
+- 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 *Properties* to match the source image. When everything is correct the tiles will line up perfectly.
+
+![Creating a Tile Source](images/tilemap/tilesource.png){srcset="images/tilemap/[email protected] 2x"}
+
+Size
+: The size of the source image.
+
+Tile Width
+: The width of each tile.
+
+Tile Height
+: The height of each tile.
+
+Tile Margin
+: The number of pixels surrounding each tile (orange in the image above).
+
+Tile Spacing
+: The number of pixels between each tile (blue in the image above).
+
+Inner Padding
+: Specifies how many empty pixels should be automatically added around the tile in the resulting texture used when the game is run.
+
+Extrude Border
+: Specifies how many times the edge pixels should be automatically replicated around the tile in the resulting texture used when the game is run.
+
+Collision
+: Specifies the image to use to automatically generate collision shapes for tiles.
+
+## Tile source flip-book animations
+
+To define an animation in a tile source the animation frame tiles 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 have a default animation named "anim". You can add new animations by <kbd>right clicking</kbd> the tile source root in the *Outline* and selecting <kbd>Add ▸ Animation</kbd>.
+
+Selecting an animation displays the animation *Properties*.
+
+![Tile Source animation](images/tilemap/animation.png){srcset="images/tilemap/[email protected] 2x"}
+
+Id
+: The identity of the animation. Must be unique for the tile source.
+
+Start Tile
+: The first tile of the animation. Numbering starts at 1 in the top left corner and goes to the right, line by line down to the bottom right corner.
+
+End Tile
+: The last tile of the animation.
+
+Playback
+: Specifies how the animation should play:
+
+  - `None` does not play back at all, the first image is displayed.
+  - `Once Forward` plays the animation one time from the first to the last image.
+  - `Once Backward` plays the animation one time from the last to the first image.
+  - `Once Ping Pong` plays the animation one time from the first to the last image and then back to the first image.
+  - `Loop Forward` plays the animation repeatedly from the first to the last image.
+  - `Loop Backward` plays the animation repeatedly from the last to the first image.
+  - `Loop Ping Pong` plays the animation repeatedly from the first to the last image and then back to the first image.
+
+Fps
+: The playback speed of the animation, expressed in frames per second (FPS).
+
+Flip horizontal
+: Flips the animation horizontally.
+
+Flip vertical
+: Flips the animation vertically.
+
+## Tile source collision shapes
+
+Defold uses an image specified in the *Collision* property to generate a _convex_ shape for each tile. The shape will outline the part of the tile that has color information, i.e. is not 100% transparent.
+
+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.
+
+The tile source outline lists collision groups that you have added to the tile source. New tile source files will get one "default" collision group added. You can add new groups by <kbd>right clicking</kbd> the tile source root in the *Outline* and selecting <kbd>Add ▸ Collision Group</kbd>.
+
+To select the tile shapes that should belong to a certain group, select the group in th *Outline*, then click each tile that you wish to assign to the group. The outline of the tile and shape is colored with the group's color. The color is automatically assigned to the group in the editor.
+
+![Collision Shapes](images/tilemap/collision.png){srcset="images/tilemap/[email protected] 2x"}
+
+To remove a tile from its collision group, select the tile source root element in the *Outline*, then click the tile.

docs/en/shared/components.md

@@ -0,0 +1,24 @@
+Components are used to give specific expression and/or functionality to game objects. Components have to be contained inside game objects and are affected by the position, rotation and scale of the game object that contains the component:
+
+![Components](../shared/images/components.png){srcset="../shared/images/[email protected] 2x"}
+
+Many components have type specific properties that can be manipulated and there are component type specific functions available for interacting with them in runtime:
+
+```lua
+-- disable the can "body" sprite
+msg.post("can#body", "disable")
+
+-- play "hoohoo" sound on "bean" in 1 second
+sound.play("bean#hoohoo", { delay = 1, gain = 0.5 } )
+```
+
+Components are either added in-place in a game object, or added to a game object as a reference to a component file:
+
+<kbd>Right-click</kbd> the game object in the *Outline* view and select <kbd>Add Component</kbd> (add in-place) or <kbd>Add Component File</kbd> (add as file reference).
+
+In most cases it makes most sense to create components in-place, but the following component types must be created in separate resource files before being added by reference to a game object:
+
+* Script
+* GUI
+* Particle FX
+* Tile Map