Updated flash manual and linked it for publishing.

docs/en/en.json

@@ -114,6 +114,10 @@
                     {
                         "path": "/manuals/lua",
                         "name": "Lua in Defold"
+                    },
+                    {
+                        "path": "/manuals/flash",
+                        "name": "Defold for Flash users"
                     }
                 ]
             },

docs/en/manuals/flash.md

@@ -11,47 +11,55 @@ This guide presents Defold as an alternative for Flash game developers. It cover
 
 Some of the key advantages of Flash were the accessibility and low barriers to entry. New users could learn the program quickly, and could be creating basic games with limited time investment. Defold offers a similar advantage by providing a suite of tools dedicated to game design, while empowering advanced developers to create advanced solutions for more sophisticated requirements (for instance by allowing developers to edit the default render script).
 
-Flash games are programmed in ActionScript (with 3.0 being the most recent version), while Defold scripting is done in Lua. This guide will not go into a detailed comparison of Lua and Actionscript 3.0. The [Defold manual](/manuals/lua) provides a good introduction to Lua programming in Defold, and references the tremendously useful [Programming in Lua](https://www.lua.org/pil/) (first edition) which is freely available online. An article by Jesse Warden provides a [basic comparison of Actionscript and Lua](http://jessewarden.com/2011/01/lua-for-actionscript-developers.html), which may serve as a good starting point.
+Flash games are programmed in ActionScript (with 3.0 being the most recent version), while Defold scripting is done in Lua. This guide will not go into a detailed comparison of Lua and Actionscript 3.0. The [Defold manual](/manuals/lua) provides a good introduction to Lua programming in Defold, and references the tremendously useful [Programming in Lua](https://www.lua.org/pil/) (first edition) which is freely available online.
 
-This guide explores some of the key concepts of game development in Flash, and outlines what the closest Defold equivalents are. Similarities and differences are discussed, along with common pitfalls, to enable you to get off to a running start in transitioning from Flash to Defold.
+An article by Jesse Warden provides a [basic comparison of Actionscript and Lua](http://jessewarden.com/2011/01/lua-for-actionscript-developers.html), which may serve as a good starting point. Note thought that there are deeper differences in how Defold and Flash are constructed than what is visible at the language level. Actionscript and Flash is object oriented in the classical sense with classes and inheritance. Defold does not have classes, nor inheritance. It includes the concept of a *game object* which can contain audivisual representation, behavior and data. Operations on game objects are done with *functions* available in the Defold APIs. Furthermore, Defold encourages the use of *messages* to communicate between objects. Messages are a higher level construct than method calls and are not intended to be used as such. These differences are important and takes a while to get used to, but will not be covered in detail in this guide.
+
+Instead, this guide explores some of the key concepts of game development in Flash, and outlines what the closest Defold equivalents are. Similarities and differences are discussed, along with common pitfalls, to enable you to get off to a running start in transitioning from Flash to Defold.
 
 ## Movie clips and game objects
 
 Movie clips are a key component of Flash game development. They are symbols, each containing a unique timeline. The closest equivalent concept in Defold is a game object.
 
-![]
+![game object and movieclip](images/flash/go_movieclip.png)
 
 Unlike Flash movie clips, Defold game objects do not have timelines. Instead, a game object consists of multiple components. Components include sprites, sounds, and scripts---among many others (for further details about the components available see the [building blocks documentation](/manuals/building-blocks) and related articles). The game object in the screenshot below consists of a sprite and a script. The script component is used to control the behavior and look of game objects throughout the object’s lifecycle:
 
 ![script component](images/flash/script_component.png)
 
-Note: while movie clips can contain movie clips, game objects can not contain game objects.
+While movie clips can contain other movie clips, game objects can not *contain* game objects. However, game objects can be *childed* to other game objects, creating hierarchies that can be moved, scaled or rotated in unison.
 
-## Flash---manually creating movie clips
+## Flash—manually creating movie clips
 
 In Flash, instances of movie clips can be added to your scene manually by dragging them from the library and onto the timeline. This is illustrated in the screenshot below, where each Flash logo is an instance of the "logo" movieclip:
 
 ![manual movie clips](images/flash/manual_movie_clips.png)
 
-## Defold---manually creating game objects
+## Defold—manually creating game objects
 
-As mentioned previously, Defold does not have a timeline concept. Instead, game objects are organised in collections. Collections are containers (or prefabs) that hold game objects and other collections. At the most basic level, a game can consist of only one collection. More frequently, Defold games make use of multiple collections, either added manually to a root “main” collection or dynamically loaded via [collection proxies](/manuals/collection-proxy). This concept of loading "levels" or "screens" does not have a direct Flash equivalent.
+As mentioned previously, Defold does not have a timeline concept. Instead, game objects are organised in collections. Collections are containers (or prefabs) that hold game objects and other collections. At the most basic level, a game can consist of only one collection. More frequently, Defold games make use of multiple collections, either added manually to the bootstrap “main” collection or dynamically loaded via [collection proxies](/manuals/collection-proxy). This concept of loading "levels" or "screens" does not have a direct Flash equivalent.
 
 In the example below, the "main" collection contains three instances (listed on the right, in the *Outline* window) of the "logo" game object (seen on the left, in the *Assets* browser window):
 
 ![manual game objects](images/flash/manual_game_objects.png)
 
-## Flash---referencing manually created movie clips
+## Flash—referencing manually created movie clips
 
 Referring to manually created movie clips in Flash requires the use of a manually defined instance name:
 
 ![flash instance name](images/flash/flash_instance_name.png)
 
-## Defold---URL of game objects
+## Defold—Game object id
+
+In Defold, all game objects and components are referred to via an address. In most cases only a simple name, or a shorthand is sufficient. For example:
 
-In Defold, all game objects and components are referred to via the [message passing](/manuals/message-passing) URL (Uniform Resource Locator) system. Each game object has a unique identity that is expressed as an URL. A full URL consists of the address of the root collection, the game object, and component. In the example outlined above, an example address to the script component of one of the game objects would be `main:/logo#script`. In most cases using the full URL is too specific. Instead, relative URL:s and shorthands are used to address game objects and components. So shorthands like `#script` (the component with id "script" in the current game object) or `logo#script` (the component "script" in the game object "logo" in same collection).
+- `.` addresses the current game object.
+- `#` addresses the current component (the script).
+- `logo` addresses the game object with the id "logo".
+- `#script` addresses the component with id "script" in the current game object.
+- `logo#script` addresses the component with id "script" in the game object with id "logo".
 
-The URL of manually placed game objects is determined by the *Id* property assigned (see bottom right of screenshot). The id has to be unique. The editor automatically sets an id for you but you can change it for each game object instance that you create.
+The address of manually placed game objects is determined by the *Id* property assigned (see bottom right of screenshot). The id has to be unique for the current collection file you are working in. The editor automatically sets an id for you but you can change it for each game object instance that you create.
 
 ![game object id](images/flash/game_object_id.png)
 
@@ -59,9 +67,9 @@ The URL of manually placed game objects is determined by the *Id* property assig
 You can find the id of a game object by running the following code in its script component: `print(go.get_id())`. This will print the id of the current game object in the console.
 :::
 
-Message passing and addressing is a key concept in Defold game development. The [message passing manual](/manuals/message-passing) is a very important starting point.
+Message passing and addressing is a key concept in Defold game development. In some cases the simple examples listed above are not expressive enough. The [message passing manual](/manuals/message-passing) covers all cases.
 
-## Flash---dynamically creating movie clips
+## Flash—dynamically creating movie clips
 
 In order to dynamically create movie clips in Flash, ActionScript Linkage first needs to be set up:
 
@@ -74,7 +82,7 @@ var logo:Logo = new Logo();
 addChild(logo);
 ```
 
-## Defold---creating game objects using factories
+## Defold—creating game objects using factories
 
 In Defold, dynamic generation of game objects is achieved through the use of *factories*. Factories are components that are used to spawn copies of a specific game object. In this example, a factory has been created with the "logo" game object as a prototype:
 
@@ -87,12 +95,12 @@ It is important to note that factories, like all components, need to be added to
 The function to call to generate an instance of the logo game object is:
 
 ```lua
-factory.create("factories#logo_factory")
+local logo_id = factory.create("factories#logo_factory")
 ```
 
 The URL is a required parameter of `factory.create()`. In addition, you can add optional parameters to set position, rotation, properties, and scale. For more information on the factory component, please see the [factory manual](/manuals/factory). It is worth noting that calling `factory.create()` returns the id of the created game object. This id can be stored for later reference in a table (which is the Lua equivalent of an array).
 
-## Flash---stage
+## Flash—stage
 
 In Flash, we are familiar with the Timeline (top section of the screenshot below) and the Stage (visible below the Timeline):
 
@@ -100,9 +108,9 @@ In Flash, we are familiar with the Timeline (top section of the screenshot below
 
 As discussed in the movie clips section above, the Stage is essentially the top level container of a Flash game and is created each time a project is exported. The Stage will by default have one child, the *MainTimeline*. Each movie clip generated in the project will have its own timeline, and can serve as a container for other symbols (including movie clips).
 
-## Defold---Collections
+## Defold—collections
 
-The Defold equivalent of the Flash Stage is a collection. By default, this is the "main" collection which is what will be in a new project when you first create it. Every game needs a collection to bootstrap from. You can change which collection is loaded at startup by accessing the *game.project* settings file that is in the root of every Defold project:
+The Defold equivalent of the Flash Stage is a collection. When the engine starts up it creates a new game world based on the content of a collection file. By default, this file is called "main.collection" but you can change which collection is loaded at startup by accessing the *game.project* settings file that is in the root of every Defold project:
 
 ![game.project](images/flash/game_project.png)
 
@@ -110,10 +118,9 @@ Collections are containers that are used in the editor to organize game objects
 
 ![collection](images/flash/collection.png)
 
-For more advanced uses, the [collection proxy](/manuals/collection-proxy/) component allows you to load and unload root collections. In contrast to the collection factory mentioned previously, this would be useful for scenarios such as loading new game levels, mini games, or cutscenes.
+In some cases, you want to load a completely new game world. The [collection proxy](/manuals/collection-proxy/) component allows you to create a new game world based on the contents of a collection file. This would be useful for scenarios such as loading new game levels, mini games, or cutscenes.
 
-
-## Flash---timeline
+## Flash—timeline
 
 The Flash timeline is primarily used for animation, using various frame by frame techniques or shape/motion tweens. The overall FPS (frames per second) setting of the project defines the length of time a frame is displayed. Advanced users can modify the overall FPS of the game, or even that of individual movie clips.
 
@@ -125,7 +132,7 @@ Motion tweens allow the animation of various properties of an object, including
 
 ![motion tween](images/flash/tween.png)
 
-## Defold---property animation
+## Defold—property animation
 
 Defold works with pixel images as opposed to vector graphics, thus it does not have an equivalent for shape tweening. However, motion tweening has a powerful equivalent in [property animation](/ref/go/#go.animate). This is accomplished via script, using the `go.animate()` function. The go.animate() function tweens a property (such as color, scale, rotation or position) from the starting value to the desired end value, using one of many available easing functions (including custom ones). Where Flash required user implementation of more advanced easing functions, Defold includes [many easing functions](/manuals/animation/#_easing) built into the engine.
 
@@ -133,7 +140,7 @@ Where Flash makes use of keyframes of graphics on a timeline for animation, one
 
 ![flipbook](images/flash/flipbook.png)
 
-## Flash---depth index
+## Flash—depth index
 
 In Flash, the display list determines what is shown and in what order. The ordering of objects in a container (such as the Stage) is handled by an index. Objects added to a container using the `addChild()` method will automatically occupy the top position of the index, starting from 0 and incrementing with each additional object. In the screenshot below, we have generated three instances of the "logo" movie clip:
 
@@ -161,12 +168,12 @@ The result would look like the below (with the index position updated):
 
 ![depth index](images/flash/depth_index_2.png)
 
-## Defold---Z position
+## Defold—z position
 
 The positions of game objects in Defold are represented by vectors consisting of three variables: x, y, and z. The z position determines the depth of a game object. In the default [render script](/manuals/rendering), the available z positions range from -1 to 1.
 
 ::: sidenote
-Note – game objects with a z position outside the -1 to 1 range will not be rendered and therefore not visible. This is a common pitfall for developers new to Defold, and is worth keeping in mind if a game object is not visible when you expect it to be.
+Game objects with a z position outside the -1 to 1 range will not be rendered and therefore not visible. This is a common pitfall for developers new to Defold, and is worth keeping in mind if a game object is not visible when you expect it to be.
 :::
 
 Unlike in Flash where the editor only implies depth indexing (and allows modification using commands like *Bring Forward* and *Send Backward*), Defold allows you to set the z position of objects directly in the editor. In the screenshot below, you can see that "logo3" is displayed on top, and has a z position of 0.2. The other game objects have z positions of 0.0 and 0.1.
@@ -185,7 +192,7 @@ pos.z  = 0.5
 go.set_position(pos)
 ```
 
-## Flash---hitTestObject and hitTestPoint collision detection
+## Flash—hitTestObject and hitTestPoint collision detection
 
 Basic collision detection in Flash is achieved by using the `hitTestObject()` method. In this example, we have two movie clips: "bullet" and "bullseye". These are illustrated in the screenshot below. The blue boundary box is visible when selecting the symbols in the Flash editor, and it is these boundary boxes that drive the result of the `hitTestObject()` method.
 
@@ -209,7 +216,7 @@ bullseye.hitTestPoint(bullet.x, bullet.y, true);
 
 This line would check the x and y position of the bullet (top left in this scenario) against the shape of the target. Since `hitTestPoint()` checks a point against a shape, which point (or points!) to check is a key consideration.
 
-## Defold---collision objects
+## Defold—collision objects
 
 Defold includes a physics engine that can detect collisions and let a script react to it. Collision detection in Defold starts with assigning collision object components to game objects. In the screenshot below, we have added a collision object to the "bullet" game object. The collision object is indicated as the red transparent box (which is visible in the editor only):
 
@@ -221,7 +228,7 @@ The collision object includes the following properties:
 
 ![collision object properties](images/flash/collision_object_properties.png)
 
-A box shape has been used as this was most appropriate for the bullet graphic. The other shape used for 2D collisions, sphere, will be used for the target. Setting the type to Kinematic means resolving collisions is done by your script as opposed to the in-built physics engine (for more information on the other types, please refer to the [physics manual](/manuals/physics)). The group and mask properties determine what collision group the object belongs to and what collision group it should be checked against, respectively. The current setup means a "bullet" can only collide with a "target". Imagine the setup was changed to the below:
+A box shape has been used as this was most appropriate for the bullet graphic. The other shape used for 2D collisions, sphere, will be used for the target. Setting the type to Kinematic means resolving collisions is done by your script as opposed to the built-in physics engine (for more information on the other types, please refer to the [physics manual](/manuals/physics)). The group and mask properties determine what collision group the object belongs to and what collision group it should be checked against, respectively. The current setup means a "bullet" can only collide with a "target". Imagine the setup was changed to the below:
 
 ![collision group/mask](images/flash/collision_groupmask.png)
 
@@ -235,11 +242,11 @@ In Flash, collision detection occurs only when explicitly called by the script.
 
 The advantage of Defold collision detection is that it is more advanced than that of Flash, with the ability to detect collisions between relatively complex shapes with very little setup effort. Collision detection is automatic, meaning looping through the various objects in the different collision groups and explicitly performing hit tests is not required. The main drawback is that there is no equivalent to the Flash shapeFlag. However, for most uses combinations of the basic box and sphere shapes suffice. For more complex scenarios, custom shapes [are possible](//forum.defold.com/t/does-defold-support-only-three-shapes-for-collision-solved/1985).
 
-## Flash---event handling
+## Flash—event handling
 
 Event objects and their associated listeners are used to detect various events (e.g. mouse clicks, button presses, clips being loaded) and trigger actions in response. There are a variety of events to work with.
 
-## Defold---call-back functions and messaging
+## Defold—call-back functions and messaging
 
 The Defold equivalent of the Flash event handling system consists of a few aspects. Firstly, each script component comes with a set of callback-functions that detect specific events. These are:
 
@@ -265,18 +272,16 @@ The callback functions listed above are all optional and can be removed if not u
 
 As discussed in the collision detection section, collision events are dealt with through the sending of messages to the game objects involved. Their respective script components receive the message in their on_message callback functions.
 
-## Flash---button symbols
+## Flash—button symbols
 
 Flash uses a dedicated symbol type for buttons. Buttons use specific event handler methods (e.g. `click` and `buttonDown`) to execute actions when user interaction is detected. The graphical shape of a button in the "Hit" section of the button symbol determines the hit area of the button.
 
 ![button](images/flash/button.png)
 
-## Defold---GUI scenes and scripts
+## Defold—GUI scenes and scripts
 
 Defold does not include a native button component, nor can clicks be easily detected against the shape of a given game object in the way buttons are handled in Flash. The use of a [GUI](/manuals/gui) component is the most common solution, partially because the positions of the Defold GUI components are not affected by the in-game camera (if used). The GUI API also contains functions for detecting if user input like clicks and touch events are within the bounds of a GUI element.
 
-A [GUI library](//forum.defold.com/t/dirtylarry-a-quick-and-dirty-gui-library/2438) for test and debugging purposes containing key UI components (including buttons) has been released by the Defold team. Information on how to use libraries in Defold can be found in the [libraries manual](/manuals/libraries).
-
 ## Debugging
 
 In Flash, the `trace()` command is your friend when debugging. The Defold equivalent is `print()`, and is used in the same way as `trace()`: