# 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](https://docs.dev.board.fun/guides/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](https://docs.dev.board.fun/guides/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](https://docs.dev.board.fun/guides/pause-menu) and [Profile Switcher](https://docs.dev.board.fun/guides/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](https://docs.dev.board.fun/guides/save-games) for implementation details.

## Modules

| Module          | Purpose                                                                      |
|-----------------|------------------------------------------------------------------------------|
| `Board`         | Application lifecycle, capability check, logging passthrough                 |
| `Board.input`   | Touch Contacts, Glyphs, input settings                                      |
| `Board.session` | Players, Profiles, sessions                                                  |
| `Board.save`    | Save game management                                                         |
| `Board.avatar`  | Cached, player-scoped avatar `ImageTexture` loader                          |
| `Board.pause`   | System pause overlay                                                         |