Pairs and the mode​

• A theme is a folder holding dark.toml and light.toml. editor/appearance/theme names the pair, balaur by default.
• editor/appearance/mode is system, dark or light, and system by default. The ☾ button writes dark or light.
• Duplicate writes themes/balaur-custom/ in the editor's data folder, holding the half you wear. A half the folder lacks comes from its base.

Bundled schemes​

• Solarized, Gruvbox, Catppuccin, Tokyo Night, Atom One, Rosé Pine, GitHub, Everforest, Dracula and Kanagawa ship with the editor, both halves each. The largest half is 621 bytes.
• A half states the scheme's surfaces, text, accents and syntax colours, read off the scheme's own palette file. Its header names the licence and the source.
• Every half reads at WCAG AA. A colour under 4.5:1 keeps its hue and moves in lightness, with the scheme's value beside it: Catppuccin Latte's keyword went from #8839ef to #771dda.
• Nord has no light half, so it is not bundled.

Dark mode in a game​

• engine::dark_mode() and on_dark_mode_changed(bool) answer on Windows, Linux, iOS and Android, as on macOS and in a browser.
• Linux asks the desktop portal's color-scheme through the system's libdbus, loaded on first use and asked every two seconds.

• #{ z_index: 1 } on draw_circle_2d, draw_rect_2d, draw_arc_2d, draw_polygon_2d, draw_polyline_2d, draw_texture_2d, draw_line_2d and draw_text_2d places the shape at that index. Without one it draws over the scene.
• A stroke placed at an index is a mesh, so its width in pixels holds at the camera's zoom.
• draw_texture_2d takes region_origin and region_size in the image's pixels and draws that part of it, the keys a sprite uses for its region.
• A misspelt key is an error naming the keys a verb takes.
• balaur import draws a Godot node's _draw at the node's global_z_index, and a draw_texture_rect_region through the region.

