OKONAONLINE

Introduction

OkonaPad is the Unity SDK for games published to the Okona Console — a living-room device that boots into a library, lets a player pick a game, and runs it as a Unity WebGL build with local USB/Bluetooth gamepads. The SDK's whole job is to make those controllers appear inside your game as ordinary Unity Gamepad devices.

Key Features

• Controllers arrive as standard Unity Gamepad devices
• Up to 6 players, each in their own slot
• Full controller surface: face buttons, bumpers, both sticks (incl. L3/R3), D-pad, triggers
• Zero-allocation input via WebAssembly memory (no GC hitches)
• Standard rumble through Gamepad.SetMotorSpeeds()
• Self-bootstrapping — no GameObject, no component, no scene wiring
• Works in the Editor with any pad; on the console with the real controllers

What changed in v2

SDK v2 is a clean break from v1. If you integrated against v1, re-import the package and re-bind to the standard Gamepad paths — it's simpler now.

Requirements

Unity

• Unity 6 (6000.3.x) or newer
• Input System package (com.unity.inputsystem) 1.17+
• Build target: WebGL

Project Settings

1. Install the Input System package via Package Manager.
2. Edit > Project Settings > Player > Other Settings → set Active Input Handling to Input System (New) (or Both).
3. That's it. The SDK registers its layout and starts pumping input automatically at load — there is nothing to add to a scene.

Quick Start

using UnityEngine;
using UnityEngine.InputSystem;

public class Player : MonoBehaviour
{
    void Update()
    {
        var pad = Gamepad.current;        // an OkonaPadDevice on the console
        if (pad == null) return;

        if (pad.buttonSouth.wasPressedThisFrame) Jump();
        Vector2 move = pad.leftStick.ReadValue();
        float gas = pad.rightTrigger.ReadValue();
    }
}

Recommended Pattern: PlayerInputManager

For both single- and multi-player, the cleanest setup is Unity's PlayerInputManager with "Join Players When Button Is Pressed". Each controller that presses a button spawns one player; when a controller is removed, that player's device is lost. Because OkonaPads are real Gamepads, this is identical to how you'd support local multiplayer in any Unity game — and it runs unchanged in the Editor with whatever pads you have on your desk.

Setup

1. Create an Input Actions asset with a control scheme that requires <Gamepad>, and bind your actions to <Gamepad>/… paths.
2. Make a Player prefab with a PlayerInput component pointing at that asset (set its default scheme + default map).
3. Add a PlayerInputManager to a scene object; set Join Behavior to Join Players When Button Is Pressed and point Player Prefab at your prefab.
4. If you subscribe to join/leave in C#, set the manager's Notification Behavior to Invoke C# Events (the onPlayerJoined/onPlayerLeft events only fire in that mode).

using UnityEngine;
using UnityEngine.InputSystem;
using OkonaPad;

// One of these is spawned per joined controller.
[RequireComponent(typeof(PlayerInput))]
public class PlayerController : MonoBehaviour
{
    PlayerInput _input;

    void Awake()
    {
        _input = GetComponent<PlayerInput>();

        // The Gamepad this player owns (an OkonaPadDevice on the console).
        var pad = _input.GetDevice<Gamepad>();

        // Optional: the 0-based Okona slot (P1 = 0 … P6 = 5).
        if (pad is OkonaPadDevice okona)
            Debug.Log($"Joined as player slot {okona.okonaSlot}");
    }

    // Bound to a "Fire" action in the Input Actions asset.
    public void OnFire(InputAction.CallbackContext ctx)
    {
        if (ctx.performed) Fire();
    }

    void Rumble()
    {
        // Standard Gamepad rumble — forwarded to the physical pad.
        (_input.GetDevice<Gamepad>())?.SetMotorSpeeds(0.4f, 0.8f);
    }
}

To clean up a player whose controller is removed, handle device loss on the PlayerInput:

_input.onDeviceLost += pi => Destroy(pi.gameObject);

API Reference

Everything lives in the OkonaPad namespace. For most games you never touch these types directly — you read input through the standard Gamepad / PlayerInput API. They're here for when you want the Okona slot, manual access, or deterministic tests.

// The connected device for a 0-based slot, or null.
public static OkonaPadDevice GetDevice(int slot);

// Pull the current snapshot and push it to the Input System. Runs every
// frame automatically (InputSystem.onBeforeUpdate); also callable directly
// for deterministic tests.
public static void Pump();

// Editor/test only: inject a snapshot as if it came from the web layer.
#if UNITY_EDITOR
public static void SimulateSnapshot(byte[] snapshot);
#endif

Header (4 bytes)
  [0]      magic        0x4F ('O')
  [1]      version      1
  [2]      maxPads      6
  [3]      reserved     0

Per pad (17 bytes), one per slot 0..5
  [0]      flags        bit0 = connected
  [1..4]   buttons      uint32 LE — bit i = button i pressed
  [5..6]   leftX        int16  LE  (-32767..32767 => -1..1)
  [7..8]   leftY        int16  LE
  [9..10]  rightX       int16  LE
  [11..12] rightY       int16  LE
  [13..14] leftTrigger  uint16 LE  (0..65535 => 0..1)
  [15..16] rightTrigger uint16 LE

How Input Flows

On the Okona Console, a USB or Bluetooth pad is paired at the OS level and surfaced into the game page; the shell tracks it in one of six player slots and writes its state into the snapshot; the SDK reads the snapshot from WebAssembly memory and drives a Gamepad for it.

Slots & reconnection

The shell manages six slots. A pad is adopted into the lowest free slot the moment a button is pressed on it (a single pad attached at load is adopted automatically). If a pad disconnects — including a brief Bluetooth blip — its slot is held for 30 seconds and the same player resumes when it returns, so a momentary drop never turns into a new join. After the reserve expires the slot is freed and the OkonaPadDevice is removed.

