API リファレンス

@uzupj/uzu-sdk パッケージの公開 API 一覧です。

パッケージ情報

項目	値
パッケージ名	@uzupj/uzu-sdk
モジュール形式	ES Modules
依存関係	なし (devDependencies: typescript ^5.7.0 のみ)

関数

init(): void

SDK を初期化し、Flutter ホスト / 親ウィンドウに準備完了を通知する。

import { init } from '@uzupj/uzu-sdk';

init();

動作:

1. Flutter WebView / iframe 環境に応じてメッセージ受信口を登録
2. URL に ?roomId=xxx があれば Relay WebSocket に自動接続

TIP

run() / sync() を使う場合は内部で init() を呼ぶため、直接呼ぶ必要はありません。 Relay ベース (onRoom()) のゲームでのみ、最初に呼び出してください。

run<S>(config: GameConfig<S>): void

Host-authoritative ゲームループを実行する。

import { run } from '@uzupj/uzu-sdk';

run({
  logic,
  onState(state, myPlayerId) {
    currentState = state;
    myId = myPlayerId;
  },
  inputs(sendAction) {
    canvas.addEventListener('click', () => {
      sendAction('choose', { hand: 'rock' });
    });
  },
  events: {
    sound(data) {
      new Audio(`/sounds/${data.sound}.mp3`).play().catch(() => {});
    },
  },
  playerCount: 2,
});

モードの自動判定:

• URL に ?roomId=xxx がない → ローカルモード (サーバー不要)
• URL に ?roomId=xxx&server=xxx がある → オンラインモード
• URL に ?__dev=N がある → Dev ハーネスモード

sync<S>(config: SyncConfig<S>): void

Server-authoritative な JSON Patch ベースの状態同期を開始する。

import { sync, SERVER_TIME } from '@uzupj/uzu-sdk';
import type { Player } from '@uzupj/uzu-sdk';

sync<GameState>({
  playerCount: 2,
  initialState(players: Player[]) {
    return { board: createBoard(8), currentPlayer: players[0].id };
  },
  onState(state, myPlayerId, serverTime) {
    currentState = state;
    render();
  },
  inputs(patch, set) {
    canvas.addEventListener('click', (e) => {
      const { row, col } = getCellFromClick(e);
      patch([
        { op: 'replace', path: `/board/${row}/${col}`, value: myPlayerId },
        { op: 'replace', path: '/lastMoveAt', value: SERVER_TIME },
      ]);
    });
  },
  connection: {
    onConnectionStateChange(state) {
      console.log('Connection:', state);
    },
    onPatchFailed(error) {
      console.error('Patch failed:', error);
    },
  },
});

send(message: PlayScreenMessage): void

Flutter ホスト / 親ウィンドウへ任意のメッセージを送信する。

import { send } from '@uzupj/uzu-sdk';

send({ type: 'playSound', sound: 'sounds/clear.mp3' });

on(type: string, handler: MessageHandler): void

Flutter / ホストからのメッセージに対するハンドラを登録する。同一 type に複数登録可能。

import { on } from '@uzupj/uzu-sdk';
import type { PlayersChangedMessage } from '@uzupj/uzu-sdk';

on('playersChanged', (msg) => {
  const { players } = msg as unknown as PlayersChangedMessage;
  for (const [id, state] of Object.entries(players)) {
    switch (state.audioStatus) {
      case 'speaking':
        highlightAvatar(id);
        break;
      case 'listening':
        showNormalAvatar(id);
        break;
      case 'muted':
        showMuteIcon(id);
        break;
      case 'unstable':
        showUnstableBadge(id);
        break;
      case null:
        showNoVoice(id);
        break;
    }
  }
});

playSound(sound: string): void

効果音の再生リクエストを送信する。

import { playSound } from '@uzupj/uzu-sdk';
playSound('sounds/clear.mp3');

playBgm(sound: string): void / stopBgm(): void

BGM の再生・停止を制御する。

import { playBgm, stopBgm } from '@uzupj/uzu-sdk';

