API Reference

This section provides a comprehensive reference for the classes, functions, and events available in the RACE JS SDK. Each element includes detailed descriptions, parameters, return values, and code examples for clarity and ease of use.

Note: This reference focuses on the core SDK package (@race-foundation/sdk-core). Additional functionalities and APIs may be available in specific transport implementation packages (e.g., @race-foundation/sdk-solana).

Classes

AppClient

The AppClient class is the main interface for interacting with Race games on the client side.

Constructor:

constructor(opts: AppClientCtorOpts);

Properties:

• playerAddr: The wallet address of the player.

• playerId: The ID of the player within the game (if joined).

• gameAddr: The address of the Race game.

• gameContext: The GameContext object representing the current game state.

• info: The GameInfo object containing game details.

Functions:

• static initialize(opts: AppClientInitOpts): Promise<AppClient>: Initializes and returns a new AppClient instance.

• subClient(opts: SubClientInitOpts): Promise<SubClient>: Creates and returns a SubClient instance for interacting with a sub-game.

• getProfile(id: bigint): Promise<PlayerProfileWithPfp | undefined>: Retrieves the player profile associated with the given ID.

• getProfile(addr: string): Promise<PlayerProfileWithPfp | undefined>: Retrieves the player profile associated with the given address.

• makeSubGameAddr(subId: number): string: Generates the address for a sub-game based on the subId.

• join(params: JoinOpts): Promise<TransactionResult<void>>: Joins the player to the game with the specified parameters.

• exit(keepConnection?: boolean): Promise<void>: Exits the player from the game, optionally keeping the connection to the Transactor open.

• detach(): void: Disconnects the client from the Transactor server.

• submitEvent(raw: Uint8Array): Promise<void>: Submits a custom event to the game.

• submitEvent(customEvent: ICustomEvent): Promise<void>: Submits a custom event object to the game.

• submitMessage(content: string): Promise<void>: Submits a message to the Transactor, which is then broadcasted to all connected clients.

• getRevealed(randomId: number): Promise<Map<number, string>>: Retrieves the revealed hidden knowledge associated with the given randomness ID.

SubClient

The SubClient class is used to interact with sub-games launched by the main game.

Constructor:

constructor(opts: SubClientCtorOpts);

Properties:

• subId: The unique identifier of the sub-game.

• Inherits all properties and functions from BaseClient.

Functions:

• attachGame(): Promise<void>: Connects the client to the sub-game's event stream and initializes the game state.

Events

GameEvent

The GameEvent class is the base class for all events in Race Protocol.

Functions:

• kind(): EventKind: Returns the type of the event.

Custom Event

The Custom class represents custom game events defined by the developer.

Properties:

• sender: The ID of the player who sent the event.

• raw: The binary data of the custom event.

Built-in Events

The SDK defines various built-in events, such as:

• Init: Signals game initialization.

• Checkpoint: Indicates a checkpoint has been applied.

• EndOfHistory: Signals the end of the game history.

• Ready: Signals a player is ready.

• ShareSecrets: Contains secret shares for randomness or decisions.

• OperationTimeout: Indicates an operation timeout has occurred.

• Mask: Contains masked randomness data from a server.

• Lock: Contains locked randomness data from a server.

• RandomnessReady: Signals that randomness generation is complete.

• Join: Indicates new players have joined the game.

• ServerLeave: Indicates a server has left the game.

• Leave: Indicates a player has left the game.

• GameStart: Signals the start of the game.

• WaitingTimeout: Indicates a waiting timeout has occurred.

• DrawRandomItems: Represents a request to draw random items.

• DrawTimeout: Indicates a draw timeout has occurred.

• ActionTimeout: Indicates a player action timeout has occurred.

• AnswerDecision: Represents a player's answer to a decision.

• SecretsReady: Signals that secrets for revealing hidden knowledge are ready.

• Shutdown: Signals the game is shutting down.

• Bridge: Represents a custom event sent between games or sub-games.

These events are used by the Race Protocol and the game handler to manage the game flow and synchronize state across participants. Developers can use the SDK's event listeners to react to these events and update the game UI accordingly.

Additional Notes

This API reference provides a high-level overview of the main classes and events available in the RACE JS SDK. For more detailed information and specific usage examples, refer to the individual class and function documentation within the SDK codebase.