arcane_sdk/lib.rs
1//! Arcane game SDK core.
2//!
3//! Games build one [`ArcaneClient`] at launch, and pass it nothing: Arcane
4//! Powered hands the game process the id of the title in `ARCANE_GAME_ID` and
5//! the signed-in account in `ARCANE_USER_ID`. The client verifies ownership
6//! once and then holds the result in memory — that `user_id`, that `game_id`,
7//! the ownership status and the device fingerprint — so nothing downstream
8//! needs the id again.
9//!
10//! ```no_run
11//! use arcane_sdk::ArcaneClient;
12//!
13//! let client = ArcaneClient::init()?;
14//! println!("user={:?} owned={}", client.user_id(), client.is_owned());
15//! # Ok::<(), arcane_sdk::SdkError>(())
16//! ```
17//!
18//! Ownership is checked against a locally cached ticket when possible. If the
19//! ticket is missing or expired, the SDK asks the Arcane desktop app (loopback
20//! `127.0.0.1:39284`) to refresh online, opening the app via deep link when
21//! needed.
22//!
23//! `init` also opens a play session: one background thread reports playtime to
24//! the Arcane desktop app once a minute, and — while the player allows it —
25//! samples the frame rate in short windows if the game calls
26//! [`ArcaneClient::frame`]. It never blocks or fails `init`. See
27//! [`SessionSnapshot`].
28//!
29//! Achievements are opt-in and cost nothing until used: one line unlocks one,
30//! and it is idempotent, so a game can call it every time its condition holds.
31//!
32//! ```no_run
33//! # let client = arcane_sdk::ArcaneClient::init()?;
34//! client.achievements().unlock("first_blood")?;
35//! # Ok::<(), arcane_sdk::SdkError>(())
36//! ```
37//!
38//! Friends are the same shape: one call gives the list with `online` and
39//! `in_game` for this title, read straight from the Arcane desktop app.
40//!
41//! ```no_run
42//! # let client = arcane_sdk::ArcaneClient::init()?;
43//! client.friends().list()?;
44//! # Ok::<(), arcane_sdk::SdkError>(())
45//! ```
46//!
47//! P2P lobbies are another opt-in surface: Arcane hosts the lobby, the join
48//! code and the invitations, and carries each member's opaque connection blob.
49//! The game keeps its own netcode, or uses the coop network below.
50//!
51//! ```no_run
52//! # use arcane_sdk::Visibility;
53//! # let client = arcane_sdk::ArcaneClient::init()?;
54//! # let my_endpoint = b"udp://203.0.113.7:7777";
55//! let lobby = client.p2p().create_lobby(4, Visibility::FriendsAndCode, my_endpoint)?;
56//! for event in client.p2p().poll_events() { /* … */ }
57//! # Ok::<(), arcane_sdk::SdkError>(())
58//! ```
59//!
60//! The coop network carries the game's own messages between the members of a
61//! lobby, with no port to open: the Arcane desktop app connects the players
62//! directly, or through Arcane's relay when it has to.
63//!
64//! ```no_run
65//! # use arcane_sdk::{Channel, NetOptions, Peer};
66//! # let client = arcane_sdk::ArcaneClient::init()?;
67//! # let lobby_id = "3f2b9c1e-0d4a-4e7b-9a61-5c8e2f7d1b40";
68//! client.net().open(lobby_id, NetOptions::default())?;
69//! client.net().send(Peer::Host, Channel::Reliable, b"ready")?;
70//! # Ok::<(), arcane_sdk::SdkError>(())
71//! ```
72//!
73//! Failures are [`SdkError`], carrying a stable [`code`](SdkError::code), a
74//! player-facing [`message`](SdkError::message), a developer-facing
75//! [`hint`](SdkError::hint) and a [`context`](SdkError::context) key/value list.
76
77mod achievements;
78mod client;
79mod desktop;
80mod device;
81mod error;
82mod friends;
83mod net;
84mod p2p;
85mod paths;
86mod session;
87mod ticket;
88
89pub use achievements::{Achievement, Achievements, Unlock, MAX_ACHIEVEMENT_KEY_LEN};
90pub use client::{ArcaneClient, MAX_GAME_ID_LEN};
91pub use error::{ErrorCode, OwnershipStatus, SdkError};
92pub use friends::{Friend, FriendList, Friends};
93pub use net::{
94 Channel, Net, NetEvent, NetMessage, NetOptions, Peer, Route, MAX_RELIABLE_MESSAGE, MAX_UNRELIABLE_MESSAGE,
95};
96pub use p2p::{
97 Lobby, LobbyEvent, LobbyMember, LobbyOptions, LobbyPollingState, LobbyQuery, LobbySummary, P2p,
98 Visibility, JOIN_CODE_LEN, MAX_LOBBY_METADATA_BYTES, MAX_LOBBY_METADATA_KEY_LEN, MAX_LOBBY_METADATA_PAIRS,
99 MAX_LOBBY_METADATA_VALUE_LEN, MAX_LOBBY_PAYLOAD_LEN, MAX_LOBBY_SEARCH_RESULTS,
100};
101pub use session::{SessionSnapshot, TrackingState};
102
103pub mod ffi;