VirMesh Protocol

Appearance

me.virmesh.worldInstance.createInstance ​

新しい world instance を作成します。

WorldServer 上に新しい instance を作成する private action です。 この action のサポートは任意です。単一 instance のみを提供する WorldServer は、この action を無効にして status+me.virmesh.action.not_supported を返せます。

draft

Endpoint

Method
POST
Path
/private/me.virmesh.worldInstance.createInstance
Auth
required
Host
VirMesh.WorldServer

Request schema

fromstringRequired

action 実行者の player identifier です。

payload.worldIdstringRequired

instance を作成する world identifier です。

payload.namestringOptional

表示用の instance 名です。省略時の扱いは WorldServer が決めます。

payload.capacityintegerOptional

希望する最大 player 数です。最終値は WorldServer のポリシーに従います。

payload.joinPolicystringOptional

希望する join policy です。public, invite, private のいずれかです。

signaturestringRequired

canonical JSON of { action, from, payload } に対する署名です。

Request example

{
  "from": "medi:player:ed25519:creator-public-key",
  "payload": {
    "worldId": "medi:world:ed25519:base64url-world-public-key",
    "name": "Friends Room",
    "capacity": 16,
    "joinPolicy": "invite"
  },
  "signature": "base64-signature-for-action-envelope"
}

Responses

201
status+me.virmesh.success.worldInstanceCreated

world instance が正常に作成されたことを示します。

Response body

payload.instanceworldInstanceRequired

作成された instance です。

References obj+me.virmesh.worldInstance.instance : WorldServer 上で稼働している world instance を表す object です。

idstringRequired

WorldServer が割り当てる instance identifier です。不透明な文字列として扱います。

worldIdstringRequired

この instance が属する world identifier です。形式は medi:world:<scheme>:<publicKey> です。

endpointstringRequired

この instance を管理する WorldServer の absolute URL です。

namestringOptional

表示用の instance 名です。

statestringRequired

open, full, closed のいずれかです。

playerCountintegerRequired

現在参加している player 数です。

capacityintegerRequired

参加可能な最大 player 数です。

joinPolicystringRequired

public, invite, private のいずれかです。

createdAtintegerRequired

instance を作成した epoch second です。

updated_atintegerRequired

instance metadata を更新した epoch second です。

worldProtocolsobject[]Required

この instance に接続するための protocol 一覧です。各要素は name, version, information を持ちます。

worldProtocols[].namestringRequired

protocol identifier です。例: me.virmesh.world.websocket。

worldProtocols[].versionstringRequired

protocol version です。

worldProtocols[].informationobjectRequired

当該プロトコルがこの instance への接続に必要とするパラメータです。キー・型・意味は worldProtocols[].name で識別されるプロトコル仕様が定義します。

Response example

{
  "payload": {
    "instance": {
      "id": "inst_01HZY9ABCDQ4Y6Z8A0B1C2D3E4",
      "worldId": "medi:world:ed25519:base64url-world-public-key",
      "endpoint": "https://worlds.example.com/",
      "name": "Friends Room",
      "state": "open",
      "playerCount": 0,
      "capacity": 16,
      "joinPolicy": "invite",
      "createdAt": 1770000200,
      "updated_at": 1770000200,
      "worldProtocols": [
        {
          "name": "me.virmesh.world.websocket",
          "version": "1.0.0",
          "information": {
            "uri": "wss://worlds.example.com/instances/inst_01HZY9ABCDQ4Y6Z8A0B1C2D3E4/session"
          }
        }
      ]
    }
  }
}

me.virmesh.worldInstance.createInstance が正常終了し、新しい instance を作成したことを示します。

400
status+me.virmesh.json.invalid_json

request body が JSON として解釈できないことを示します。

この status は body が壊れている、または JSON parser が受理できない形式で送られた場合に返ります。

Status payload

payload.messagestringRequired

実装依存の詳細メッセージです。

malformed json

{
  "status": "status+me.virmesh.json.invalid_json",
  "payload": {
    "message": "Request body must be valid JSON."
  }
}
400
status+me.virmesh.json.invalid_private_request

private request envelope の形式が不正であることを示します。

この status は private route が期待する from, payload, signature などの envelope 要件を満たさない場合に返ります。

Status payload

payload.messagestringRequired

実装依存の詳細メッセージです。

invalid private envelope

{
  "status": "status+me.virmesh.json.invalid_private_request",
  "payload": {
    "message": "Private request must contain the expected envelope fields."
  }
}
400
status+me.virmesh.json.unexpected_fields

許可されていない field が request に含まれていることを示します。

この status は strict validation が有効な route に未知の top-level field または payload field を送った場合に返ります。

Status payload

payload.messagestringRequired

実装依存の詳細メッセージです。

unexpected request fields

{
  "status": "status+me.virmesh.json.unexpected_fields",
  "payload": {
    "message": "Request contains unknown fields that are not allowed by this route."
  }
}
400
status+me.virmesh.json.invalid_payload

`payload`がactionの期待する形式ではないことを示します。

リクエストデータ自体はJSON objectとして解釈できたものの、 期待する形式と一致しない場合に使います。

Status payload

payload.messagestringRequired

検証に失敗した理由を表す詳細メッセージです。

invalid payload

{
  "status": "status+me.virmesh.json.invalid_payload",
  "payload": {
    "message": "送信されたペイロードが正しい形式ではありません。"
  }
}
401
status+me.virmesh.key.invalid_signature

署名の形式が不正、または署名検証に失敗したことを示します。

この status は署名文字列が base64 として不正な場合と、 復元できた署名が検証に失敗した場合に使われます。

Status payload

payload.messagestringRequired

実装依存の詳細メッセージです。

signature verification failed

{
  "status": "status+me.virmesh.key.invalid_signature",
  "payload": {
    "message": "Signature verification failed."
  }
}
403
status+me.virmesh.worldInstance.create_not_allowed

現在の player が world instance を作成できないことを示します。

この status は WorldServer が createInstance 自体はサポートしているが、対象 player や world policy により作成を拒否した場合に返ります。 createInstance をサポートしないサーバーは status+me.virmesh.action.not_supported を返します。

Status payload

payload.messagestringRequired

実装依存の詳細メッセージです。

404
status+me.virmesh.world.not_found

指定された world が見つからないことを示します。

この status は query.worldId に対応する world manifest を WorldServer が保持していない場合に返ります。

Status payload

payload.messagestringRequired

実装依存の詳細メッセージです。

501
status+me.virmesh.action.not_supported

要求した action が現在の server では利用できないことを示します。

指定されたactionがサーバー上で無効化されており、使用できないことを示します。

Status payload

payload.messagestringRequired

実装依存の詳細メッセージです。

action is disabled

{
  "status": "status+me.virmesh.action.not_supported",
  "payload": {
    "message": "registerAccountKeyによる登録がサポートされていません。"
  }
}