# PNGTuberPlusTanu External Control API Specification

本ドキュメントは、PNGTuberPlusTanu が提供するローカル TCP ベース外部制御 API の仕様書です。 備忘録および外部公開を目的としています。
このファイルはChatGPTに自動生成させたHTMLを一部編集しています。

## 概要

- 通信方式: TCP
- ホスト: 127.0.0.1（ローカルのみ想定）
- ポート: 8766
- データ形式: UTF-8 JSON
- 1接続 = 1リクエスト / 1レスポンス

極端に悪意のある攻撃（DoS等）は想定していません。

## 基本通信仕様

### リクエスト

JSON オブジェクトを TCP で送信します。

    {
      "type": "<command>",
      ...
    }

### レスポンス（ACK）

必ず JSON で返却されます。

    {
      "ok": true | false,
      "code": "CODE_STRING",
      "message": "human readable message"
    }

## コマンド一覧

### model（モデルロード）

#### リクエスト

    {
      "type": "model",
      "path": "user://example/avatar.save"
    }

#### 動作

- 指定されたパスのアバターファイルをロードします
- ロード中の場合は拒否されます

#### 成功レスポンス

    {
      "ok": true,
      "code": "OK",
      "message": "model loaded"
    }

#### 失敗例

- MISSING_PARAM
- FILE_NOT_FOUND
- MAIN_NOT_FOUND
- AVATAR_ERROR

### zoom（カメラズーム）

#### リクエスト

    {
      "type": "zoom",
      "value": 1.2
    }

#### 動作

Camera2D の zoom を等倍で変更します。

#### 成功レスポンス

    {
      "ok": true,
      "code": "OK",
      "message": "zoom changed"
    }

#### 失敗例

- CAMERA_NOT_FOUND

### costume（コスチューム変更）

#### リクエスト

    {
      "type": "costume",
      "costume": 3
    }

#### 動作

モデル側で定義されている 1?10 のプリセット番号を指定し、 小物・衣装などの状態を変更します。

#### 成功レスポンス

    {
      "ok": true,
      "code": "OK",
      "message": "costume requested"
    }

#### 失敗例

- MAIN_NOT_FOUND

## ACKコード一覧

### 成功

コード | 説明
--- | ---
OK | 正常終了

### リクエストエラー

コード | 説明
--- | ---
MISSING_PARAM | 必須パラメータ不足
INVALID_JSON | JSON が不正、または Dictionary でない
UNKNOWN_COMMAND | 未定義コマンド

### 実行時エラー（Godot側）

コード | 説明
--- | ---
FILE_NOT_FOUND | 指定ファイルが存在しない
MAIN_NOT_FOUND | Main ノードが存在しない
CAMERA_NOT_FOUND | Camera2D が見つからない
AVATAR_ERROR | アバターロード処理でのエラー

### クライアント側エラー（参考）

以下は PNGTuberPlusTanu クライアント実装で使用されるコードです。

コード | 説明
--- | ---
RESPONSE_ERROR | 通信失敗、接続エラー、レスポンス JSON の解析失敗など

PNGTuberPlusTanu External Control API
Version: 現行（非バージョン固定）