rc_client_set_event_handler

Provides a callback for notifying the emulator when things happen inside the runtime as the result of a call to rc_client_do_frame, rc_client_reset, or rc_client_deserialize_progress so the emulator can provide visual cues to the player.

Syntax

void rc_client_set_event_handler(
    rc_client_t* client,
    rc_client_event_handler_t handler
);

Parameters

client

The rc_client_t to associate the handler to.

handler

Function to call when various events happen during processing.

---

rc_client_event_handler_t

void (*rc_client_event_handler_t)(
    const rc_client_event_t* event,
    rc_client_t* client
);

event

Information about the event that occurred.

client

The rc_client_t that spawned the event.

---

rc_client_event_t

typedef struct rc_client_event_t
{
  uint32_t type;

  rc_client_achievement_t* achievement;
  rc_client_leaderboard_t* leaderboard;
  rc_client_leaderboard_tracker_t* leaderboard_tracker;
  rc_client_server_error_t* server_error;

} rc_client_event_t;

type

The type of event that occurred.

achievement

The achievement associated to the event (for achievement events).

leaderboard

The leaderboard associated to the event (for leaderboard events).

leaderboard_tracker

The leaderboard tracker associated to the event (for leaderboard tracker events).

server_error

Additional information about the error.

---

RC_CLIENT_EVENT_ACHIEVEMENT_TRIGGERED

An achievement was earned by the player. The handler should notify the player that the achievement was earned.

RC_CLIENT_EVENT_ACHIEVEMENT_CHALLENGE_INDICATOR_SHOW

A challenge achievement has become active. The handler should show a small version of the achievement icon to indicate the challenge is active.

RC_CLIENT_EVENT_ACHIEVEMENT_CHALLENGE_INDICATOR_HIDE

A challenge achievement has become inactive. The handler should hide the small version of the achievement icon that was shown by the corresponding RC_CLIENT_EVENT_ACHIEVEMENT_CHALLENGE_INDICATOR_SHOW event.

RC_CLIENT_EVENT_ACHIEVEMENT_PROGRESS_INDICATOR_SHOW

An achievement that tracks progress has changed the amount of progress that has been made. The handler should show a small version of the achievement icon along with the achievement->measured_progress text (for two seconds).

Only one progress indicator should be shown at a time. If a progress indicator is already visible, it should be updated with the new icon and text, and the two second timer should be restarted.

RC_CLIENT_EVENT_GAME_COMPLETED

All achievements for the game have been earned. The handler should notify the player that the game was completed (softcore) or mastered (hardcore), preferably with the user's display name for screenshot purposes, and the user's total playtime.

RC_CLIENT_EVENT_LEADERBOARD_STARTED

A leaderboard attempt has started. The handler may show a message with the leaderboard title and/or description indicating the attempt started.

RC_CLIENT_EVENT_LEADERBOARD_FAILED

A leaderboard attempt has failed. The handler may show a message with the leaderboard title and/or description indicating the attempt failed.

RC_CLIENT_EVENT_LEADERBOARD_SUBMITTED

A leaderboard attempt was completed. The handler may show a message with the leaderboard title and/or description indicating the final value being submitted to the server.

RC_CLIENT_EVENT_LEADERBOARD_TRACKER_SHOW

A leaderboard_tracker has become active. The handler should show the tracker text on screen.

Multiple active leaderboards may share a single tracker if they have the same definition and value. As such, the leaderboard tracker IDs are unique amongst the leaderboard trackers, and have no correlation to the active leaderboard(s).

RC_CLIENT_EVENT_LEADERBOARD_TRACKER_UPDATE

The leaderboard_tracker value has been updated. The handler should update the tracker text on the screen.

RC_CLIENT_EVENT_LEADERBOARD_TRACKER_HIDE

A leaderboard_tracker has become inactive. The handler should hide the tracker text from the screen.

RC_CLIENT_EVENT_LEADERBOARD_SCOREBOARD

A leaderboard entry has been successfully submitted and the server returned information about the player's rank and the top entries for the leaderboard_scoreboard.

RC_CLIENT_EVENT_RESET

The runtime is requesting that the emulator be reset. As part of the reset progress, the emulator should call rc_client_reset to inform the runtime that the reset occurred.

RC_CLIENT_EVENT_SERVER_ERROR

Called when a server error should be reported to the player. The handler should display the error.

This is only raised for errors that occur as the result of the runtime making server calls outside of rc_client_begin_ interactions (such as unlocking an achievement).

RC_CLIENT_EVENT_DISCONNECTED

An request to update the user's state on the server failed in a non-fatal manner and has been queued to be attempted again. The handler can place an indicator on the screen to show the user that their state is not synchronized.

RC_CLIENT_EVENT_RECONNECTED

All pending updates to the user's state have been completed. The handler can remove any indicator shown by the RC_CLIENT_EVENT_DISCONNECTED event.

Remarks

Minimum version: 11.0.0

See also

rc_client_deserialize_progress

rc_client_do_frame

rc_client_reset