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:
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.
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.
| 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¶
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.
RespondToDownload¶
Answers a DownloadConfirmationRequested signal.
| 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.
See PatchProgress.
LastPlan¶
The last DownloadPlanned information, or null before the first patch.
Client¶
The SDK's inner parts, for advanced use. See Advanced: the sub-clients.
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.
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.
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.
GETandHEADonly. 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,503and504. 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'sRetry-Afterwhen it sends one (seconds or a date), otherwise 0.5 s doubling up to 8 s, with up to 20 % jitter. ARetry-Afterlonger than 30 s is not waited out: the caller gets the429/503and can show it. - Control.
Otomo.Instance.Client.Http.Retry = RetryPolicy.Noneturns it off, ornew RetryPolicy { MaxAttempts = 5, RetryOnTimeout = true }changes it. Cancelling theCancellationTokenends 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)
- Copy
addons/otomo/into your game'saddons/folder. Godot's own C# project compiles it with the rest of your scripts; no NuGet package of otomo is needed. - Add the one NuGet package the hosting code needs to your game's
.csproj:<PackageReference Include="BouncyCastle.Cryptography" Version="2.4.0" />. - 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 |