Rumble

Call SetMotorSpeeds(low, high) on the player's Gamepad. The SDK forwards it to the web layer, which vibrates the physical pad (best-effort — silently ignored on pads that don't support haptics). No Okona-specific API to call.

Reference Project

The SDK ships with a Unity 6 reference project that demonstrates the recommended setup end-to-end:

• Input Tester — a PlayerInputManager scene that spawns one on-screen controller widget per joined pad and lights up every input (face buttons, bumpers, sticks, L3/R3, D-pad, analog triggers). Drop in up to six pads and watch them light independently.
• Player prefab + Input Actions — a bare PlayerInput prefab and an actions asset with a <Gamepad> control scheme you can copy straight into your game.

It's the fastest way to confirm the SDK works with your controllers — open the Input Tester scene, press Play, and press a button on each pad.

Testing Your Game for Okona

The Okona Dev Harness runs your WebGL build on your own machine exactly as the console runs it — the same game shell, the same controller input path, the same in-game menu — so you can validate your game before you publish it. Download the harness — it's a small tool that needs only Python 3.7+, nothing to install.

Run it

1. Build your game for WebGL with Brotli compression (see Requirements).
2. Download the harness and unzip it anywhere.
3. From the unzipped okona-harness/ folder, point it at your build — the folder Unity produced, containing index.html and a Build/ subfolder:

   python devtools/okona-test/okona-serve.py <path-to-your-WebGL-build>

4. A browser opens with your game running. Plug in a USB or Bluetooth controller and play. Press ` (backtick) to toggle the diagnostics overlay.

The serve script sets the HTTP headers Unity WebGL requires — the reason a plain static server usually fails to load a Brotli build.

Confirm your controls

The strip along the bottom shows one card per controller slot (P1–P6), decoded live from the input snapshot the SDK reads: pressed buttons, stick positions, trigger pull. Use it to confirm every control maps the way you expect, and that multiple pads each drive their own player.

Check performance against the console

The Okona Console is a Raspberry Pi 5. A game that hits 60 fps on your development machine can run far slower on the Pi, so the harness does not rely on desktop framerate. Instead it grades your game's GPU workload — which predicts console behaviour no matter how fast your machine is — against budgets measured on real console hardware:

Green is comfortable, amber is at budget, red is over. If you're in the red, reduce draw calls (batch/atlas), cut per-frame mesh rebuilds, and avoid realtime shadows and full-screen post-processing.

Pre-submit checklist

• Game loads and is playable in the harness (Brotli build).
• Every control reads correctly in the input visualizer.
• Multiple controllers each drive their own player (P1–P6).
• Home opens the Game Menu; Continue resumes, Exit leaves.
• Workload metrics are green or amber — not red.
• Rumble fires on supported pads (if your game uses it).

Troubleshooting

Use with AI Assistants

If you build with an AI coding assistant, connect it to the Okona docs MCP server and it can read this documentation directly — the full SDK reference, the testing guide, and the dev-harness manual — instead of guessing at the OkonaPad API. It's a public, read-only Model Context Protocol endpoint; no account or API key needed.

https://okonaonline.com/mcp

Claude Code

claude mcp add --transport http okona-docs https://okonaonline.com/mcp

Cursor

Add to .cursor/mcp.json in your project (or the global one):

{
  "mcpServers": {
    "okona-docs": { "url": "https://okonaonline.com/mcp" }
  }
}

Other clients

Any MCP client that supports the Streamable HTTP transport works — point it at the URL above with no authentication. The server exposes three tools:

• list_doc_sections — the documentation catalog
• read_doc_section — one section (or everything) as markdown
• search_docs — keyword search with snippets

Build Your Own Console

The Okona Console is a Raspberry Pi 5 appliance. We publish the exact pre-provisioned image we flash ourselves, so you can build your own: flash one SD card, plug it into a TV, and it boots straight into Okona — the same setup, library, and gameplay as a retail unit. No install steps, no command line.

Loading the latest image…

What you'll need

• Raspberry Pi 5 (recommended). A Pi 4 also works; Pi 3 and older can't run Unity WebGL.
• microSD card, 16 GB or larger.
• Official USB-C power supply — 27 W for the Pi 5, 15 W for the Pi 4. (Underpowered supplies cause hard-to-diagnose instability.)
• micro-HDMI → HDMI cable, into the HDMI port next to the USB-C jack (HDMI0).
• A TV with an HDMI input.
• A USB or Bluetooth gamepad (Xbox, PlayStation, 8BitDo, Switch Pro…). A phone on the same Wi-Fi can also act as a controller.

Flash the card

1. Download the image above — it's a .img.gz. Don't unzip it; the flashing tool reads it directly.
2. Install Raspberry Pi Imager (or balenaEtcher).
3. In Imager: Choose Device (your Pi) → Choose OS → Use custom → pick the downloaded .img.gz → Choose Storage (your microSD) → Write.

Verify the download optional

Confirm the file arrived intact by checking its SHA-256 against the published value (—):

# Windows (PowerShell)
Get-FileHash -Algorithm SHA256 okona-console.img.gz

# macOS / Linux
shasum -a 256 okona-console.img.gz

First boot

Insert the card, connect HDMI and power, and the Pi boots into the Okona setup screen.

• Wi-Fi: the console raises its own Okona-XXXX hotspot and shows a QR code on the TV. Scan it with your phone, pick your home network, and type its password. The TV flips to the game library once it's online.
• Controllers: hold a Bluetooth pad's pairing button to pair it — there's no pairing screen to find. USB pads just work when plugged in.
• Pick a game and play. Subsequent boots skip setup and land on the library in seconds.