Skip to content

SDK reference

Everything the otomo Godot SDK offers your game code, in one page. For step-by-step use, see the guides: Install the SDK, Publish your first content update and Build a download screen.

All types are in the OtomoSdk namespace (C#'s way of grouping names, unrelated to otomo's settings namespaces), or a sub-namespace such as OtomoSdk.Patch. Add the matching using lines at the top of your script:

using OtomoSdk;           // Otomo, StartResult, SessionStatus, OtomoFormat
using OtomoSdk.Patch;     // PatchResult, RemoteConfig, PatchProgress, PatchPlan
using OtomoSdk.Http;      // OtomoError
using OtomoSdk.Session;   // PlayerProfile
using OtomoSdk.Lobby;     // ILobbyService, SessionLobbyService, FakeLobbyService, SoloMatch
using OtomoSdk.Matchmaking; // MatchState, MatchPlacement, MatchJoinResult, ITransportConnector
using OtomoSdk.Content;   // ContentManager, ContentState
using OtomoSdk.Economy;   // ShopClient, TaskClient, PurchaseAttempt, ClaimAttempt
using OtomoSdk.Hosting;   // peer-hosted matches
using OtomoSdk.Chat;        // ChatKind, ChatMessage, ChatPage, ChatChannelFeed

You only need the lines for the types your script names. Otomo.Instance.RemoteConfig works with just using OtomoSdk;.

On this page: Project settings · The Otomo autoload · Signals · StartResult · RemoteConfig · OtomoFormat · OtomoError · Progress types · The lobby · Matchmaking · Content packs · Announcements · Failed requests are retried · Account, social and economy routes · Peer-hosted matches · Installing the SDK · Team chat · Advanced: the sub-clients · Files on the player's computer


Project settings

Under Project Settings › General › Otomo › Config (switch on Advanced Settings to see them). Enabling the plugin creates them.

Setting Type Default Meaning
otomo/config/base_url text (empty: you must set it) The address of your otomo's gateway, such as https://play.example.com. There is no built-in address: with this empty the SDK stops at start-up with an error that names the setting, instead of guessing one (a build that quietly talked to localhost or to someone else's server is worse than one that refuses to start).
otomo/config/client_version text (empty) This build's version, major.minor.patch such as 1.2.0. Empty means: use application/config/version, or 0.0.0. Compared with a release's minimum client version.
otomo/config/channel text live Which content channel to download. Players can only read live (the server refuses any other channel without a developer token), so leaving the default is the safe choice; a QA build that follows staging needs a developer login and sets it here or with --otomo-channel.
otomo/config/verbose_log on/off on Print the SDK's steps to the Output panel. Secrets are never printed.
otomo/config/confirm_download_over_bytes number -1 Ask before downloading more than this many bytes: -1 never asks, 0 always asks. See DownloadConfirmationRequested.
otomo/config/away_after_seconds number 300 Seconds without any input before friends see the player as away. The next input shows them as before. 0 never.
otomo/content/pack_prefix text (empty: off) Release packs whose name starts with this are content packs: not downloaded at start-up but on demand by Otomo.Instance.Content (see Content packs). Empty (the default) turns content delivery off and every pack is a start-up pack, so a release whose packs merely share a prefix is unaffected until you opt in, for example with content_.
otomo/content/auto_download on/off on Start downloading missing content packs as soon as the release's catalog is known. Turn it off to download only when your game calls EnsureContentAsync.

Overriding the address or channel for one run. In a debug build (the editor, or a debug export) launching the game with -- --otomo-base-url=<address> on the command line uses that address instead of the setting, for that run only, and --otomo-channel=<name> does the same for the channel. This is useful with an SSH tunnel:

Godot_v4.7.2_console.exe --path C:\MyGame -- --otomo-base-url=http://localhost:8080

A game that chooses its server some other way (a build profile, a launcher, an environment variable) sets the static Otomo.SettingOverride (Func<string, string>, asked for "base_url" and "channel") from an autoload listed before Otomo; a non-empty answer wins over the project setting.

A release build ignores both arguments. The device id is the player's sign-in credential, so a crafted shortcut or launcher argument must not be able to send it to another host.

