Working on resource management doc.

docs/en/manuals/factory.md

@@ -52,7 +52,7 @@ 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.
+1. Sets the "score" property of the star game object.
 
 .star.script
 ```lua

docs/en/manuals/message-passing.md

@@ -5,14 +5,12 @@ brief: Message passing is the mechanism used by Defold to permit loosely coupled
 
 # Message passing
 
-Message passing is the mechanism used by Defold to permit objects to communicate without creating dependencies between them. This manual assumes that you have a basic understanding of *Game Objects*, *Components* and *Collections*.
-
-When programming it is generally best to couple all objects, code modules or components [as loosely as possible](http://en.wikipedia.org/wiki/Loose_coupling). Any object that has a dependency to the inner workings of another object is considered to be _tightly coupled_ and such coupling often leads to code that is harder to maintain and it is a common source of bugs---some of which can be very hard to track down.
+Message passing is the mechanism used by Defold to permit objects to communicate without creating dependencies between them. This manual assumes that you have a basic understanding of Defold's addressing mechanism and basic building blocks (game objects, components and collections).
 
 Defold's Lua integration does not provide object orientation in the sense that you define your application by setting up class hierarchies with inheritance (like Java, C++ or C#). Instead, Defold extends Lua with a simple and powerful object oriented design with the following characteristics:
 
 * [Message passing](/manuals/message-passing) to communicate between objects.
-* All objects have their own internal state, their own memory that they control. This is done through the `self` reference.
+* All script components have their own internal state, their own memory that they control. This is done through the `self` reference.
 * You can send _any_ message to any existing object and it is up to your code how to respond to the message. This is done through the `on_message()` function. If your code does not contain code for a particular message, nothing happens.
 
 ## Addressing and URLs
@@ -327,38 +325,21 @@ Note that the paths to the heart objects inside the "hearttree" collection are u
 The parent-child relationship is separate from the address of the object within the collection hierarchy. Thus, the parent-child relationship is _in no way_ reflected in the URL of an object.
 :::
 
-## Constructing URLs
-
-In rare situations you might find the need to build URL objects programmatically. You can do it like this:
-
-```lua
-local my_url = msg.url()
-my_url.socket = "main" -- specify by valid name
-my_url.path = hash("/hearttree/tree") -- specify as string or hash
-my_url.fragment = "script" -- specify as string or hash
-msg.post(my_url, "grow")
-```
-
-Inspecting the URL and its components:
-
-```lua
-print(my_url) --> url: [main:/hearttree/tree#script]
-print(my_url.socket) --> 786443 (internal numeric value)
-print(my_url.path) --> hash: [/hearttree/tree]
-print(my_url.fragment) --> hash: [script]
-```
+## System sockets
 
 ## System sockets
 
-Defold uses sockets for communicating with certain engine subsystems. Those are:
+Defold exposes certain engine subsystems as sockets:
 
 - `@physics:`
 - `@render:`
 - `@system:`
 
-Note that all are sockets with no path or fragment.
+For instance, you can toggle the system profiler by:
 
-For instance, you can toggle the system profiler by sending a message `msg.post("@system:", "toggle_profile")`
+```lua
+msg.post("@system:", "toggle_profile")
+```
 
 ## Collection Proxies
 

docs/en/manuals/resource.md

@@ -0,0 +1,56 @@
+---
+title: Defold resource management
+brief: This manual explains how Defold automatically manages resources and how you can manually manage loading of resources to adher to memory constraints.
+---
+
+# Resource management
+
+For smaller games, memory may not ever be an issue. However, when making larger games, and especially on handheld devices, memory problems will likely become a problem. Defold provides a range of features to help handle different scenarios.
+
+## The static resource tree
+
+When you build a game in Defold, you statically declare the resource tree. Every single part of the game is linked into the tree, starting with the bootstrap collection (usually called "main.collection"). The resource tree follows any reference and includes all resources associated with those references:
+
+- Game object and component data (atlases, sounds etc).
+- Factory component prototypes (game objects and collections).
+- Collection proxy component references (collections).
+- Custom resources declared in "game.project".
+
+When the game is *bundled*, only what is in the resource tree will be included. Anything that is not referenced in the tree is left out. There is no need to manually select what to include or exclude from the bundle.
+
+When the game is *run*, the engine starts at the bootstrap root of the tree and pulls resources into memory:
+
+- Any referenced collection and its content.
+- Game objects and component data.
+- Factory component prototypes (game objects and collections).
+
+However, the engine will not automatically follow and load the following types of references:
+
+- Game world collections referenced through collection proxies. Game worlds are relatively large so you will need to manually trigger loading and unloading of these in code. See [the Collection proxy manual](/manuals/collection-proxy) for details.
+- Files added via the *Custom Resources* setting in "game.project". These files are manually loaded with the [sys.load_resource()](/ref/sys/#sys.load_resource) function.
+
+## Dynamically loading bundled resources
+
+To postpone the loading of the resources referenced through a factory component (factory or collection factory), you can simply mark a factory with the *Load Dynamically* checkbox.
+
+![Load dynamically](images/resource/load_dynamically.png)
+
+By checking this box, the engine will still include the referenced resources in the game bundle, but it will not be automatically loaded when the game object holding the component is loaded. Instead, you have two options:
+
+1. Call `factory.create()` or `collectionfactory.create()` which will load the resources synchronously, then spawn new instances.
+2. Call `factory.load()` or `collectionfactory.load()` to load the resources asynchronously. When the resources are ready, a callback is received and you can spawn new instances.
+
+Read the [Factory manual](/manuals/factory) and the [Collection factory manual](/manual/collection-factory) for details on how this works.
+
+## Unloading dynamically loaded resources
+
+Defold keeps reference counters for all resources. If a resource's counter reaches zero it means that nothing refers to it anymore. The resource is then automatically unloaded from memory. For example, if you delete all objects spawned by a factory and you also delete the object holding the factory component, the resources previously referred to by the factory is unloaded from memory.
+
+For factories that are marked *Load Dynamically* you can call the `factory.unload()` or `collectionfactory.unload()` function. This removes the factory component's reference to the resource. If nothing else refers to the resource (all spawned objects are deleted, for instance), thie resource is unloaded from memory.
+
+## Excluding resources from bundle
+
+With collection proxies, it is possible to leave out all the resources the component refers to from the bundling process.
+
+![Resource loading](images/resource/loading.png)
+