Defold

Defold is a free, lightweight game engine whose small runtime is a natural fit for instant-loading Games.

Quick Start#

Step 1: Set Up Your Defold Project#

Install Defold from defold.com and build your game as usual (official manuals). For the Minit Games feed, set the design display dimensions in game.project to portrait:

[display]
width = 960
height = 1480

This is the design resolution your UI is laid out against. Step 4 makes the game fill any actual screen.

Step 2: Add the Minit SDK#

Add the SDK as a library dependency in game.project, then Project > Fetch Libraries:

[project]
dependencies = https://github.com/Minit-Games/minit-defold/archive/refs/tags/v0.1.0.zip

Prefer the tag-pinned URL: .../archive/refs/heads/master.zip tracks latest and can change under you. After fetching, minit/ appears as a read-only library folder and require("minit.minit") resolves. No dependencies beyond Defold's built-in html5 and json modules.

Fallback (no editor / quick try / offline):

Download the Minit SDK (minit.lua)

Drop the file into your project under a minit/ folder (so it lives at minit/minit.lua). require("minit.minit") resolves the same way.

Step 3: Import & Use the API#

local minit = require("minit.minit")

-- Call once your game has booted and is ready to be shown
minit.loading_done()

-- Read a game-config value from the URL query string, e.g. ?difficulty=hard
local difficulty = minit.get_config_value("difficulty", "normal")

-- Read this player's persisted userData slot (or nil if never written)
local saved = minit.get_user_data()

local score = 1234 -- Replace with the final score from your game's own state

-- When the game ends, report the final score once (higher score = better)
minit.report_result(score)

• minit.report_result(): the one call every Game must make. Options and result handling: Reporting Results.
• minit.loading_done(): optional; holds the host's reveal until your game is playable. Game Ready Signal.
• minit.get_user_data() / report_result(score, { user_data = ... }): optional per-player persistence (browser storage is unavailable in the sandboxed host). Saving User Data.
• minit.get_config_value(key, default): reads mod config values off the URL query string; outside the host it returns default (desktop/mobile) or reads the URL directly (standalone HTML5 build). Declaring the keys: Config Values.

Step 4: Configure Scaling#

Set the HTML5 scale mode in game.project to stretch:

[html5]
scale_mode = stretch

scale_mode is a string enum (downscale_fit, fit, stretch, no_scale). A numeric value is silently ignored, no resize logic runs, and the canvas stays pinned at the design resolution ("my Game doesn't fit the screen").

The Minit Games host mounts every game in a width: 100%; height: 100% iframe with a per-device aspect ratio. stretch resizes the canvas to fill it on every resize event. To keep your UI centered and undistorted, pair it with GUI adjust modes: background nodes ADJUST_MODE_STRETCH, text/content nodes ADJUST_MODE_FIT with a center pivot.

Step 5: Build for HTML5#

Project > Bundle > HTML5 (or headless bob for CI). Defold 1.13's HTML5 target is wasm-web. The asm.js js-web target has been removed. Optionally pass --architectures wasm-web for a single non-pthread build, avoiding the SharedArrayBuffer/COOP-COEP requirement of a multi-threaded build.

Step 6: Upload to Creator Console#

Zip the contents of your HTML5 build folder (index.html at the ZIP root, not nested) and upload to the Creator Console. Test in the feed preview.

Start from a template#

Instead of generating from nothing, clone the official starter template, with structure and SDK wiring already in place:

• minit-template-defold: engine project, SDK wired and simple example game mechanic

Minit Games-Specific Tips#

Touch Input#

Include the touch action in your input binding file and handle it in on_input. See the Defold input manual.

Bundle Size#

Defold's lean runtime keeps web bundles small. Compress textures with texture profiles; the limits live in Platform Requirements.

Text & Fonts on High-DPI Mobile#

Don't use the built-in /builtins/fonts/default.font for on-screen UI text: it's baked at size: 14, tiny relative to the 960×1480 design canvas. On-screen text height ≈ baked font size × node scale × the ADJUST_MODE_FIT scale factor. high_dpi does not change it; it only raises rendering sharpness.

Bake a custom .font asset instead: point a .font resource at a TTF (the built-in /builtins/fonts/vera_mo_bd.ttf works) with size set to 40–60, add it to your GUI's font list, and assign it to your text nodes. Increase the baked size rather than scaling the node up: scaling a small glyph adds no detail; Defold's distance-field fonts bake larger at little cost.

Set [display] high_dpi = 1 for crisper text at no cost to layout size.