render::draw_circle_2d(-1.5, 0.0, 1.4, [0.2, 0.9, 0.4, 1.0], #{ z_index: 1 });
render::draw_texture_2d("art/blocks.png", -5.0, 2.2, 1.5, 1.5, (),
    #{ region_origin: [0, 0], region_size: [16, 16] });

Sources and tokens​

• The dark theme states six colours: background, foreground, primary, secondary, warning and danger. The other 55 of its 61 tokens are derived.
• A token is <group>_<role>: bg_panel, text_muted, primary_fill, text_on_primary. Stating one overrides its rule.
• Sizes work the same way. font_size = 12 and control_height = 24 give the editor's 11, 14 and 17 px text and its 20, 30 and 33 px controls.
• The 106 roles live in one roles.toml both bundled themes share, so the dark and light files hold colours only.

Your own themes​

• Duplicate writes themes/dark-custom.toml in the editor's data folder, holding base = "dark" and nothing else. The copy is worn at once.
• Save writes only the keys that differ from the base, so a theme with its own primary colour is one line.
• editor/appearance/theme lists dark, light and every file in that folder. The ☾ button writes the same setting.

The window​

• It opens from the menu, from Settings, or from the palette.
• The side lists Colors, Sizes, Text, Controls, Boxes, Layout, Kinds and Problems. A derived token reads quieter than one the theme states.
• Each role is drawn as itself. Edit lists its keys: a swatch and a token for a colour, a number or a size's name for a size.
• A chip row picks the role or its hover, active, focus, disabled, checked or touch table, and "add a key…" states one the base leaves out.

Contrast​

• Every role's text is measured on its fill with the WCAG 2 ratio. Problems lists each pair under 4.5:1, or 3:1 for large text. Both bundled themes have none.
• ui::contrast(a, b), ui::contrast_pairs(theme, ground) and ui::complete_theme(theme) give a script the same numbers and tokens.

# themes/dusk.toml
type = "widget_theme"
base = "dark"

[colors]
primary = "#c8843e"
background = "#221e28"

• kind lays the particles out: box, sphere, cloth, cloth_tube or rope in 3D, and grid, circle or rope in 2D. A mesh can be filled with cells or kept as a surface.
• pinned_particles names the particles held in place. Past tear_strain or tear_force an edge breaks, and the node's on_tear runs.
• The material rows set a spring per constraint family, the cell model and plasticity. solver = "fem" switches to Rapier's implicit step.
• A soft body is in the snapshot, and the digest hashes every particle's velocity.
• The Physics panel lists every physics component on the selection. One click turns a mesh into a hull, convex pieces, voxels or a soft body.

[nodes.softbody2d]
kind = "circle"
radius = 1.0
particle_count = 32
color = [0.29, 0.56, 0.82, 1.0]

What it costs, offscreen at 1600x1000​

What joins a call​

• A sheet frame joins the run. The frame is a rectangle on the instance, where it used to be a private copy of the built-in quad with rewritten coordinates.
• In two dimensions a run is cut along the draw order, so what covers what does not change. In three it is not, because geometry is depth-tested.

What keeps a draw of its own​

Declaring one​

• of is the spec a list's entries and a map's values take, and fields is one spec per record field. Each is a whole property spec, so min, options, asset and component work at any depth.
• A nested spec may leave its default out; the type's zero is written in when the component registers, and a new entry starts there.
• A map's key is "string" or "int". A number key is written "7" in the file and reaches the script as the number.
• strings and nodes are gone. They were list of string and list of node, and fifteen schema lines were rewritten.

waves  = { type = "list", of = { type = "int", min = 0 }, default = [] }
spawns = { type = "map", key = "int", of = { type = "node" }, default = {} }

Exporting one from a script​

• A bare export says what it is: waves: [2, 4, 8] is a list of whole numbers, and an object is a record whose fields keep their own types.
• A list holds one type, and an entry of another names itself in the error.
• A node path is resolved wherever the spec puts one, so a list of nodes arrives as the nodes, and a record's node field does too.
• A struct the script declares is exported as itself: the scene writes its fields, and init is handed that class, methods and all. The inspector row says which class it is.

struct Wave { hp, name }

pub fn exports() {
    #{ waves: [2, 4, 8], wave: Wave { hp: 3, name: "grunt" } }
}

Docs​

• Component properties
• Exported script properties

Modules​

• addons/kit/math.rn is kit::math. Its functions are called as kit::math::double(2) and its constants read as kit::math::LIMIT.
• The constants in a pub mod block sit one segment deeper: kit::math::colors::RED.
• Saving an addon file reaches every script that calls it.
• Completion and hover walk the path, and show a function's parameters and its doc line.
• An addon may share a name with an engine module: gamend::lobbies sits beside gamend::login.
• An exported pack keeps the paths, and a project opened in the editor mounts its own addons.

The Gamend SDK​

• 259 operations in 47 modules, one per server feature: gamend::lobbies::create_lobby, gamend::users::get_current_user.
• Realtime events are grouped by channel. gamend::events::lobby::MEMBER_JOINED is what gamend::events::decode answers for a lobby's user_joined.

let reply = task::wait(gamend::lobbies::quick_join(this.node, #{
    "title": "duel", "max_users": 2,
})).await;

Docs​

• Script files as modules
• Gamend accounts

The server​

• The header switches between the project's two servers, [gamend] url and local_url.
• The choice is kept in the editor's own settings, so an exported game always talks to url.
• A new project starts on https://gamend.org.
• Open and Admin go to the server and to its admin site.

The player​

• The User tab shows the session, both tokens masked behind show and copy, and when the access token expires.
• A session kept by an earlier run can be read while signed out, restored or forgotten.
• The editor uses the game's own user data folder and device id, so a device sign-in from the dock is the game's account.

One tab per feature​

• Leaderboards, Quests, Economy, Friends, Chat, Parties, Groups, Tournaments, Matchmaking, Notifications, Payments, Hooks and Users list their GET endpoints as trees.
• The Lobby tab follows the lobby the game joined, and reads it again when a message lands on its topic.
• Activity lists every call and socket message, opens each to its arguments and reply, and filters to errors.

Shipping the log​

• Nothing is sent unless the game puts addons/gamend/log_sink.rn on a long-lived node.
• The sink reads log::since and collects what the server's policy asks for.
• A batch goes at 50 lines, every 10 seconds, and at once on an error.
• Unsent lines wait in a save slot for the next launch.
• Every call, the socket and each batch carry gamend::run_id(), so the server files a run's lines together.
• The Logs tab shows the newest lines and flushes on demand.

Docs​

• The Gamend dock
• Client logs
• Extending the editor

Projects list​

The project manager contains a list of all your projects, what version of the engine you used to open them and a logo.

Example​

The default examples that the GitHub repo contains are also visible in the Examples tab. Each of them has a screenshot and a title. Opening it downloads it into your projects and opens the copy.

Manage Engine Version​

• Pick a channel: alpha, beta, rc, stable or nightly.
• The latest version is checked whenever you open the tab.
• Each release says whether it is newer or older than yours, and its button says Install or Downgrade.
• An install downloads in the background with a progress bar. Restart to use it.
• The macOS app downloads the release's .dmg instead, since it cannot replace itself.
• The tab calls the same functions as balaur update (the cli).

About Balaur​

• The menu under the logo has an About Balaur entry.
• It shows the version, build, channel and platform, and whether your channel has a newer build.

Docs​

Read more about it here:

• The Project manager.

It is also configurable in the project.toml file:

[application]
splash = "art/logo.png"
splash_seconds = 1.5

It can also be reused if needed for other parts of the game, from Rune:

ui::set_load_progress(0.4, "textures");
// ...
ui::finish_loading();

• set_load_progress takes a fraction and a label, and draws a bar under the picture in the theme's primary colour.
• finish_loading ends the loading early.

Docs​

Read more about it here:

• Shipping.

• A saved texture, model, font or sound reloads, and every node built from it is rebuilt.
• An id:// reference survives a move, and a rename in the Assets dock rewrites every reference to the file.
• art/hero.png.import.toml holds one image's import settings, and [import.texture] in project.toml is the default.
• filter = "nearest" draws pixel art crisp.

Asset imports · Import settings

Surfaces​

package::mesh binds the sky as an environment map, the occlusion, the reflection probes, and the scene that glass refracts.

• Image-based lighting takes the place of environment.ambient.
• A mirror renders the scene from its own plane.
• A reflection_probe is a box with a room captured inside.

Occlusion​

Every 3D material draws a geometry prepass. It then feeds the occlusion buffer.

Running it​

Follow the instructions in balaur-sponza. Its scripts download the model and set up the scene after balaur import.

• The model is Sponza from the Khronos glTF sample assets, CC BY 4.0, after the original by Frank Meinl for Crytek.

process is a key on a node like visible, and the subtree under it inherits the answer:

• pausable stops while paused. The default, and what everything above gets from the root.
• always runs either way. A pause menu, a loading screen, the script that lifts the pause.
• when_paused runs only while paused.
• disabled never runs.
• inherit takes the nearest ancestor's answer.

That one key stops everything that ticks per node:

• Scripts, animation players, tweens, state machines and the timer component.
• Physics is one world and is held whole, so a body under an always node stops with the rest. Godot draws the line in the same place.
• Every script's on_paused(bool) is called when the state changes, the scripts the pause just stopped included.

Slow motion, and the frames between ticks​

engine.set_time_scale(0.25) multiplies wall-clock time before the simulation is owed it. Half speed takes half the fixed steps, double takes twice, and each step is still the same length. The cap on catch-up steps scales with it, so fast forward is not quietly clipped. Three settings come with it:

• [window] max_fps caps the loop where vsync does not.
• [time] tick_hz replaces the built-in 60. A recording carries the rate it was made at.
• [time] interpolate draws bodies and fixed_update nodes between steps, so they move on every frame of a 144 Hz display. Off by default: it costs one tick of latency, which a run taking one step per frame pays for nothing.

• multi lets a list, tree or table hold more than one row. The platform's command key toggles a row, shift takes the run from the last one clicked, and selection is what the widget holds.
• on_change hears the whole selection where the widget holds many, and the row where it holds one. A widget without multi behaves as it always did.
• A table's placeholder names its columns, split on the separator its rows are. A name ending in > draws its column against the right edge, which is what a column of numbers wants.
• Each column's width is a share the seam in the header drags, held per table, so a rebuild of the rows leaves the widths where you put them.
• A row may carry an #rrggbb past its last cell, the way a list row carries its own colour.
• A secondary click picks the row it lands on, so a context menu acts on what it opened over. A row already picked keeps the set it is in.
• The table places its body by arithmetic now, as list and tree already did: 2,000 rows cost a screenful. No crate was added for any of it.

The editor eats it. Its Profiler and Cost docks were padding numbers into a monospace string to fake columns, and both are table nodes now. The outliner's search view moved onto the same tree node the unfiltered one already used, and a right click on a row opens the node's own menu.

The picture above is one scene of widget nodes, with no drawing code behind it.

The rest is on the roadmap.

Docks​

• On a tablet both side docks start folded, and an open one takes half the screen.
• On a phone all three start folded, and one opens at a time.
• A folded dock leaves a handle at its edge, and an open one folds back the same way.

Touch​

• Under a finger the glyph, the plate and the bar grow together.
• Every control is at least 44 points, and the editor's selftest fails one under that.

The editor

• A menu bar is a row of menu nodes. A row that is itself a menu opens to the side on hover, one submenu at a time, and does not shut the menu it hangs off.
• Any widget names a menu as its context. A right click opens it at the pointer, and so does a long press, which is the same gesture on a phone. The widget's own on_click stays quiet for that press.
• placement says where a menu opens: below, above, pointer, or center.
• shortcut is a chord on any widget, written one way: cmd+shift+s, f5. A menu row fires with its menu shut, and the row draws the chord the way this platform writes it.
• A toast is a root that stacks at its anchor, fades over its last half second, and frees itself when its duration is up. A binding action puts one up with no script at all.
• A dialog closes on Escape and on a click on the dim, and reports that through on_change.

Every one of them is a property on the widget component, so the inspector edits them and a scene file holds them.

The rest is on the roadmap.

• A [url=target] span wears the theme's link colour and an underline, the pointer over it is a hand, and a click calls on_link with the target. What to do with it is the game's: a scene, a shop, a browser.
• A [hint=text] span says something while the pointer rests on it. The hover text belongs to the span, not to the whole label.
• With selectable, a drag selects, the platform's copy key takes it, double click takes a word and treble takes the block. A seed or an error code is now something a player can send you.
• A drag_value with arrows draws a step up and a step down inside its own box, each moving by step within min and max, and suffix puts the units after the number: 12 px, 4.5 m/s.

Labels are still shaped by the engine's own text stack. That is what keeps right-to-left runs in order, holds one glyph atlas behind the HUD and the world, and measures a width a headless run agrees with.

Cutting a polygon used to leave seams, where small objects could get stuck. Erin Catto's Stuck Inside article explains about overlaps the pieces by hand. This does it automatically.

overlap is configurable, 0.9 by default (it leaves a bit of empty room). At 0 you get the plain cut.

Performance​

What the times look like (at build time):

• A trimesh is the cheaper static collider when bodies only touch it from outside. This kind is for dynamic bodies.

Also​

• Mass comes from the ungrown pieces, so a table weighs what its area says.
• A solids-mode Godot CollisionPolygon2D imports as this kind.
• geometry2d.convex_decomposition hands the pieces to a script.

balaur import project.godot --project my-game

Ported: Polyglot Pirates, a shipped Godot 4.7 game. 181 scenes, 769 scripts, a theme of 700 items. Its automation runner was ported first, so a passing scenario proves every script it walks through.

• Each scene has one root, and an instance is that root, so a converted node path reads the same as in Godot.
• A stack container lays every child over the same box, as a Godot MarginContainer does.
• Theme import carries separations, icon colours and bold faces.
• fit on a picture covers Godot's expand and stretch modes.
• await works on a signal and on another node's method.
• A meta component, Array[Node] exports, toggle buttons, and children running init before their parent.
• Tilemaps honour z_index against sprites.
• A button takes the box the layout solved, not its caption's size.
• macOS dark mode is read from the window.

How far it is​

Five scenarios pass headless, and a run ends with a screenshot. The menu matches. The gameplay screens are next.

• It folds the tree, the inspector and the bottom dock, whatever each was showing, and the split with them. The hooks list stays.
• Focus records the three docks' state and the split before folding them, and leaving restores what was open.
• Opening a panel under focus ends it: the panel stays and the record is dropped. Leaving the code tab restores the shell.
• A chip beside Split in the top bar, ⇧⌘\, or the command palette turns it on. With no script on the selection the chip is greyed and its tooltip says why.