The file game.project contains all project wide settings. It must stay in the root folder of the project and must be named game.project. The first thing the engine does when starting up and launching your game is look for this file.
Every setting in the file belongs to a category. When you open the file Defold presents all settings grouped by category.
The settings in game.project are usually changed from within Defold, but the file can also be edited in any standard text editor. The file follows the INI file format standard and looks like this:
[category1]
setting1 = value
setting2 = value
[category2]
...
A real example is:
[bootstrap]
main_collection = /main/main.collectionc
which means that the setting main_collection belongs to the bootstrap category. 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.
It is possible to read values from game.project at runtime using sys.get_config_string(key), sys.get_config_number(key), sys.get_config_int(key), and sys.get_config_boolean(key). Examples:
local title = sys.get_config_string("project.title")
local gravity_y = sys.get_config_number("physics.gravity_y")
local fullscreen = sys.get_config_boolean("display.fullscreen", false)
The key is a combination of the category and setting name, separated by a dot, and written in lowercase letters with any space characters replaced by underscores. Examples: The field “Title” from the “Project” category becomes project.title and the “Gravity Y” field from the “Physics” category becomes physics.gravity_y.
Below are all the available settings, arranged by category.
The title of the application.
The version of the application.
Publisher name.
Developer name.
Controls when the engine writes a log file. Options:
If running more than one instance from the editor the file will be named instance_2_log.txt with 2 being the instance index. If running a single instance or from a bundle the file will be named log.txt. The location of the log file will be one of the following paths (tried in order):
NSDocumentDirectoryContext.getExternalFilesDir()NSApplicationSupportDirectoryCSIDL_APPDATA (e.g. C:\Users\\AppData\Roaming)Context.getFilesDir()HOME environment variableSpecify the minimum log level for the logging system. Only logs at or above this level will be shown.
Enables compression of archives when bundling. Note that this currently applies to all platforms except Android where the apk already contains all data compressed.
A list of URLs to the project Library URLs. Refer to the Libraries manual for more information.
project.dependencies_metadata includes metadata about library dependencies in the runtime bundle. Disabled by default. The metadata can be read at runtime using sys.load_resource("/.internal/dependencies.json").
custom_resources
Custom resources are bundled in the main game archive using the Custom Resources field in game.project.
The Custom Resources field should contain a comma separated list of resources that will be included in the main game archive. If directories are specified, all files and directories in that directory are recursively included. You can read the files using sys.load_resource().
Loading custom resources is covered in more detail in the File Access manual.
Paths contributed by extensions through custom_resources.default in ext.properties are combined with this setting. See extension custom resources for an example.
bundle_resources
Bundle resources are additional files and folders located as a part of your application bundle using the Bundle Resources field in game.project.
The Bundle Resources field should contain a comma separated list of directories containing resource files and folders that should be copied as-is into the resulting package when bundling. The directories must be specified with an absolute path from the project root, for example /res. The resource directory must contain subfolders named by platform, or architecture-platform.
Supported platforms are ios, android, osx, win32, linux, web, switch A subfolder named common is also allowed, containing resource files common for all platforms. Example:
res
├── win32
│ └── mywin32file.txt
├── common
│ └── mycommonfile.txt
└── android
├── myandroidfile.txt
└── res
└── xml
└── filepaths.xml
You can use sys.get_application_path() to get the path to where the application is stored. Use this application base path to create the final absolute path to the files you need access to. Once you have the absolute path of these files you can use the io.* and os.* functions to access the files.
Loading bundle resources is covered in more detail in the File Access manual.
bundle_exclude_resources
A comma separated list of resources that should not be included in the bundle. That is, they’re removed from the result of the collection of the bundle_resources step.
A space separated list of directories that should be shared from your project via library sharing. Refer to the Libraries manual for more information.
library.defold_min_version specifies the minimum Defold/Bob version required to use this project as a library, for example 1.11.2. Leave empty to specify no minimum version.
On desktop platforms, engine windows opened from the editor can restore a size saved during an earlier run. Choose Debug ▸ Reset Simulated Resolution to clear remembered sizes and return to the configured size while keeping saved window positions. See engine window placement and reset for details.
The width in pixels of the application window.
The height in pixels of the application window.
Creates a high dpi back buffer on displays that support it. Typically the game will render in double the resolution than what is set in the Width and Height settings, which will still be the logical resolution used in scripts and properties.
On HTML5, use Min Pixel Ratio and Max Pixel Ratio to bound the rendering scale when this setting is enabled.
How many samples to use for super sampling anti-aliasing. It sets the GLFW_FSAA_SAMPLES window hint. A value of 0 means that anti-aliasing is turned off.
This setting controls the window. Offscreen multisampled render targets have their own sample count.
Check if the application should start full screen. If unchecked, the application runs windowed.
The desired frame rate in Hertz. Set to 0 for variable frame rate. A value larger than 0 will result in a fixed frame rate capped at runtime towards the actual frame rate (which means that you cannot update the game loop twice in an engine frame). Use sys.set_update_frequency(hz) to change this value at runtime. This setting also works in headless builds.
This integer value controls how the application deals with vsync. 0 disables vsync, and the default value is 1. When using an OpenGL adapter, this value sets the number of frames the window should update between buffer swaps. For Vulkan, there is no built-in concept of swap interval, the value instead controls if vsync should be enabled or not.
Legacy compatibility setting. This setting is deprecated; use Swap Interval for new projects. If disabled, it forces the effective swap interval to 0. If enabled, Swap Interval determines the effective value.
Specifies which display profiles file to use, /builtins/render/default.display_profilesc by default. Learn more in the GUI Layouts manual.
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.
Output GPU info to console at startup.
Max number of collision objects.
Which type of physics to use, 2D or 3D.
World gravity along x-axis. In meters per second.
World gravity along y-axis. In meters per second.
World gravity along z-axis. In meters per second.
Check if physics should be visualized for debugging.
Alpha component value for visualized physics, 0–1.
Max number of concurrent physics worlds, 4 by default. If you load more than 4 worlds simultaneously through collection proxies you need to increase this value. Be aware that each physics world allocates a fair amount of memory.
Tells the physics engine how to scale the physics worlds in relation to the game world for numerical precision, 0.01–1.0. If the value is set to 0.02, it means that the physics engine will view 50 units as 1 meter ($1 / 0.02$).
Check if the physics engine should apply the transform of a game object to any attached collision object components. This can be used to move, scale and rotate collision shapes, even those that are dynamic.
Check if the physics engine should use fixed and framerate independent updates. Use this setting in combination with the fixed_update(self, dt) lifecycle function and the engine.fixed_update_frequency project setting to interact with the physics engine at regular intervals. For new projects the recommended setting is true.
How big to draw unit objects in physics, like triads and normals.
How many collisions that will be reported back to the scripts.
How many contact points that will be reported back to the scripts.
Ignore contact impulses with values less than this setting.
The max number of 2d ray cast requests per frame.
The max number of 3d ray cast requests per frame.
The maximum number of overlapping physics triggers.
Minimum velocity that will result in elastic collisions.
Max number of steps in the simulation when using fixed timestep (3D only).
shader.exclude_gles_sm100 excludes shaders for OpenGLES 2.0 and WebGL 1.0. Enabled by default (1).
To target these graphics APIs or allow fallback to them, uncheck Shader ▸ Exclude GLES 2.0 in game.project, or set:
[shader]
exclude_gles_sm100 = 0
Projects that do not explicitly set this option use the default. Set it to 0 explicitly if the project needs OpenGLES 2.0 or WebGL 1.0 support.
shader.glsl_es_default_precision_float sets the default global precision qualifier for floating-point values in cross-compiled GLSL ES shaders. Valid values are mediump and highp; the default is mediump.
shader.glsl_es_default_precision_int sets the default global precision qualifier for integer values in cross-compiled GLSL ES shaders. Valid values are mediump and highp; the default is highp.
If checked, a HTTP cache is enabled for faster loading of resources over the network to the running engine on device.
Where to find the project build data, in URI format.
The max number of resources that can be loaded at the same time.
resource.profile enables resource loading timings and INFO-level logs for each completed or failed load. Disabled by default (0). Enable it (1) before launching the game to measure startup loads. The resource profiler shows retained initial-load measurements for currently loaded resources; click Capture, then Show load times to inspect them. See Resource loading times for the timing columns and how to interpret them.
Max number of game object instances in a collection, 1024 by default. (See information about component max count optimizations).
Max number of game objects in the input stack.
Max number of sprites per collection. (See information about component max count optimizations).
Check to allow sprites to appear unaligned with respect to pixels.
Max number of spine model components. (See information about component max count optimizations).
Max number of model components per collection. (See information about component max count optimizations).
Split meshes with more than 65536 vertices into new meshes.
Maximum width of the bone matrix texture. Only the size needed for animations is used, rounded up to nearest power-of-two.
Maximum height of the bone matrix texture. Only the size needed for animations is used, rounded up to nearest power-of-two.
model.max_morph_target_texture_width sets the maximum width in pixels of the texture generated per mesh for morph target position, normal, and tangent deltas. The default is 1024.
model.max_morph_target_texture_height sets the maximum height in pixels of the texture generated per mesh for morph target position, normal, and tangent deltas. The default is 1024.
Max number of GUI components. (See information about component max count optimizations).
The max number of concurrent particles in GUI.
gui.max_particlefx_count sets the maximum number of particle FX nodes per collection. The default is 64.
The max number of active animations in gui.
gui.safe_area_mode selects which safe-area insets affect GUI adjustment:
none (default): Ignore the insets.long: Apply left/right insets in landscape and top/bottom insets in portrait.short: Apply top/bottom insets in landscape and left/right insets in portrait.both: Apply all four insets.A GUI script can override the mode for its scene with gui.set_safe_area_mode(). See the safe area guidance for platform support and custom layouts.
particle_fx.max_count sets the maximum number of particle FX components, 64 by default. (See information about component max count optimizations).
particle_fx.max_emitter_count sets the maximum number of concurrent particle FX emitters. The default is 64.
The max number of concurrent particles. This limits the GPU vertex buffer size, 1024 particles by default.
particle_fx.max_particle_buffer_count sets the maximum number of particles per upload to the GPU. This limits the CPU buffer used to generate particle vertices. The default is 1024.
Max number of collection proxies. (See information about component max count optimizations).
Max number of game object factories. (See information about component max count optimizations).
Image file (.png) to use as application icon at given width and height dimensions W × H.
Image files (.png) to be used as custom push notification icon on Android. The icons will automatically be used for both local or remote push notifications. If not set the application icon will be used by default.
Specifies which payload JSON field should be used as notification title. Leaving this setting empty makes the pushes default to the application name as title.
Specifies which payload JSON field should be used as notification text. If left empty, the text in the field alert is used, just as on iOS.
An integer value indicating the version of the app. Increase the value for each subsequent update.
The minimum API Level required for the application to run (android:minSdkVersion).
The API Level that the application targets (android:targetSdkVersion).
Package identifier. Must consist of two or more segments separated by a dot. Each segment must start with a letter. Each segment must only consist of alphanumeric letters or the underscore character.
Google Cloud Messaging Sender Id. Set this to the string assigned by Google to enable push notifications.
Firebase Cloud Messaging Application Id.
If set, use the specified Android manifest XML file when bundling. A custom manifest replaces Defold’s built-in base manifest. Native-extension manifest fragments are still merged into it, but later changes to the built-in base manifest are not inherited automatically, so compare custom manifests with the current built-in manifest when upgrading. For games, set android:appCategory="game" on the `` element. For non-game applications, set android:appCategory only if one of Android’s defined application categories accurately describes the app.
Specifies which store to use. Valid options are Amazon and GooglePlay. Refer to extension-iap for more information.
Specifies which method to use to get keyboard input on Android devices. Valid options are KeyEvent (old method) and HiddenInputField (new).
If set, hides the navigation and status bars and lets your app capture all touch events on the screen.
Extend to display cutout.
Whether or not the application can be debugged using tools such as GAPID or Android Studio. This will set the android:debuggable flag in the Android manifest (official documentation).
android.r8_keep_rules selects a .keep file to enable R8 shrinking, optimization and obfuscation of Java code in Android builds. Leave the setting empty to use D8 without shrinking.
With a compatible Extender build server, this also removes unused Android resources. Resources loaded dynamically may need separate XML keep rules.
Select /builtins/manifests/android/dmengine.keep to use Defold’s default rules directly. Extensions supply their own keep rules, which are combined with this file.
Only copy the built-in file into your project if you need to add project-specific rules. Preserve the built-in rules in the copy: selecting a custom file replaces the complete project rule set.
See the Android manual for enabling R8 and retaining its obfuscation mapping with a release bundle.
Specifies whether the package installer extracts native libraries from the APK to the file system. If set to false, your native libraries are stored uncompressed in the APK. Although your APK might be larger, your application loads faster because the libraries load directly from the APK at runtime. This will set the android:extractNativeLibs flag in the Android Manifest (official documentation).
Image file (.ico) to use as application icon on Windows. Read more about how to create a .ico file in the Windows manual.
Check to automatically finish IAP transactions. If unchecked, you need to explicitly call iap.finish() after a successful transaction.
If set, use the app manifest to customize the engine build. This allows you to remove unused parts from the engine to decrease the final binary size. Learn how to exclude unused feature in the application manifest manual.
The App Manifest Profiler setting controls whether profiler code is linked into debug and release builds. The settings below control the runtime behavior of profiler code that is present in the selected build. See the Profiling manual for details.
Enable the in-game profiler.
CPU usage sampling is enabled by default in debug builds. Enable this setting when CPU sampling is also needed in a release build that includes profiler support through the App Manifest.
profiler.track_detailed_memory enables detailed memory sampling in the profiler. Disabled by default. This can be expensive on HTML5.
Number of milliseconds to sleep between server updates.
Enable in-browser performance timeline (HTML5 only).
profiler.max_sample_count is the maximum number of profiler samples recorded per thread per frame. The default is 4096 and the minimum is 128. Increase this only when a legitimate profile exceeds the limit; first check native-extension profiling code for mismatched scope begin/end calls.
When the engine starts, it is possible to provide config values from the command line that override the game.project settings:
# Specify a bootstrap collection
$ dmengine --config=bootstrap.main_collection=/my.collectionc
# Set two custom config values
$ dmengine --config=test.my_value=4711 --config=test2.my_value2=foobar
Custom values can—just like any other config value—be read with the matching function described under Runtime access:
local my_value = sys.get_config_number("test.my_value")
local my_value2 = sys.get_config_string("test.my_value2")
local my_flag = sys.get_config_boolean("test.my_flag", false)
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:
It is possible to define custom settings for the main project or for a native extension. Custom settings for the main project must be defined in a game.properties file in the project root. Files named ext.properties are discovered anywhere in the project and fetched library dependencies; they do not require a neighboring ext.manifest. All discovered extension metadata is merged, after which the root game.properties file is applied and can override it.
The settings file uses the same INI format as game.project and property attributes are defined using a dot notation with a suffix:
[my_category]
my_property.private = 1
...
The default meta file that is always applied is available here
The following attributes are currently available:
[my_extension]
// `type` - used for the value string parsing
my_property.type = string // one of the following values: bool, string, number, integer, string_array, resource
// `help` - displayed as a help tooltip in the editor
my_property.help = string
// `default` - value used as default if user didn't set value manually
my_property.default = string
// `private` - private value used during the bundle process but will be removed from the bundle itself
my_property.private = 1 // boolean value 1 or 0
// `label` - editor input label
my_property.label = My Awesome Property
// `minimum` and/or `maximum` - valid range for numeric properties, validated in the editor UI
my_property.minimum = 0
my_property.maximum = 255
// `options` - drop-down choices for the editor UI, comma-separated value[:label] pairs
my_property.options = android: Android, ios: iOS
// `resource` type only:
my_property.filter = jpg,png // allowed file extensions for resource selector dialog
my_property.preserve-extension = 1 // use original resource extension instead of a built one
// deprecation
my_property.deprecated = 1 // mark property as deprecated
my_property.severity-default = warning // if deprecated property is specified, but set to a default value
my_property.severity-override = error // if deprecated property is specified and set to a non-default value
Additionally, you can set the following attributes on a setting category:
[my_extension]
// `group` - game.project category group, e.g. Main, Platforms, Components, Runtime, Distribution
group = Runtime
// `title` - displayed category title
title = My Awesome Extension
// `help` - displayed category help
help = Settings for My Awesome Extension
Both Bob and the Editor parse these metadata files. The Editor uses them to create the corresponding fields, choices, validation, and help tooltips in the game.project viewer.