A second player on the same PC. The SDK keeps the player's identity (the device id) and tokens in user://otomo, which every copy of the game on one PC shares, so they all sign in as the same player. Launching with -- --otomo-data-dir=<folder> keeps that run's files in another folder, so it signs in as a new player. This is for testing only: it works in the editor and in debug exports, and a release export ignores it. The folder can be a user:// path or an absolute one. In the editor, open Debug › Customize Run Instances, set Run Instances to 2, and give instance 2 the launch arguments -- --otomo-data-dir=user://otomo-p2 (the first -- separates the game's own arguments from Godot's). Pressing Play then starts two players who can befriend and invite each other.


The Otomo autoload

The plugin adds a node named Otomo that Godot creates at start-up and keeps for the whole game. Reach it from any C# script as Otomo.Instance.

Otomo.Instance

The one Otomo node.

public static Otomo Instance { get; }

It's null only if the plugin isn't enabled, or before autoloads have been created (so not in any scene's _Ready).

StartAsync

Runs otomo's start-up sequence: patch, then log in, then create or fetch the player's profile. Call it once, from your first scene, and await it before loading any scene that uses patched content.

public Task<StartResult> StartAsync(CancellationToken ct = default)
Argument Meaning
ct Optional. Lets you cancel the sequence (for example if the player quits during a download). Leave it out normally.

Returns a StartResult saying how far it got. It doesn't throw when the server can't be reached; check the result instead.

StartResult result = await Otomo.Instance.StartAsync();
if (result.Patch == PatchResult.ClientTooOld) { /* ask the player to update the game */ }
else if (!result.LoggedIn) { /* offline: the game still has last time's content */ }

Calling it again later, for example after AuthenticationLost, runs the sequence again. Packs already mounted aren't mounted twice.

JoinMatchAsync

Task<JoinHandshakeResult> JoinMatchAsync(string address, int port, string ticket, CancellationToken ct = default)

Shows the Gameplay Proxy a join ticket (the values from the PartyLaunching signal) and waits for its answer. If the ticket had expired or was already used, it fetches a fresh one and tries once more. The result's Outcome is Accepted, Refused (with a RefusalReason) or NoAnswer. On Accepted, connect ENet to the result's Address and Port from its LocalPort. See Join a match.

SetPresenceStatusAsync

Task SetPresenceStatusAsync(PresenceStatus status, CancellationToken ct = default)

Changes the status friends see: online (the default while logged in), in a menu (InMenus), in a game (InGame), or away. The heartbeat that keeps the player "online" starts and stops by itself with login. The SDK also shows the player as away by itself after away_after_seconds without input, and as your chosen status again on the next input; while away, a new choice waits for that input. Session accepts at most one change every 10 seconds, so a quick change reaches friends with the next heartbeat (up to 20 s).

RemoteConfig

The settings documents from the current release. See RemoteConfig.

public RemoteConfig RemoteConfig { get; }

RespondToDownload

Answers a DownloadConfirmationRequested signal.

public void RespondToDownload(bool accept)
Argument Meaning
accept true downloads the release. false skips it: the game keeps the content it already has, and the patch result is Declined.

Calling it when nothing is waiting does nothing.

CurrentDownload

The latest download progress, for UI that updates every frame in _Process instead of using the DownloadProgress signal.

public PatchProgress CurrentDownload { get; }

See PatchProgress.

LastPlan

The last DownloadPlanned information, or null before the first patch.

public PatchPlan LastPlan { get; }

Client

The SDK's inner parts, for advanced use. See Advanced: the sub-clients.

public OtomoClient Client { get; }

Signals

Connect with += and a function whose parameters match, and disconnect with -= when your node leaves the scene tree:

public override void _EnterTree() => Otomo.Instance.LoggedIn += OnLoggedIn;
public override void _ExitTree()  => Otomo.Instance.LoggedIn -= OnLoggedIn;
private void OnLoggedIn() => GD.Print("Logged in!");

Download signals

Emitted during StartAsync, in this order: DownloadPlanned → (DownloadConfirmationRequested) → DownloadProgress (repeatedly) → PatchFinished.

DownloadPlanned: once, after checking and before downloading anything. Not emitted when offline or when the build is too old.

Argument Type Meaning
releaseId long The release being downloaded
fileCount int Files still to download. 0 means up to date.
bytesToDownload long Bytes still to download
bytesAlreadyHave long Bytes already on disk from an interrupted download

DownloadConfirmationRequested: only when confirm_download_over_bytes is 0 or more, and the download is larger than that. The download waits until you call RespondToDownload.

Argument Type Meaning
bytesToDownload long Bytes to download
fileCount int Files to download

DownloadProgress: at most every 100 milliseconds, and after every finished file.

Argument Type Meaning
bytesDone long Bytes downloaded so far
bytesTotal long Bytes in the whole download
filesDone int Files finished
filesTotal int Files in the download
currentFile string The name of the file being downloaded
bytesPerSecond double Current speed
etaSeconds double Seconds left; -1 while unknown

PatchFinished: once, at the end of patching.

Argument Type Meaning
result string Ready, OfflineReady, ClientTooOld or Declined (see PatchResult)
bytesDownloaded long Bytes actually downloaded
filesDownloaded int Files actually downloaded
seconds double How long patching took
errorCode string Empty on success, otherwise an error code such as network

Other signals

Signal Arguments When
PatchStateChanged string state Patching moved to another step: Checking, Downloading, Verifying, Mounting, Ready, OfflineReady, ClientTooOld
PatchProgress long done, long total Simple byte progress. DownloadProgress gives more detail.
RemoteConfigChanged (none) New settings documents were loaded. Re-read any values you cached.
LoggedIn (none) The player is logged in
LoggedOut (none) The player logged out
AuthenticationLost string code, string requestId A request was refused even after renewing the login. Return to your start screen and call StartAsync again. See Logins and tokens.
SessionEventReceived long seq, long at, string type, string payloadJson One event from Session (a friend came online, the party changed, an invite arrived). at is Unix milliseconds; payloadJson is the raw payload or empty.
Resync (none) Some events were missed (the game was offline, or Session restarted). Re-fetch the friends list and party with normal calls.
PartyLaunching string allocationId, string address, int port, string ticket, long ticketExpiresAtUnixMs A game server was reserved for this player. Pass address, port and ticket to JoinMatchAsync. See Join a match.
PartyLaunchFailed string reason No game server was available: no_capacity or allocator_unavailable. The lobby is forming again.
PartyReturned string reason The match is over (ended, expired, server_dead or server_restarted). The lobby is forming again with ready flags cleared.
MatchQueued string partyId, string ticketId, string poolId, long queueTimeoutAtUnixMs The party entered a matchmaking queue. queueTimeoutAtUnixMs is when the queue ends without a match (0 if unknown). See Matchmaking.
MatchFound string matchId, string transport, string region The party was placed in a match. Join it with Client.Matchmaking.JoinAsync.
MatchCancelled string partyId This player's cancel took the party out of the queue.
MatchFailed string partyId, string reason The queue ended without a match: timeout or queue_closed. The party can queue again.
MatchReturned string matchId, string reason The matchmade match is over (ended, expired, server_dead or server_restarted). The party can queue again.
MatchStatusChanged string state The party moved between idle, queued and in_match, for any reason, including the leader cancelling.
ChatMessageReceived string channel, long seq, string sender, string body, string text, string lang, bool translated, string attachment, long sentAtUnixMs A message arrived in a feed opened with OpenChatFeed. Show text: it is the translation into the feed's language when translated, else body. See Team chat.
ChatTypingChanged string channel, string[] players Who else is typing in a chat feed changed.
ChatFeedEnded string channel, string code A chat feed stopped because retrying cannot help: not_a_member, channel_expired, not_found or invalid_request.

StartResult

What StartAsync returns.

Property Type Meaning
Patch PatchResult How patching ended (below)
LoggedIn bool Whether the player is logged in
Profile PlayerProfile The player's profile, or null if Session couldn't be reached
Session SessionStatus How the Session step went (below)
Error OtomoError What stopped the sequence, or null if nothing did

PatchResult (in OtomoSdk.Patch):

Value Meaning What your game should do
Ready The newest content is downloaded and loaded Carry on
OfflineReady Otomo couldn't be reached; the last good content is loaded (or none, on a first run) Carry on; online features won't work
ClientTooOld This build is older than the release's minimum client version. Nothing was loaded. Tell the player to update the game
Declined The player declined the download; the old content is loaded Carry on

SessionStatus:

Value Meaning
Available Session answered, and Profile is set
NotAttempted Session wasn't tried, because the login failed
Failed Session was tried and failed; see Error
NotImplemented Left over from early development; current servers never cause it

PlayerProfile:

Property Type Example
PlayerId string 01a0ecdd-ed9c-758a-… (a unique ID)
DisplayName string Player1676 (a temporary name until the player chooses one)
Discriminator int 9062, the number that tells apart players with the same name

profile.ToString() gives Player1676#9062.


RemoteConfig

The client settings documents of the current release. Each Get… function takes the namespace (the document's name), a key, and a fallback returned when the value is missing or has the wrong type. It never throws.

Keys with dots reach into nested objects: with the document {"spells": {"fireball": {"damage": 20}}}, the key spells.fireball.damage gives 20. An empty key "" means the whole document.

GetInt, GetFloat, GetBool, GetString

public int    GetInt   (string doc, string key, int fallback)
public float  GetFloat (string doc, string key, float fallback)
public bool   GetBool  (string doc, string key, bool fallback)
public string GetString(string doc, string key, string fallback)
Argument Meaning
doc The namespace, such as "balance.player"
key The key inside it, such as "max_hp" or "spells.fireball.damage"
fallback Returned if the namespace or key doesn't exist, or the value is the wrong kind (text where a number was expected)
var config = Otomo.Instance.RemoteConfig;
int maxHp = config.GetInt("balance.player", "max_hp", 100);

GetInt returns the fallback for a number with decimals (5.5); use GetFloat for those.

TryGet

For values the Get… functions don't cover, such as lists. Returns true and the raw JSON value if it exists.

public bool TryGet(string doc, string key, out System.Text.Json.JsonElement value)
if (config.TryGet("events.winter", "regions", out var regions))
    foreach (var region in regions.EnumerateArray())
        GD.Print(region.GetString());

Names

The names of all loaded documents.

public IReadOnlyCollection<string> Names { get; }

OtomoFormat

Helpers for showing sizes and times to players.

public static string OtomoFormat.Bytes(long bytes)
public static string OtomoFormat.Duration(double? seconds)
Call Result
OtomoFormat.Bytes(0) 0 B
OtomoFormat.Bytes(1536) 1.5 KB
OtomoFormat.Bytes(12_900_000) 12.3 MB
OtomoFormat.Duration(null) -- (unknown)
OtomoFormat.Duration(12) 12 s
OtomoFormat.Duration(185) 3 min 5 s
OtomoFormat.Duration(3720) 1 h 2 min

Sizes are in steps of 1024.


OtomoError

Every problem the SDK reports is an OtomoError, a C# exception with these properties:

Property Type Meaning
Status int The HTTP status code, or 0 if the server never answered (no connection, timeout)
Code string A short, fixed word such as network or not_in_party. See Error codes.
Message string A sentence for humans
RequestId string The request's ID in the server logs. Include it in bug reports.
IsRetryableLater bool true when trying again later might work (no connection, 429, 5xx)

Progress types

In OtomoSdk.Patch.

PatchProgress (from CurrentDownload): BytesDone, BytesTotal, FilesDone, FilesTotal, CurrentFile, BytesPerSecond, and EtaSeconds (null while unknown). The same values as the DownloadProgress signal.

PatchPlan (from LastPlan): ReleaseId, FileCount, TotalBytes, AlreadyHaveBytes, BytesToDownload, IsUpToDate, and Files, the list of files to download, each with its Kind (config or pack), Name, Sha256, Size and AlreadyHave (bytes already on disk).


The lobby

OtomoSdk.Lobby is a ready-made layer for menus: friends, the party (which is the lobby), invites, launch and the join handshake behind one interface, ILobbyService, with plain records (PartyInfo, FriendsSnapshot, LobbyInvite, MatchTicket, MatchJoin) and one exception type, LobbyException, whose Code is the server's error code and whose Message is a short sentence you can show as-is.

Type What it is
SessionLobbyService The real lobby: new SessionLobbyService(Otomo.Instance.Client, profile?.PlayerId). Keeps the event stream's replayed history (old invites, spent tickets) out of your menu, and raises its events on the thread StartAsync was called on.
FakeLobbyService The same lobby played locally, for building and testing menus offline. FakeLobbyOptions sets the player, the local game server a launch sends everyone to, the allowed lobby settings, and whether scripted friends join, invite you and launch.
Also: KickAsync and DisbandPartyAsync (leader), RemoveFriendAsync, BlockAsync / UnblockAsync / GetBlockedAsync. FriendInfo carries each friend's Status (kept current from presence.changed) and their party's PartySize/PartyMax.
SoloMatch JoinAsync(lobby, log): a match for this player alone with no lobby screen (create or reuse a party, ready, launch, handshake). For "play now" developer buttons.
var lobby = new SessionLobbyService(Otomo.Instance.Client, startResult.Profile?.PlayerId);
lobby.PartyChanged += party => RenderParty(party);          // null: no party
lobby.InviteReceived += invite => ShowInvite(invite);
lobby.Launching += async match =>
{
    MatchJoin join = await lobby.HandshakeAsync(match);
    // ENetMultiplayerPeer.CreateClient(join.Match.Address, join.Match.Port, localPort: join.LocalPort),
    // then send join.Match.Ticket to the game server.
};
await lobby.StartAsync();                                    // from the main thread
PartyInfo party = await lobby.GetPartyAsync() ?? await lobby.CreatePartyAsync();

Matchmaking

Otomo.Instance.Client.Matchmaking (OtomoSdk.Matchmaking) puts a party in a queue with strangers, follows it to a match and joins it. The party leader queues and cancels; every member reads the state and joins. Your game never names a transport: the match's placement says which one it uses, and the SDK picks the connector registered under that name.

Member What it does
QueueAsync(partyId, poolId, settings, revision?) Queues the party (leader only) in a pool with the lobby settings. Calling it again answers the same ticket.
GetStateAsync(partyId) Reads where the party stands: Idle, Queued (with Position and QueueTimeoutAt) or InMatch (with Match). Members call this when the party shows queued.
CancelAsync(partyId) Takes the party out of the queue (leader only). Safe to repeat.
JoinAsync(placement) Joins the match: gets this player's credential, hands the placement to its transport's connector, and gets one fresh credential if the first is refused as expired or used.
GetTicketAsync() A fresh credential for this player's live match: what JoinAsync uses, and the way back into a match after a restart.
Current The last state read.
Connectors The connector registry: Register(transport, connector), Unregister, Names. otomo-udp is registered by default.

While the party is queued the SDK reads its state every 2 seconds (PollInterval), so a match is found even if an event is missed. Its events are Queued, Matched, Cancelled, Failed, Returned and StatusChanged; the autoload raises them as the Match* signals above.

var mm = Otomo.Instance.Client.Matchmaking;
mm.Matched += async placement =>
{
    MatchJoinResult join = await mm.JoinAsync(placement);
    if (join.Outcome == MatchJoinOutcome.Connected && join.Connection is JoinHandshakeResult udp)
    {
        // otomo-udp: ENetMultiplayerPeer.CreateClient(udp.Address, udp.Port, localPort: udp.LocalPort),
        // then send udp.Ticket to the game server.
    }
    // MatchJoinOutcome.Returned: the match ended while joining. Go back to the lobby.
};
await mm.QueueAsync(party.PartyId, "default", party.Settings);

Your own transport. Implement ITransportConnector.ConnectAsync(placement), read your transport's fields from placement.Descriptor, pass placement.Credential.Value to whatever your transport checks, and register it: mm.Connectors.Register("my-transport", new MyConnector()). Return ConnectorResult.CredentialRejected only when a new credential could help. A placement whose transport has no connector falls back to the one named by its descriptor's meta.protocol, and otherwise JoinAsync answers NoConnector.

A runnable example is godot-plugin/samples/Matchmaking: two fresh players queue one lane and join one match.


Content packs

Packs whose name starts with otomo/content/pack_prefix (default content_) are not downloaded by the start-up patch. They are downloaded and mounted on demand, after your main menu is up, by Otomo.Instance.Content (a ContentManager). The release's content.packs config document says what each pack is for; without it every content pack is required for everything and has no dependencies.

{ "packs": [
  { "name": "content_arena",  "depends_on": ["content_core"], "required_for": ["arena"] },
  { "name": "content_core",   "required_for": ["*"], "probe": "res://content/core_marker.tres" }
] }
Field Meaning
name The pack's name in the release manifest.
depends_on Packs mounted before this one.
required_for Feature names this pack is needed for; "*" or empty means everything. The names are yours.
replace_files true lets the pack overwrite files that already exist in the game build. Default false: a pack may add files but never replace the base build's. Opt in per pack, only for packs you control.
probe A res:// path. If it already resolves (the pack is part of this build, for example in the editor), the pack is not downloaded.
Member of Otomo.Instance What it does
await CheckContentAsync() Makes sure a catalog is known: runs the patch once if nothing has run yet. Call it when the main menu opens.
await EnsureContentAsync(feature) Downloads, verifies (SHA-256) and mounts what feature needs ("*" for everything). True when ready.
Content.IsReady(feature), Content.Plan(feature) Whether it is ready, and what a download would fetch (packs, bytes, bytes already on disk).
Content.State, Content.Progress ContentState: Unknown, Ready, NeedsDownload, Downloading, Verifying, Mounting, Failed (ErrorMessage), RestartRequired.
Signals ContentStateChanged, ContentProgress, ContentPackMounted For a download screen. Progress arrives at most every 100 ms; the eta is -1 while unknown.
RestartGame() Restarts with the same command line, to finish an update of a pack that was already mounted (Godot keeps loaded resources in its cache, so a restart is the only clean swap).

A content pack must hold assets only: the SDK reads the pack's file list before mounting and refuses one that carries code (.cs, .gd, native libraries) or project files.

Announcements

Otomo.Instance.ActiveAnnouncements(locale = null) returns the announcements to show now, from the release's announcements document: published, inside their window on the server's clock, one per id in the best language (the given locale, else the same language, else English; null means the game's current locale). Call it again after RemoteConfigChanged. The server's clock is the Date header of the last manifest answer, exposed as RemoteConfig.ServerNow and RemoteConfig.ServerClockOffset: use it, not DateTime.UtcNow, for any time-boxed document entry.

Failed requests are retried

Every call through OtomoHttp retries a transient failure by itself, so a screen does not have to:

  • Which calls. GET and HEAD only. Any other call is retried only when it says so (retry: true); the SDK does that for the calls that carry an idempotency key or are idempotent by design (shop purchase, task claim, roll, follow, display slots, session revoke).
  • What. A connection that failed before any answer, and the answers 429, 502, 503 and 504. A timeout is not retried by default.
  • How long. At most 3 attempts in all, shared by the whole call (including the resend after a login refresh), and at most 45 s of waiting (RetryPolicy.TotalBudget): a retry that would go past it is not made. The wait is the server's Retry-After when it sends one (seconds or a date), otherwise 0.5 s doubling up to 8 s, with up to 20 % jitter. A Retry-After longer than 30 s is not waited out: the caller gets the 429/503 and can show it.
  • Control. Otomo.Instance.Client.Http.Retry = RetryPolicy.None turns it off, or new RetryPolicy { MaxAttempts = 5, RetryOnTimeout = true } changes it. Cancelling the CancellationToken ends the wait and the call at once. Each attempt has its own timeout.

The background loops (events, presence) keep their own back-off and are not retried a second time.

Account, social and economy routes

Sub-clients on Otomo.Instance.Client, all async, all throwing OtomoError on failure (branch on Code). Economy calls that can be refused for a business reason (not enough coins, an offer that is closed) do not throw: they return an attempt object with the code.

Property Calls Notes
Account ListSessionsAsync(), RevokeSessionAsync(familyId), RevokeAllSessionsAsync(), DeleteAccountAsync() A session is one login (a device or an install); Current marks this one. RevokeAll and DeleteAccount also forget the tokens held here, as LogoutAsync does. After DeleteAccountAsync the next StartAsync signs in with the same device id as a new account.
Profile CheckNameAsync(name), RenameAsync(name), TryRenameAsync(name), GetDisplayAsync(), SetDisplayAsync(slot, itemId), ClearDisplayAsync(slot) CheckNameAsync answers Available or a reason (invalid, reserved, cooldown, taken); at most 30 a minute, so check when the player stops typing. TryRenameAsync returns a RenameResult instead of throwing: the new profile, or InvalidName (with Rule and the length limits), NameTaken, Cooldown (with RetryAfter), NoProfile, Network or Server. PlayerProfile.NextRenameAt and CanRenameNow say when the rename button can be enabled. Display slots show an owned item on the player's card; which slots exist is your session rules.
Follows FollowAsync(name, number), FollowByIdAsync(id), UnfollowAsync(id), ListFollowersAsync(), ListFollowingAsync(), CountAsync() One-way, no consent, separate from friends.
FriendInvites GetAsync(), RotateAsync(), RedeemAsync(code) A code that makes redeemer and owner friends at once. Can be turned off by the deployment (invites_disabled).
Rank ListAsync(), GetAsync(ruleType), GetBoardAsync(ruleType, limit, offset, following, namedOnly) Read-only. The board answers one page and the player's own place (You).
Shop ListOffersAsync(), PurchaseAsync(offerId, quantity, key) The price is the server's; a refusal is a PurchaseAttempt with Code (insufficient_funds, offer_closed, offer_limit_reached, unknown_offer, stack_overflow, insufficient_items).
Tasks ListTracksAsync(), ClaimAsync(trackId, key) A claim refusal is a ClaimAttempt (not_claimable, unknown_track). A track with AutoClaim pays itself.
Entitlements ListAsync() Rewards owed and not yet collected. Read-only here: a game server claims them.

Session.GetMeAsync() now also returns the player's Display map and the game's own Ext document. The obsolete Crafting client (and FakeCraftingClient) are gone: a craft is a roll by payment (Pools.RollByPaymentAsync).

Peer-hosted matches

A queue can place a party on a peer-hosted room (transport p2p_host, alias otomo-p2p) instead of a dedicated server: one player's game is the host, the others join through otomo's Gameplay Proxy. The SDK has the whole protocol in OtomoSdk.Hosting, and registers the client side of it by default (OtomoP2PConnector, so Matchmaking.JoinAsync works for these rooms with no extra code). Nothing in it is specific to a game.

Type Role
P2PWireContract Every path, field and datagram constant of p2p-wire/1 (docs/p2p-wire-contract.md).
MatchHostClient, HostSession The host: claims the host role, verifies the signed roster, attaches to the relay, resumes after a dropped link, reports the outcome. HostSession.LocalServerPort is the loopback port your listen server must bind.
HostRelayBridge, RelayFrame, SlotTable Forwards each remote player to the listen server from its own loopback port.
SignedRoster, RosterVerifier, PeerTicketVerifier, JwksClient, TicketVerifier Who may be in the match (otomo-signed, Ed25519 checked against the Allocator's public keys) and with which items. JwksClient.ForGateway(baseUrl) fetches the keys from {gateway}/p2p/v1/placement-keys; it requires https (http only on loopback), and a key that leaves the document is distrusted after a 10-minute grace.
MatchPeerClient, FactOutbox Every player reports its own facts and its view of the outcome, with its own token, through a durable outbox.
ServiceKeyGuard The host holds no service key and pays nobody: rewards are decided and paid by otomo from the claims.

The host code needs BouncyCastle.Cryptography (Ed25519), a NuGet package that your game must reference even if it never hosts (the folder is always compiled); see Installing. What stays in your game is the glue to your own networking: starting the listen server on LocalServerPort, and mapping your match result to a MatchOutcome. Core/Hosting/TODO-wire-contract.md lists the few places that still depend on server behaviour the contract does not pin down.

Installing the SDK in a Godot project

The SDK is plain C# with no Godot types, plus a thin Godot layer:

godot-plugin/
  addons/otomo/            <- what you copy into your game
    Core/                  the Godot-free SDK (every client, hosting, content)
    Otomo.cs               the autoload (signals, settings, mounting packs)
    OtomoPlugin.cs         the editor plugin
    plugin.cfg
  src/Otomo.Sdk/           Otomo.Sdk.csproj: compiles addons/otomo/Core with no Godot reference
  tests/Otomo.Sdk.Tests/   unit tests (plain `dotnet test`, no Godot needed)
  1. Copy addons/otomo/ into your game's addons/ folder. Godot's own C# project compiles it with the rest of your scripts; no NuGet package of otomo is needed.
  2. Add the one NuGet package the hosting code needs to your game's .csproj: <PackageReference Include="BouncyCastle.Cryptography" Version="2.4.0" />.
  3. Build once, then enable Otomo SDK under Project Settings › Plugins.

To use the SDK outside Godot (a dedicated server, a bot, a tool, a test), reference godot-plugin/src/Otomo.Sdk/Otomo.Sdk.csproj from your project, or build it (dotnet build -c Release godot-plugin/src/Otomo.Sdk) and reference Otomo.Sdk.dll. It targets net8.0 (the version Godot 4 .NET runs on) and has the same public API. Every client takes an IOtomoTransport (OtomoHttp is the real one), and OtomoHttp takes your HttpClient, so a test can pass a fake HttpMessageHandler.

Team chat

Otomo.Instance.Client.Chat (OtomoSdk.Chat) reads and writes a party's, a match's or the global channel, with machine translation into the reader's language. See Team chat for the guide and the server side.

Member What it does
ReadAsync(kind, scope, after, lang, waitSeconds, typingTag) Reads the channel after after; with no after it answers the latest page. waitSeconds (0 to 25) lets the server hold the call until something is new. Answers a ChatPage: Messages, Typing (the others typing), TypingTag and Cursor, the after for the next read.
SendAsync(kind, scope, body, key, attachment) Sends a message. key is your idempotency key: a retry with the same key answers the stored message and never posts twice.
SetTypingAsync(kind, scope, typing) Says the player is typing (lasts a few seconds; refresh it) or stopped. At most about two calls a second.
OpenFeed(kind, scope, lang) A ChatChannelFeed: the long-poll loop. Start(), StopAsync(), events MessageReceived, TypingChanged, ReadFailed, Ended. It delivers each message once, in order, backs off on errors, never polls faster than MinPollInterval and stops itself when the player is not a member. Events are raised on the context Start was called on.

kind is ChatKind.Party, ChatKind.Match or ChatKind.Global; scope is the party or match id (ignored for global). A ChatMessage has Seq, Sender, Body (what was written), Text (what to show), Lang, Translated, Attachment and SentAt. From a node, Otomo.Instance.OpenChatFeed(kind, scope, lang) opens and starts a feed and raises it as the ChatMessageReceived, ChatTypingChanged and ChatFeedEnded signals. Feeds stop on logout.

Errors are OtomoErrors with chat's codes: not_a_member (403), rate_limited (429, with Retry-After), too_long, refused_words, empty_message, attachment_unknown, attachment_not_owned, channel_expired (410) and membership_unavailable (503). See Error codes.


Advanced: the sub-clients

Otomo.Instance.Client holds the parts the autoload is built from. Most games never need them.

Property What it is Useful members
Patch The updater RunAsync(): check for new content again (for example every few minutes in the main menu). RequiredClientVersion: the minimum version when the result was ClientTooOld. ConfirmDownload: your own async "ask the player" function, replacing the project setting.
Auth Logins IsLoggedIn. LogoutAsync(): log out and forget the saved login (the device ID is kept).
Session Session calls GetMeAsync(): the player's profile.
Presence Online status Started and stopped automatically with login. Change what it reports with Otomo.Instance.SetPresenceStatusAsync.
Friends Friends and blocks ListAsync(), RequestAsync(displayName, discriminator), AcceptAsync(playerId) and more.
Party Parties and the lobby CreateAsync(), GetAsync(), InviteAsync, AcceptInviteAsync, LeaveAsync, KickAsync, PromoteAsync, UpdateSettingsAsync, SetReadyAsync, LaunchAsync, GetLaunchTicketAsync. See Join a match.
Launch The Gameplay Proxy handshake JoinAsync(info), which Otomo.Instance.JoinMatchAsync wraps.
Matchmaking Queues with strangers See Matchmaking.
Chat Team chat See Team chat.
Recordings Replays: list, download, upload, report Not a property: var rec = Otomo.Instance.Client.CreateRecordings(httpClient) builds a RecordingsClient. See Record and share replays. ListMineAsync, ListByTagAsync, ListCuratedAsync, DownloadAsync (resumes, checks the SHA-256, refuses redirects), UploadAsync (the match's host only; retries; returns an UploadResult with a RecordingFailure), ReportAsync, SetVisibilityAsync. It moves and verifies bytes and never opens a replay.
Http The shared HTTP sender SendAsync<T>(method, url, body): an authenticated request to any otomo route, with the login renewed automatically and transient failures retried (see Failed requests are retried).
// Check for new content again, from the main menu.
PatchResult r = await Otomo.Instance.Client.Patch.RunAsync();

Files on the player's computer

In the game's user data folder (Project → Open User Data Folder in the editor), under otomo/:

Path Contents If deleted
device_id The player's identity. It is the account. A new, empty account is created
refresh_token The saved login The game logs in again with device_id
patch/manifest.json The last good release Downloaded again
patch/blobs/ Downloaded files, named by fingerprint Downloaded again