Add note on component max count optimizations

docs/en/manuals/project-settings.md

@@ -13,7 +13,9 @@ Every setting in the file belongs to a category. When you open the file Defold p
 
 Below are all the available settings, arranged by section. Some settings are not yet exposed in the settings editor (these are marked "hidden setting" below), but can be set manually by right clicking "game.project" and selecting <kbd>Open With ▸ Text Editor</kbd>.
 
-## Project
+## Sections and settings
+
+### Project
 
 #### Title
 The title of the application.
@@ -47,7 +49,9 @@ A comma separated list of directories containing resource files and folders that
 #### Bundle Exclude Resources
 A comma separated list of resources that should not be included in the bundle.
 
-## Bootstrap
+---
+
+### Bootstrap
 
 #### Main Collection
 File reference of the collection to use for starting the application, `/logic/main.collection` by default.
@@ -55,22 +59,28 @@ File reference of the collection to use for starting the application, `/logic/ma
 #### Render
 Which render setup file to use, which defines the render pipeline, `/builtins/render/default.render` by default.
 
-## Library
+---
+
+### Library
 
 #### Include Dirs
 A space separated list of directories that should be shared from your project via library sharing.
 
-## Script
+---
+
+### Script
 
 #### Shared State
 Check to share a single Lua state between all script types, unchecked by default.
 
-## Engine
+---
+
+### Engine
 
 #### Run While Iconified
 Allow the engine to continue running while the application window is iconified (desktop platforms only), `false` by default.
 
-## Display
+### Display
 
 #### Width
 The width in pixels of the application window, `960` by default.
@@ -88,10 +98,10 @@ How many samples to use for super sampling anti-aliasing. It sets the GLFW_FSAA_
 Check if the application should start full screen. If unchecked, the application runs windowed.
 
 #### Frame Cap
-If `Vsync` checked, snaps to the closest matching swap interval for the set frame cap if a monitor is detected. Otherwise uses timers to respect the set value, 0 means no cap. This setting maps to `display.update_frequency`.
+If `Vsync` checked, snaps to the closest matching swap interval for the set frame cap if a monitor is detected. Otherwise uses timers to respect the set value, 0 means no cap. This setting maps to `display.update_frequency`. ([See below](#vsync-frame-cap-and-swap-interval)).
 
 #### Vsync
-Vertical sync, rely on hardware vsync for frame timing. Can be overridden depending on graphics driver and platform specifics.
+Vertical sync, rely on hardware vsync for frame timing. Can be overridden depending on graphics driver and platform specifics. ([See below](#vsync-frame-cap-and-swap-interval)).
 
 #### Display Profiles
 Specifies which display profiles file to use, `/builtins/render/default.display_profilesc` by default. Learn more in the [GUI Layouts manual](/manuals/gui-layouts/#creating-display-profiles).
@@ -99,7 +109,9 @@ Specifies which display profiles file to use, `/builtins/render/default.display_
 #### Dynamic Orientation
 Check if the app should dynamically switch between portrait and landscape on device rotation. Note that the development app does not currently respect this setting.
 
-## Render
+---
+
+### Render
 
 #### Clear Color Red
 Clear color red channel, used by the render script and when the window is created. Added in 1.2.167.
@@ -113,7 +125,9 @@ Clear color blue channel, used by the render script and when the window is creat
 #### Clear Color ALpha
 Clear color alpha channel, used by the render script and when the window is created. Added in 1.2.167.
 
-## Physics
+---
+
+### Physics
 
 #### Type
 Which type of physics to use, `2D` (default) or `3D`.
@@ -163,7 +177,9 @@ The max number of 3d ray cast requests per frame. `128` by default.
 #### Trigger Overlap Capacity
 The maximum number of overlapping physics triggers. `16` by default.
 
-## Graphics
+---
+
+### Graphics
 
 #### Default Texture Min Filter
 Specifies which filtering to use for minification filtering, `linear` (default) or `nearest`.
@@ -183,12 +199,14 @@ The maximum number of debug vertices. Used for physics shape rendering among oth
 #### Texture Profiles
 The texture profiles file to use for this project, `/builtins/graphics/default.texture_profiles` by default.
 
-## Shader
+### Shader
 
 #### Output SPIR-V
 Compile and output SPIR-V shaders for use with Metal or Vulkan.
 
-## Input
+---
+
+### Input
 
 #### Repeat Delay
 Seconds to wait before a held down input should start repeating itself, `0.5` by default.
@@ -205,7 +223,9 @@ File reference of the input config file, which maps hardware inputs to actions,
 #### Use Accelerometer
 Check to make the engine receive accelerator input events each frame. Disabling accelerometer input may give some performance benefit, checked by default.
 
-## Resource
+---
+
+### Resource
 
 #### Http Cache
 If checked, a HTTP cache is enabled for faster loading of resources over the network to the running engine on device, unset by default.
@@ -216,12 +236,16 @@ Where to find the project build data, in URI format.
 #### Max Resources
 The max number of resources that can be loaded at the same time, `1024` by default.
 
