Updated optimization pages

docs/en/en.json

@@ -1429,6 +1429,22 @@
                         "path": "/manuals/optimization",
                         "name": "Optimizing an application"
                     },
+                    {
+                        "path": "/manuals/optimization-size",
+                        "name": "Optimize game size"
+                    },
+                    {
+                        "path": "/manuals/optimization-speed",
+                        "name": "Optimize runtime performance"
+                    },
+                    {
+                        "path": "/manuals/optimization-battery",
+                        "name": "Optimize battery usage"
+                    },
+                    {
+                        "path": "/manuals/optimization-memory",
+                        "name": "Optimize memory usage"
+                    },
                     {
                         "path": "/manuals/profiling",
                         "name": "Profiling"

docs/en/manuals/html5.md

@@ -305,6 +305,12 @@ function init(self)
 end
 ```
 
+## Optimizations
+HTML5 games usually have strict requirements on initial download size, startup time and memory usage to ensure that games load fast and run well on low end devices and slow internet connections. To optimize an HTML5 game it is recommended to focus on the following areas:
+
+* [Memory usage](/manuals/optimization-memory)
+* [Engine size](/manuals/optimization-size)
+* [Game size](/manuals/optimization-size)
 
 ## FAQ
 :[HTML5 FAQ](../shared/html5-faq.md)

docs/en/manuals/optimization-battery.md

@@ -0,0 +1,12 @@
+---
+title: Optimizing battery usage of a Defold game
+brief: This manual describes how to optimize battery usage a Defold game.
+---
+
+# Optimize battery usage
+Battery usage is mainly a concern if you are targeting mobile/handheld devices. High CPU or GPU usage will quickly drain battery and overheat the device.
+
+Refer to the manuals on how to [optimize runtime performance](/manuals/optimization-speed) of a game to learn how to reduce CPU and GPU usage.
+
+## Disable accelerometer
+If you are creating a mobile game which doesn't make use of the device accelerometer it is recommended to [disable it in *game.project*](/manuals/project-settings/#use-accelerometer) to reduce the number of generated input events.

docs/en/manuals/optimization-memory.md

@@ -0,0 +1,28 @@
+---
+title: Optimizing memory usage of a Defold game
+brief: This manual describes how to optimize memory usage of a Defold game.
+---
+
+# Optimizing memory usage
+
+## Texture compression
+The use of texture compression will not only reduce the size of resources within your game archive, but compressed textures may also reduce the amount of GPU memory required.
+
+## Dynamic loading
+Most game have at least some content that is used infrequently. From a memory usage stand point it does not make sense to have such content loaded in memory at all times, but rather load and unload it when it is neded. This will obviously be a trade-off between having something readily accessible at the cost of runtime memory and loading something at the cost of loading time.
+
+Defold has several different ways of loading content dynamically:
+
+* [Collection proxies](/manuals/collection-proxy/)
+* [Dynamic collection factories](/manuals/collection-factory/#dynamic-loading-of-factory-resources)
+* [Dynamic factories](/manuals/factory/#dynamic-loading-of-factory-resources)
+* [Live Update](/manuals/live-update/)
+
+## Optimize component counters
+Defold will allocate memory for components and resources once when a collection is created, to reduce memory fragmentation. The amount of memory that is allocated depends on the configuration of various components counters in *game.project*. Use the [profiler](/manuals/profiling/) to get accurate component and resource usage and configure your game to use max values that are closer to the real count of components and resources. This will reduce the amount of memory your game is using (refer to information about component [max count optimizations](/manuals/project-settings/#component-max-count-optimizations)).
+
+## Optimize GUI node count
+Optimize GUI node counts by setting the max number of nodes in the GUI file to only what is needed. The `Current Nodes` field of the [GUI component properties](https://defold.com/manuals/gui/#gui-properties) will show the number of nodes used by the GUI component.
+
+:[HTML5 Optimizations](../shared/optimization-memory-html5)
+

docs/en/manuals/optimization-size.md

@@ -0,0 +1,90 @@
+---
+title: Optimizing size of a Defold game
+brief: This manual describes how to optimize the size of a Defold game.
+---
+
+# Optimizing game size
+
+The size of your game can be a critical success factor for platforms such as web and mobile, while it is of less importance on desktop and consoles where disk space is cheap and often plentiful.
+
+* Apple and Google has defined application size limits when downloading over mobile networks (as opposed to downloading over Wifi).
+  * In the summer of 2019 these limits were 100 MB for Google Play and 150 MB for the Apple App Store.
+* Poki and many other web game platforms recommend that the initial download should be no larger than 5 MB.
+* Facebook has a recommendation that a Facebook Instant Game should start in less than 5 seconds and preferably less than 3 seconds.
+  * What this means for actual application size is not clearly defined but we are talking size in the range of up to 20 MB.
+* Playable ads are usually limited to between 2 and 5 MB depending on the ad network.
+
+::: sidenote
+According to a 2017 study it was shown that "For every 6 MB increase to an APK’s size, we see a decrease in the install conversion rate of 1%." ([source](https://medium.com/googleplaydev/shrinking-apks-growing-installs-5d3fcba23ce2))
+:::
+
+You can optimize the application size in two ways; by reducing the size of the engine and/or by reducing the size of the game assets.
+
+To get a better understanding of what makes up the size of your application you can [generate a build report](/manuals/bundling/#build-reports) when bundling. It is quite common that sounds and graphics is what takes up the bulk of the size of any game.
+
+::: important
+Defold will create a dependency tree when building and bundling your application. The build system will start from the bootstrap collection specified in the *game.project* file and inspect every referenced collection, game object and component to build a list of the assets that are in use. It is only these assets that will get included in the final application bundle. Anything not directly referenced will get excluded. While it is good to know that unused assets will not be included you as a developer still needs to consider what goes into the final application and the size of the individual assets and the total size of the application bundle. 
+:::
+
+
+## Optimize engine size
+A quick way to reduce the engine size is to remove functionality in the engine that you do not use. This is done [application manifest file](https://defold.com/manuals/app-manifest/) where it is possible to remove engine components that you do not need. Examples:
+
+* Physics - If your game does not make use of Box2D or Bullet3D physics then it is strongly advised to remove the physics engines
+* LiveUpdate - If your game does not use LiveUpdate it can be removed
+* Image loaded - If your game does not manually load and decode images using `image.load()`
+* BasisU - If your game has few textures, compare the build size without BasisU (removed via app manifest) and without texture compression versus a build with BasisU and compressed textures. For games with limited textures, it might be more beneficial to reduce the binary size and skip texture compression. Additionally, not using the transcoder can lower the amount of memory required to run your game.
+
+
+## Optimize asset size
+The biggest wins in terms of asset size optimizations are usually gained by reducing the size of sounds and textures.
+
+### Optimize sounds
+Defold supports .ogg and .wav files where .ogg is typically used for music and .wav for sound effects. Sounds must be 16-bit with a sampling rate of 44100 so any optimizations must be done on the sounds before encoding them. You can edit the sounds in an external sound editor software to reduce the quality or convert from .wav to .ogg. Also consider converting sounds from stereo to mono.
+
+### Optimize textures
+You have several options when it comes to optimizing the textures used by your game, but the first thing to do is to check the size of the images that gets added to an atlas or used as a tilesource. You should never use a larger size on the images than is actually needed in your game. Importing large images and scaling them down to the appropriate size is a waste of texture memory and should be avoided. Start by adjusting the size of the images using external image editing software to the actual size needed in your game. For things such as background images it might also be ok to use a small image and scale it up to the desired size. Once you have the images down to the correct size and added to atlases or used in tilesources you also need to consider the size of the atlases themselves. The maximum atlas size that can be used varies between platforms and graphics hardware.
+
+::: sidenote
+[This forum posts](https://forum.defold.com/t/texture-management-in-defold/8921/17?u=britzl) suggests several tips on how to resize multiple images using scripts or third party software.
+:::
+
+* Max texture size on HTML5: https://webglstats.com/webgl/parameter/MAX_TEXTURE_SIZE
+* Max texture size on iOS:
+  * iPad: 2048x2048
+  * iPhone 4: 2048x2048
+  * iPad 2, 3, Mini, Air, Pro: 4096x4096
+  * iPhone 4s, 5, 6+, 6s: 4096x4096
+* Max texture size on Android varies greatly but in general all reasonably new devices support at least 4096x4096.
+
+If an atlas is too large you need to either split it into several smaller atlases, use multi-page atlases or scale the entire atlas using a texture profile. The texture profile system in Defold allows you to not only scale entire atlases but also to apply compression algorithms to reduce the size of the atlas on disk. You can [read more about texture profiles in the manual](/manuals/texture-profiles/). If you don’t know what to use, try to start with these settings as a starting point for further customizations:
+
+* mipmaps: false
+* premultiply_alpha: true
+* format: TEXTURE_FORMAT_RGBA
+* compression_level: NORMAL
+* compression_type: COMPRESSION_TYPE_BASIS_UASTC
+
+::: sidenote
+You can read more about how to optimize and manage textures in [this forum post](https://forum.defold.com/t/texture-management-in-defold/8921).
+:::
+
+### Optimize fonts
+The size of your fonts will be smaller if you specify what symbols you are going to use and set this in [Characters](/manuals/font/#properties) instead of using the All Chars checkbox.
+
+
+### Exclude content for download on demand
+Another way of reducing initial application size is to exclude parts of the game content from the application bundle and download it on demand. Defold provides a system called Live Update for excluding content for download on demand.
+
+Excluded content can be anything from entire levels to unlockable characters, skins, weapons or vehicles. If your game has a lot of content, organize the loading process so that the bootstrap collection and the first level collection include the bare minimum resources required for that level. You achieve this by using collection proxies or factories with the "Exclude" checkbox enabled. Split resources according to the player's progress. This approach ensures efficient resource loading and keeps initial memory usage low. Learn more in the [Live Update manual](/manuals/live-update/).
+
+
+
+## Android specific size optimizations
+Android builds must support both 32-bit and 64-bit CPU architectures. When you [bundle for Android](/manuals/android) you can specify which CPU architectures to include:
+
+![Signing Android bundle](images/android/sign_bundle.png)
+
+Google Play has support for [multiple APKs](https://developer.android.com/google/play/publishing/multiple-apks) per release of a game, which means that you can reduce the application size by generating two APKs, one per CPU architecture, and uploading both to Google Play.
+
+You can also make use of a combination of [APK Expansion Files](https://developer.android.com/google/play/expansion-files) and [Live Update content](/manuals/live-update) thanks to the [APKX extension in the Asset Portal](https://defold.com/assets/apkx/).

docs/en/manuals/optimization-speed.md

@@ -0,0 +1,84 @@
+---
+title: Optimizing runtime performance of a Defold game
+brief: This manual describes how to optimize a Defold game to run at a stable high frame rate.
+---
+
+# Optimizing runtime speed
+Before trying to optimize a game with the goal to make it run at a stable high frame rate you need to know where your bottlenecks are. What is actually taking up most of the time in a frame of your game? Is it the rendering? Is it your game logic? Is it the scene graph? To figure this out it is recommended to use the built-in profiling tools. Use the [on-screen or web profiler](/manuals/profiling/) to sample the performance of your game and then make a decision if and what to optimize. Once you have a better understanding of what takes time you can start addressing the problems.
+
+## Reduce script execution time
+Reducing script execution time is needed if the profiler shows high values for the `Script` scope. As a general rule of thumb you should of course try to run as little code as possible every frame. Running a lot of code in `update()` and `on_input()` every frame is likely to have an impact on your game's performance, especially on low end devices. Some guidelines are:
+
+### Use reactive code patterns
+Don't poll for changes if you can get a callback. Don't manually animate something or perform a task that can be handed over to the engine (eg go.animate vs manually animating something).
+
+### Reduce garbage collection
+If you create loads of short lived objects such as Lua tables every frame this will eventually trigger the garbage collector of Lua. When this happens it can manifest itself as small hitches/spikes in frame time. Re-use tables where you can and really try to avoid creating Lua tables inside loops and similar constructs if possible.
+
+### Pre-hash message and action ids
+If you do a lot of message handling or have many input events to deal with it is recommended to pre-hash the strings. Consider this piece of code:
+
+```
+function on_message(self, message_id, message, sender)
+    if message_id == hash("message1") then
+        msg.post(sender, hash("message3"))
+    elseif message_id == hash("message2") then
+        msg.post(sender, hash("message4"))
+    end
+end
+```
+
+In the above scenario the hashed string would be recreated every time a message is received. This can be improved by creating the hashed strings once and use the hashed versions when handling messages:
+
+```
+local MESSAGE1 = hash("message1")
+local MESSAGE2 = hash("message2")
+local MESSAGE3 = hash("message3")
+local MESSAGE4 = hash("message4")
+
+function on_message(self, message_id, message, sender)
+    if message_id == MESSAGE1 then
+        msg.post(sender, MESSAGE3)
+    elseif message_id == MESSAGE2 then
+        msg.post(sender, MESSAGE4)
+    end
+end
+```
+
+### Prefer and cache URLs
+Message passing or in other ways addressing a game object or component can be done both by providing an id as a string or hash or as a URL. If a string or hash is used it will internally be translated into a URL. It is therefore recommended to cache URLs that are used often, to get the best possible performance out of the system. Consider the following:
+
+```
+    local pos = go.get_position("enemy")
+    local pos = go.get_position(hash("enemy"))
+    local pos = go.get_position(msg.url("enemy"))
+    -- do something with pos
+```
+
+In all three cases the position of a game object with id `enemy` would be retrieved. In the first and second case the id (string or hash) would be converted into a URL before being used. This tells us that it's better to cache URLs and use the cached version for the best possible performance:
+
+```
+    function init(self)
+        self.enemy_url = msg.url("enemy")
+    end
+
+    function update(self, dt)
+        local pos = go.get_position(self.enemy_url)
+        -- do something with pos
+    end
+```
+
+## Reduce time it takes to render a frame
+Reducing the time it takes to render a frame is needed if the profiler shows high values in the `Render` and `Render Script` scopes. There are several things to consider when trying to increase reduce the time it takes to render a frame:
+
+* Reduce draw calls - Read more about reducing draw calls in [this forum post](https://forum.defold.com/t/draw-calls-and-defold/4674)
+* Reduce overdraw
+* Reduce shader complexity - Read up on GLSL optimizations in [this Kronos article](https://www.khronos.org/opengl/wiki/GLSL_Optimizations). You can also modify the default shaders used by Defold (found in `builtins/materials`) and reduce shader precision to gain some speed on low end devices. All shaders are using `highp` precision and a change to for instance `mediump` can in some cases improve performance slightly.
+
+## Reduce scene graph complexity
+Reducing the scene graph complexity is needed if the profiler shows high values in the `GameObject` scope and more specifically for the `UpdateTransform` sample. Some actions to take:
+
+* Culling - Disable game objects (and their components) if they aren't currently visible. How this is determined depends very much on the type of game. For a 2D game it can be as easy as always disabling game objects that are outside of a rectangular area. You can use a physics trigger to detect this or by partitioning your objects into buckets. Once you know which objects to disable or enable you do this by sending a `disable` or `enable` message to each game object.
+
+## Frustum culling
+The render script can automatically ignore rendering of game object component that are outside of a defined bounding box (frustum). Learn more about Frustum Culling in the [Render Pipeline manual](/manuals/render/#frustum-culling).

docs/en/manuals/optimization.md

@@ -1,178 +1,12 @@
 ---
 title: Optimizing a Defold game
-brief: This manual describes how to optimize a Defold app for size and performance.
+brief: This manual describes how to optimize a Defold game for size and performance.
 ---
 
 # Optimizing a Defold game
-It is important to understand the technical constraints of the platform(s) where your game is supposed to run and to optimize your game for the platform(s) while developing your game. There are several aspects to consider:
+It is important to understand the technical constraints of your target platforms and to design, implement and optimize your game to meet these requirements. For most platforms there are several aspects to consider:
 
-* Application size
-* Speed
-* Memory usage
-* Battery usage
-
-## Optimize application size
-Defold will create a dependency tree when building and bundling your application. The build system will start from the bootstrap collection specified in the *game.project* file and inspect every referenced collection, game object and component to build a list of the assets that are in use. It is only these assets that will get included in the final application bundle. Anything not directly referenced will get excluded. While it is good to know that unused assets will not be included you as a developer still needs to consider what goes into the final application and the size of the individual assets and the total size of the application bundle. Some target platforms and distribution channels have limitations on application size:
-
-* Apple and Google has defined application size limits when downloading over mobile networks (as opposed to downloading over Wifi).
-  * In the summer of 2019 these limits were 100 MB for Google Play and 150 MB for the Apple App Store.
-* Facebook has a recommendation that a Facebook Instant Game should start in less than 5 seconds and preferably less than 3 seconds.
-  * What this means for actual application size is not clearly defined but we are talking size in the range of up to 20 MB.
-* Playable ads are usually limited to between 2 and 5 MB depending on the ad network.
-
-::: sidenote
-According to a 2017 study it was shown that "For every 6 MB increase to an APK’s size, we see a decrease in the install conversion rate of 1%." ([source](https://medium.com/googleplaydev/shrinking-apks-growing-installs-5d3fcba23ce2))
-:::
-
-To get a better understanding of what makes up the size of your application you can [generate a build report](/manuals/bundling/#build-reports) when bundling. It is quite common that sounds and graphics is what takes up the bulk of the size of any game.
-
-### Reducing engine size
-You can use an [application manifest file](https://defold.com/manuals/project-settings/#app-manifest) to remove engine components that you do not need. You can for instance remove the included physics engines if your game doesn't use physics.
-
-### Optimize sounds
-Defold supports .ogg and .wav files where .ogg is typically used for music and .wav for sound effects. Sounds must be 16-bit with a sampling rate of 44100 so any optimizations must be done on the sounds before encoding them. You can edit the sounds in an external sound editor software to reduce the quality or convert from .wav to .ogg.
-
-### Optimize graphics
-You have several options when it comes to optimizing the graphics used by your game but the first thing to do is to check the size of the graphics that gets added to an atlas or used as a tilesource. You should never use a larger size on the graphics than is actually needed in your game. Importing large images and scaling them down to the appropriate size is a waste of texture memory and should be avoided. Start by adjusting the size of the images using external image editing software to the actual size needed in your game. For things such as background images it might also be ok to use a small image and scale it up to the desired size. Once you have the images down to the correct size and added to atlases or used in tilesources you also need to consider the size of the atlases themselves. The maximum atlas size that can be used varies between platforms and graphics hardware.
-
-::: sidenote
-[This forum posts](https://forum.defold.com/t/texture-management-in-defold/8921/17?u=britzl) suggests several tips on how to resize multiple images using scripts or third party software.
-:::
-
-* Max texture size on HTML5: https://webglstats.com/webgl/parameter/MAX_TEXTURE_SIZE
-* Max texture size on iOS:
-  * iPad: 2048x2048
-  * iPhone 4: 2048x2048
-  * iPad 2, 3, Mini, Air, Pro: 4096x4096
-  * iPhone 4s, 5, 6+, 6s: 4096x4096
-* Max texture size on Android varies greatly but in general all reasonably new devices support 4096x4096.
-
-If an atlas is too large you need to either split it into several smaller atlases or scale the entire atlas using a texture profile. The texture profile system in Defold allows you to not only scale entire atlases but also to apply compression algorithms to reduce the size of the atlas on disk. You can [read more about texture profiles in the manual](/manuals/texture-profiles/). If you don’t know what to use, try to start with these settings as a starting point for further customizations:
-
-* mipmaps: false
-* premultiply_alpha: true
-* format: TEXTURE_FORMAT_RGBA
-* compression_level: NORMAL
-* compression_type: COMPRESSION_TYPE_BASIS_UASTC
-
-::: sidenote
-You can read more about how to optimize and manage textures in [this forum post](https://forum.defold.com/t/texture-management-in-defold/8921).
-:::
-
-### Optimize fonts
-The size of your fonts will be smaller if you specify what symbols you are going to use and set this in [Extra Characters](/manuals/font/#properties) instead of using the All Chars checkbox.
-
-
-### Exclude content for download on demand
-Another way of reducing initial application size is to exclude parts of the game content from the application bundle and make this content downloadable on demand. Excluded content can be anything from entire levels to unlockable characters, skins, weapons or vehicles. Defold provides a system called Live Update for excluding content for download on demand. Learn more in the [Live Update manual](/manuals/live-update/).
-
-### Android specific size optimizations
-Android builds must support both 32-bit and 64-bit CPU architectures. When you [bundle for Android](/manuals/android) you can specify which CPU architectures to include:
-
-![Signing Android bundle](images/android/sign_bundle.png)
-
-Google Play has support for [multiple APKs](https://developer.android.com/google/play/publishing/multiple-apks) per release of a game, which means that you can reduce the application size by generating two APKs, one per CPU architecture, and uploading both to Google Play.
-
-You can also make use of a combination of [APK Expansion Files](https://developer.android.com/google/play/expansion-files) and [Live Update content](/manuals/live-update) thanks to the [APKX extension in the Asset Portal](https://defold.com/assets/apkx/).
-
-
-## Optimize for application speed
-Before trying to optimize a game with the goal to increase the speed at which the game runs you need to know where your bottlenecks are. What is actually taking up most of the time in a frame of your game? Is it the rendering? Is it your game logic? Is it the scene graph? To figure this out it is recommended to use the built-in profiling tools. Use the [on-screen or web profiler](/manuals/profiling/) to sample the performance of your game and then make a decision if and what to optimize. Once you have a better understanding of what takes time you can start addressing the problems.
-
-### Reduce script execution time
-Reducing script execution time is needed if the profiler shows high values for the `Script` scope. As a general rule of thumb you should of course try to run as little code as possible every frame. Running a lot of code in `update()` and `on_input()` every frame is likely to have an impact on your game's performance, especially on low end devices. Some guidelines are:
-
-#### Use reactive code patterns
-Don't poll for changes if you can get a callback. Don't manually animate something or perform a task that can be handed over to the engine (eg go.animate vs manually animating something).
-
-#### Reduce garbage collection
-If you create loads of short lived objects such as Lua tables every frame this will eventually trigger the garbage collector of Lua. When this happens it can manifest itself as small hitches/spikes in frame time. Re-use tables where you can and really try to avoid creating Lua tables inside loops and similar constructs if possible.
-
-#### Pre-hash message and action ids
-If you do a lot of message handling or have many input events to deal with it is recommended to pre-hash the strings. Consider this piece of code:
-
-```
-function on_message(self, message_id, message, sender)
-    if message_id == hash("message1") then
-        msg.post(sender, hash("message3"))
-    elseif message_id == hash("message2") then
-        msg.post(sender, hash("message4"))
-    end
-end
-```
-
-In the above scenario the hashed string would be recreated every time a message is received. This can be improved by creating the hashed strings once and use the hashed versions when handling messages:
-
-```
-local MESSAGE1 = hash("message1")
-local MESSAGE2 = hash("message2")
-local MESSAGE3 = hash("message3")
-local MESSAGE4 = hash("message4")
-
-function on_message(self, message_id, message, sender)
-    if message_id == MESSAGE1 then
-        msg.post(sender, MESSAGE3)
-    elseif message_id == MESSAGE2 then
-        msg.post(sender, MESSAGE4)
-    end
-end
-```
-
-#### Prefer and cache URLs
-Message passing or in other ways addressing a game object or component can be done both by providing an id as a string or hash or as a URL. If a string or hash is used it will internally be translated into a URL. It is therefore recommended to cache URLs that are used often, to get the best possible performance out of the system. Consider the following:
-
-```
-    local pos = go.get_position("enemy")
-    local pos = go.get_position(hash("enemy"))
-    local pos = go.get_position(msg.url("enemy"))
-    -- do something with pos
-```
-
-In all three cases the position of a game object with id `enemy` would be retrieved. In the first and second case the id (string or hash) would be converted into a URL before being used. This tells us that it's better to cache URLs and use the cached version for the best possible performance:
-
-```
-    function init(self)
-        self.enemy_url = msg.url("enemy")
-    end
-
-    function update(self, dt)
-        local pos = go.get_position(self.enemy_url)
-        -- do something with pos
-    end
-```
-
-### Reduce time it takes to render a frame
-Reducing the time it takes to render a frame is needed if the profiler shows high values in the `Render` and `Render Script` scopes. There are several things to consider when trying to increase reduce the time it takes to render a frame:
-
-* Reduce draw calls - Read more about reducing draw calls in [this forum post](https://forum.defold.com/t/draw-calls-and-defold/4674)
-* Reduce overdraw
-* Reduce shader complexity - Read up on GLSL optimizations in [this Kronos article](https://www.khronos.org/opengl/wiki/GLSL_Optimizations). You can also modify the default shaders used by Defold (found in `builtins/materials`) and reduce shader precision to gain some speed on low end devices. All shaders are using `highp` precision and a change to for instance `mediump` can in some cases improve performance slightly.
-
-### Reduce scene graph complexity
-Reducing the scene graph complexity is needed if the profiler shows high values in the `GameObject` scope and more specifically for the `UpdateTransform` sample. Some actions to take:
-
-* Culling - Disable game objects (and their components) if they aren't currently visible. How this is determined depends very much on the type of game. For a 2D game it can be as easy as always disabling game objects that are outside of a rectangular area. You can use a physics trigger to detect this or by partitioning your objects into buckets. Once you know which objects to disable or enable you do this by sending a `disable` or `enable` message to each game object.
-
-
-## Optimize memory usage
-This section is not yet finished. Topics that will be covered:
-
-* [Texture compression](/manuals/texture-profiles/)
-* [Dynamic loading of collections](https://www.defold.com/manuals/collection-proxy/)
-* [Dynamic loading of factories](https://www.defold.com/manuals/collection-factory/#dynamic-loading-of-factory-resources)
-* [Profiling](/manuals/profiling/)
-
-
-### Tweak component counters
-Check counters for components in `game.project`. Use the [profiler](/manuals/profiling/) to get accurate component and resource usage and configure your game to use max values that are closer to the real count of components and resources. This will reduce the amount of memory your game is using (refer to information about component [max count optimizations](/manuals/project-settings/#component-max-count-optimizations)).
-
-### Heap size (HTML5 only)
-Make sure you set a minimal heap size for your game. Launch your game and play the game in the most "resource heavy" level or section. Open the developer tools of your browser and write `HEAP8.length / 1024 / 1024` in the console. Take this number add 10-15% and set it as your [Heap Size](/manuals/project-settings/#heap-size) in `game.project`.
-
-
-## Optimize battery usage
-This section is not yet finished. Topics that will be covered:
-
-* Running code every frame
-* Accelerometer on mobile
-* [Profiling](/manuals/profiling/)
+* [Game size](/manuals/optimization-size) - What is the maximum acceptable size of the game bundle and how can you make the game as small as possible without compromising on quality?
+* [Runtime speed](/manuals/optimization-speed) - What is the performance of the target platform and how can you make the game run with a stable frame rate at minimal CPU and/or GPU usage?
+* [Memory usage](/manuals/optimization-memory) - What are the memory constraints of the target platform and how can you reduce memory usage?
+* [Battery usage](/manuals/optimization-battery) - This is mainly a focus area if you are targeting mobile/handheld devices.

docs/en/shared/optimization-memory-html5.md

@@ -0,0 +1,21 @@
+## Heap size
+The heap size of a Defold HTML5 game can be configured from the [`heap_size` field](/manuals/project-settings/#heap-size) in *game.project*. Make sure to optimize memory usage of your game and set a minimal heap size.
+
+For small games, 32 MB is an achievable heap size. For larger games, aim for 64–128 MB. If, for example, you're at 58 MB and further optimization isn't feasible, you can settle on 64 MB without overthinking it. There’s no strict target size — it depends on the game. Just aim for smaller sizes, ideally in steps of powers of two. 
+
+To check current heap usage you can launch your game and play the game in the most "resource heavy" level or section and monitor memory usage:
+
+```lua
+if html5 then
+    local mem = tonumber(html5.run("HEAP8.length") / 1024 / 1024)
+    print(mem)
+end
+```
+
+You can also open the developer tools of your browser and write the following in the console:
+
+```js
+HEAP8.length / 1024 / 1024
+```
+
+If the memory usage remains at 32 MB, that's great! If not, follow the steps to [optimize memory usage](/manuals/optimization-memory).