Architecture

Overview of the Board Godot SDK components.

Core Components

Board.input

The touch input subsystem. Receives Contact data from Board hardware and provides it to your game.

Responsibilities:

• Tracking active Contacts
• Contact phase management (began, moved, ended)
• Glyph recognition
• Input smoothing

Key APIs:

• Board.input.activate(model) — load a Piece Set Model and start the detector
• Board.input.contacts_received — the per-frame Contact snapshot signal (an Array of raw contact Dictionary entries; each contact carries phase_id (BEGAN/MOVED/ENDED/CANCELED/STATIONARY), is_touched, glyph_id, etc.)

This 60 fps hot path is deliberately untyped — the entries stay as raw Dictionary values to avoid per-frame allocation. For ergonomic, typed access to a single contact, wrap it with BoardContact.from_dict(c), which exposes the BoardContact.Type (FINGER/GLYPH/BLOB) and BoardContact.Phase (NONE/BEGAN/MOVED/ENDED/CANCELED/STATIONARY) enums plus the facing() -> Vector2 and is_piece() helpers. The Board.input.TYPE_* / PHASE_* int constants still exist (same values) for reading a raw contact’s type_id / phase_id directly.

There is no separate per-Contact edge signal. To detect discrete edges (tap-down / tap-up via is_touched, or a piece being lifted), keep your own previous-frame map keyed by contact_id and diff each contacts_received snapshot against it:

var _prev := {}

func _on_contacts_received(contacts: Array) -> void:
    var current := {}
    for contact in contacts:
        var id: int = contact.contact_id
        current[id] = contact
        var was := _prev.get(id)
        if was == null:
            _on_contact_appeared(contact)
        elif was.is_touched and not contact.is_touched:
            _on_piece_lifted(contact)
    for id in _prev:
        if not current.has(id):
            _on_contact_removed(_prev[id])
    _prev = current

Reference: see Touch Input for implementation details.

Board.session

Manages the current game session, players, and Profiles.

Responsibilities:

• Tracking the active Profile
• Managing the Player list
• Notifying of Player changes

Key APIs:

• Board.session.get_players() — current Players
• Board.session.players_changed — change notifications
• Board.session.present_add_player() — open the OS Player selector

Reference: see Player Management for implementation details.

Board.application

Main entry point for Board system features like the pause overlay and Profile switcher.

Responsibilities:

• Pause screen configuration and events
• Profile switcher overlay
• System-level interactions

Key APIs:

• Board.pause.set_context(...) — configure the pause overlay
• Board.pause.pause_result_received — pause action handler
• Board.session.show_profile_switcher() — show the Profile switcher
• Board.application.quit() — exit cleanly back to BoardOS

References: see Pause Menu and Profile Switcher for implementation details.

Board.save

Handles persistent save game storage.

Responsibilities:

• Creating and loading save games
• Managing save game metadata
• Player–save associations
• Storage quota management

Key APIs:

• Board.save.await_create(...) — create a save game
• Board.save.await_list() — list saves
• Board.save.await_load(save_id) — load save bytes
• Board.save.get_app_storage_info() — synchronous storage usage snapshot (Dictionary with total_storage, used_storage, remaining_storage byte counts and a usage_percentage float 0.0–1.0; {} off-device)

Reference: see Save Games for implementation details.

Modules