-## Network
+---
+
+### Network
 
 #### Http Timeout
 The HTTP timeout in seconds. Set to `0` to disable timeout, which is the default.
 
-## Collection
+---
+
+### Collection
 
 #### Max Instances
 Max number of game object instances in a collection, `1024` by default.
@@ -229,7 +253,9 @@ Max number of game object instances in a collection, `1024` by default.
 #### Max Input Stack Entries
 Max number of game objects in the input stack, `16` by default.
 
-## Sound
+---
+
+### Sound
 
 #### Gain
 Global gain (volume), `0`--`1`, The value is `1` by default.
@@ -249,41 +275,53 @@ Max number of concurrent sound instances, i.e. actual sounds played at the same
 #### Use Thread
 If checked, the sound system will use threads for sound playback to reduce risk of stutter when the main thread is under heavy load. Checked by default.
 
-## Sprite
+---
+
+### Sprite
 
 #### Max Count
-Max number of sprites per collection, `128` by default.
+Max number of sprites per collection, `128` by default. [(See information about component max count optimizations)](#component_max_count_optimzations).
 
 #### Subpixels
 Check to allow sprites to appear unaligned with respect to pixels, checked by default.
 
-## Tilemap
+---
+
+### Tilemap
 
 #### Max Count
-Max number of tile maps per collection, `16` by default.
+Max number of tile maps per collection, `16` by default. [(See information about component max count optimizations)](#component_max_count_optimzations).
 
 #### Max Tile Count
 Max number of concurrent visible tiles per collection, `2048` by default.
 
-## Spine
+---
+
+### Spine
 
 #### Max Count
-Max number of spine models, `128` by default.
+Max number of spine model components, `128` by default. [(See information about component max count optimizations)](#component_max_count_optimzations).
 
-## Mesh
+---
+
+### Mesh
 
 #### Max Count
-Max number of mesh components per collection, `128` by default.
+Max number of mesh components per collection, `128` by default. [(See information about component max count optimizations)](#component_max_count_optimzations).
 
-## Model
+---
+
+### Model
 
 #### Max Count
-Max number of model components per collection, `128` by default.
+Max number of model components per collection, `128` by default. [(See information about component max count optimizations)](#component_max_count_optimzations).
+
+---
 
-## GUI
+### GUI
 
 #### Max Count
-Max number of GUI components, `64` by default.
+Max number of GUI components, `64` by default. [(See information about component max count optimizations)](#component_max_count_optimzations).
 
 #### Max Particlefx Count
 The max number of concurrent emitters, `64` by default.
@@ -291,38 +329,50 @@ The max number of concurrent emitters, `64` by default.
 #### Max Particle Count
 The max number of concurrent particles, `1024` by default.
 
-## Label
+---
+
+### Label
 
 #### Max Count
-Max number of labels, `64` by default.
+Max number of labels, `64` by default. [(See information about component max count optimizations)](#component_max_count_optimzations).
 
 #### Subpixels
 Check to allow lables to appear unaligned with respect to pixels, checked by default.
 
-## Particle FX
+---
+
+### Particle FX
 
 #### Max Count
-The max number of concurrent emitters, `64` by default.
+The max number of concurrent emitters, `64` by default. [(See information about component max count optimizations)](#component_max_count_optimzations).
 
 #### Max Particle Count
 The max number of concurrent particles, `1024` by default.
 
-## Collection proxy
+---
+
+### Collection proxy
 
 #### Max Count
-Max number of collection proxies, `8` by default.
+Max number of collection proxies, `8` by default. [(See information about component max count optimizations)](#component_max_count_optimzations).
+
+---
 
-## Collection factory
+### Collection factory
 
 #### Max Count
-Max number of collection factories, `128` by default.
+Max number of collection factories, `128` by default. [(See information about component max count optimizations)](#component_max_count_optimzations).
+
+---
 
-## Factory
+### Factory
 
 #### Max Count
-Max number of game object factories, `128` by default.
+Max number of game object factories, `128` by default. [(See information about component max count optimizations)](#component_max_count_optimzations).
 
-## iOS
+---
+
+### iOS
 
 #### App Icon 57x57--180x180
 Image file (.png) to use as application icon at given width and height dimensions `W` &times; `H`.
@@ -351,7 +401,9 @@ The language used if the application doesn't have user's preferred language in `
 #### Localizations
 This field contains comma-separated strings identifying the language name or ISO language designator of the supported localizations (see [CFBundleLocalizations](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-109552)).
 
-## Android
+---
+
+### Android
 
 #### App Icon 36x36--192x192
 Image file (.png) to use as application icon at given width and height dimensions `W` &times; `H`.
@@ -389,7 +441,9 @@ If set, hides the navigation and status bars and lets your app capture all touch
 #### Debuggable
 Whether or not the application can be debugged using tools such as [GAPID](https://github.com/google/gapid) or [Android Studio](https://developer.android.com/studio/profile/android-profiler). This will set the `android:debuggable` flag in the Android manifest.
 
-## macOS
+---
+
+### macOS
 
 #### App Icon
 Image file (.png) to use as application icon on macOS.
@@ -406,7 +460,9 @@ The language used if the application doesn't have user's preferred language in `
 #### Localizations
 This field contains comma-separated strings identifying the language name or ISO language designator of the supported localizations (see [CFBundleLocalizations](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-109552)).
 
-## Windows
+---
+
+### Windows
 
 #### App Icon
 Image file (.ico) to use as application icon on Windows. Read more about how to create a .ico file in the [Windows manual](/manuals/windows).
@@ -414,7 +470,9 @@ Image file (.ico) to use as application icon on Windows. Read more about how to
 #### Iap Provider
 Specifies which store to use. Valid options are `None` and `Gameroom`, `None` by default.
 
-## HTML5
+---
+
+### HTML5
 
 #### Heap Size
 Heap size (number of megabytes) for Emscripten to use. By default this value is 256MB.
@@ -446,12 +504,16 @@ Enables Made With Defold link in `index.html` file. By default `true`.
 #### Scale Mode
 Specifies which method to use to scale the game canvas. By default `Downscale Fit`.
 
-## IAP
+---
+
+### IAP
 
 #### Auto Finish Transactions
 Check to automatically finish IAP transactions. If unchecked, you need to explicitly call `iap.finish()` after a successful transaction, checked by default.
 
-## Live update
+---
+
+### Live update
 
 #### Private Key
 If set, use the specified private key file when bundling live update content. If no key file is set, a key is generated.
@@ -459,16 +521,22 @@ If set, use the specified private key file when bundling live update content. If
 #### Public Key
 If set, use the specified public key file when bundling live update content. If no key file is set, a key is generated.
 
-## Native extension
+---
+
+### Native extension
 
 #### _App Manifest_
 If set, use the app manifest to customize the engine build. This allows you to remove unneeded parts from the engine making it possible to decrease the final binary size. Note that this feature is in alpha state. Please visit [the forum](https://forum.defold.com/t/native-extensions/4946/142) for information on how to proceed.
 
-## Profiler
+---
+
+### Profiler
 
 #### Track Cpu
 If checked, enable CPU profiling in release versions of the builds. Normally, you can only access profiling information in debug builds.
 
+---
+
 ## File format
 
 The format of the settings file is simple text (INI format) and can be edited by any standard text editor. The format looks like this:
@@ -492,6 +560,7 @@ which means that the setting *main_collection* belongs to the *bootstrap* catego
 Whenever a file reference is used, like the example above, the path needs to be appended with a 'c' character, which means you're referencing the compiled version of the file.
 Also note that the folder containing *game.project* will be the project root, which is why there is an initial '/' in the setting path.
 
+
 ## Setting config values on engine startup
 
 When the engine starts, it is possible to provide config values from the command line that override the *game.project* settings:
@@ -510,6 +579,18 @@ Custom values can---just like any other config value---be read with [`sys.get_co
 local my_value = tonumber(sys.get_config("test.my_value"))
 ```
 
+
+## Component max count optimzations
+The `game.project` settings file contains many values specifying the maximum number of a certain resource that can exist at the same time, often counted per loaded collection (also called world). The Defold engine will use these max values to preallocate memory for this amount of memory to avoid dynamic allocations and memory fragmentation while the game is running.
+
+The Defold data structures used to represent components and other resources are optimized to use as little memory as possible but care should still be taken when setting the values to avoid allocating more memory than is actually necessary.
+
+To further optimize memory usage the Defold build process will analyse the content of the game and override the max counts if it is possible to know for certain the exact amount:
+
+* If a collection doesn't contain any factory components the exact amount of each component will be allocated and the max count values will be ignored.
+* If a collection contains a factory component the spawned objects will be analysed and the max count will be used for components that can be spawned from the factories.
+
+
 ## Vsync, frame cap, and swap interval
 The first thing of note is that on desktop platforms vsync can be controlled globally by graphics card settings. If for example vsync is force-enabled in the graphics control panel it is not user controllable, e.g. the setting cannot be accessed or modified from Defold. Most mobile devices also has vsync enabled by default.
 
@@ -517,6 +598,7 @@ With `Vsync` checked in `game.project` the engine relies on hardware vsync and u
 
 Swap interval is the interval with which to swap the front and back buffers in sync with vertical blanks (v-blank), the hardware event where the screen image is updated with data from the front buffer. A value of 1 swaps the buffers at every v-blank, a value of 2 swaps the buffers every other v-blank and so on. A value of 0 disables waiting for v-blank before swapping the buffers\*. Setting `swap_interval` is done by calling the [```set_vsync_swap_interval```](/ref/sys/#sys.set_vsync_swap_interval:swap_interval) function.
 
+
 ### Caveat
 Currently, Defold queries for monitor refresh rate at init and uses that as a basis for picking a fixed `dt`. If you want to support monitors using variable refresh rate (GSync or FreeSync for example) or other scenarios where the refresh rate might not be trivial to query, uncheck `Vsync`to let the engine measure actual `dt` each frame instead of relying on a fixed time step.