dot-core

The common layer under everything else, and the only hard dependency in the collection. It targets desktop, mobile and the browser from one codebase, and encodes the browser’s limitations rather than pretending they do not exist.

cp -r dot-core/addons/dot_core my-game/addons/
godot --headless --path . res://examples/capability_report.tscn

What is in it

Where a game plugs in

DotTransport subclass

_create_server, _create_client, _transport_name, _is_available, supports_web_clients, scheme. Availability is checked before use, so an unusable transport fails at boot with a reason rather than as a null peer three calls later.

DotJob subclass

_step (a bounded slice; return true if more remains), _progress, _setup, _teardown, is_thread_safe. Hash a chunk, not a file — the scheduler can stop calling _step, but it cannot interrupt one.

DotConfig subclass

env_prefix(), cli_prefix(), sensitive_keys(), validate(). Declare @export properties and the layering, the reflection and the settings screen all follow.

DotLogSink, or DotLog.add_sink(callable)

Where records go. The Callable form is one line; the class handles files, rotation and forwarding.

DotNodeRef on every component

The collection-wide answer to “which node”. Every addon’s node exports at least one.

DotResult is not optional politeness

var res := await cloud.acquire(url)
if not res.ok:
    if res.error.code == DotError.CODE_RATE_LIMITED:
        retry_after(res.error.retry_after)
    return
var scene_path: String = res.value

Branch on DotError.CODE_*; never on the message. res.wrap(...) adds context without discarding the cause, so a failure three layers down still says what it was doing at each level.

DotScheduler and the browser

DotScheduler runs jobs on worker threads where the build has them and slices them on the main thread inside a frame budget where it does not — because a web export has no threads unless the template was built for them, and DotPlatform.has_threads() is the question to ask rather than OS.get_name().

Reproducible randomness

dot-core’s random/ module replaces RandomNumberGenerator with named streams whose draws are a pure function of (key, index). It shipped as a separate addon, dot-randomness, and folded in here: every other addon that wanted determinism had to take it, which made it a second hard dependency in a collection that has exactly one.

Other addons still find it through DotRegistry under dot_random_source and call stream(name), so anything with that method can stand in.

var world := DotRandomStream.new(seed)
var spread := world.stream(&"spread")
var loot := world.stream(&"loot")

spread.at(tick)             # the same number on every machine, for ever
loot.next_range_i(1, 6)     # and drawing it does not move `spread`

at() advances nothing, so a client can know what the server will do on a tick it has not simulated, and a replay can be scrubbed backwards.

A single shared generator is mutable state every caller advances, which is three bugs in a networked game:

• Two peers that draw in a different order diverge. A server that rolls weapon spread and then a loot drop, and a client that predicts the shot and never sees the loot, are one draw apart for the rest of the session — and the visible symptom is that the shooting stops matching, which points at the netcode.
• Adding a feature changes the past. One extra draw shifts every later number, so yesterday’s replay plays back differently and a shared seed stops producing the world it was shared for.
• A stream nobody can resume. A receiving peer has to adopt an index, not allocate one.

Tables

DotRandomTable draws ids and knows nothing about what they are, so a loot table validates and draws on a server without the content.

Events in ticks

var s := DotRandomSchedule.new()
s.mean_interval_ticks = 64 * 30     # about every thirty seconds at 64 Hz
s.min_gap_ticks = 64 * 8            # never two in eight seconds
s.max_gap_ticks = 64 * 90           # and never a gap longer than ninety

if s.fires_at(stream, tick, last_fired_tick):
    ...

fires_at is pure, so it answers for tick N without having run ticks 0..N-1 — which is what lets a client anticipate a server, a replay scrub, and a restarted server land on the schedule it was already running. A stateful countdown can do none of those, and its failure mode latches: a due event dropped while a cooldown runs, and nothing offered again.

Transports

DotTransportAuto is the default and picks for you. The choice is not a preference:

• A browser has no UDP, and ENetMultiplayerPeer is absent from the web template — so DotTransportENet reaches ENet through ClassDB.instantiate and Object.call, never by name. A script that so much as mentions the identifier fails to compile on a web export.
• One listening socket speaks one protocol. A server that wants browser clients listens on WebSocket, and then all its clients do. require_web_clients defaults to true for that reason.