playBgm('bgm/main.mp3'); // ループ再生
stopBgm();

setMicEnabled(enabled: boolean): void

マイクのオンオフを切り替える。

import { setMicEnabled } from '@uzupj/uzu-sdk';
setMicEnabled(false); // ミュート

changeRoom(roomId: string | null): void

ボイスチャットルームを移動する。null でデフォルト (全体) ルームに戻る。

import { changeRoom } from '@uzupj/uzu-sdk';
changeRoom('room_a');
changeRoom(null);

isHosted

boolean (読み取り専用)。Flutter WebView または iframe 内で動作しているかを示す。

型定義

Player

interface Player {
  id: string;
  nickname: string;
  iconUrl: string;
  characterId?: string;
}

GameConfig<S> (run 用)

キー	型	必須	説明
logic	GameLogic<S>	Yes	ゲームロジック定義
onState	(state: S, myPlayerId: string) => void	Yes	state 更新時のコールバック
inputs	(sendAction) => void	Yes	入力ハンドラ登録
events	Record<string, (data) => void>	No	ゲームイベントハンドラ
playerCount	number	Yes	プレイヤー数

GameLogic<S>

キー	型	必須	説明
setup	(players: Player[], random: SeededRandom) => S	Yes	初期 state を生成
actions	Record<string, ActionHandler<S> | ServerOnlyAction<S>>	Yes	アクションハンドラ
update	(state: S, ctx: UpdateContext) => void	Yes	毎 tick 実行
tickRate	number	No	秒間 tick 数 (default: 10)

SyncConfig<S> (sync 用)

キー	型	必須	説明
initialState	(players: Player[]) => S	Yes	初期 state を生成
onState	(state: S, myPlayerId: string, serverTime: number) => void	Yes	state 更新時のコールバック
inputs	(patch: PatchFn, set: SetFn) => void	Yes	入力ハンドラ
events	Record<string, (data) => void>	No	ゲームイベントハンドラ
connection	ConnectionCallbacks	No	接続状態・エラーコールバック
playerCount	number	Yes	プレイヤー数

Operation (JSON Patch)

interface Operation {
  op: 'replace' | 'add' | 'remove';
  path: string; // JSON Pointer パス
  value?: unknown; // SERVER_TIME sentinel 使用可
}

PlayerVoiceState

interface PlayerVoiceState {
  audioStatus: 'speaking' | 'listening' | 'muted' | 'unstable' | null;
}

SeededRandom

GameLogic.setup / update の引数で提供される決定論的乱数生成器。

メソッド	説明
float()	0.0〜1.0 の浮動小数点
int(max)	0〜max-1 の整数
pick(array)	配列からランダムに 1 つ選択
shuffle(array)	配列をシャッフル (新しい配列を返す)

SERVER_TIME

サーバー時刻 sentinel 定数 ('__SERVER_TIME__')。Patch の value に指定すると、サーバー側で Date.now() に自動置換される。

import { SERVER_TIME } from '@uzupj/uzu-sdk';
set('/meta/phaseStartedAt', SERVER_TIME);

Room API (Relay 用)

onRoom() コールバックで受け取る Room インスタンスのメソッド。

room.myId

string (readonly)。自分の playerId。

room.broadcast(msg)

自分以外の全メンバーにメッセージを送信。

room.broadcast({ type: 'attack', lines: 2 });

room.send(id, msg)

特定のプレイヤーにメッセージを送信。

room.on(type, handler)

メッセージタイプに対するハンドラを登録。受信データには __from (送信者 playerId) が含まれる。

room.on('attack', (msg) => {
  console.log(`${msg.__from} sent ${msg.lines} lines`);
});

URL パラメータ

パラメータ	説明
?server=	WebSocket サーバーの URL
?roomId=	ルーム ID。指定するとオンラインモード
?playerId=	プレイヤー ID
?players=	JSON エンコードされたプレイヤーリスト
?__dev=N	Dev ハーネスモード (N 画面)