SDK Cache Mechanism

How the GS2 SDK caches data internally and design guidelines for taking advantage of it
Tags:

The GS2 game-engine SDKs (GS2 SDK for Unity, GS2 SDK for Unreal Engine, and so on) have a built-in cache that keeps data fetched from the server inside the SDK. Understanding this cache helps you reduce the number of API calls and improves both responsiveness and cost.

Basic behavior

When you fetch data through a Domain object (an access pattern such as gs2.Inventory.Namespace(...).Me(...).Inventory(...)), the fetched data is stored in the SDK’s internal cache. Subsequent reads for the same resource are served from the cache without sending a request to the server.

You can therefore look up the same value through Domain objects as many times as you need throughout your UI without re-fetching it from the server each time.

Automatic cache refresh

When data is updated on the server, the SDK cache is automatically updated to stay in sync. The cache is refreshed at the following times:

  • When resource information is included in an API response received by the SDK
  • When an update notification for a resource is delivered over a WebSocket connection
  • When resource information is returned as the result of a stamp sheet execution

For example, when an item is purchased through Gs2-Showcase, the increase of the corresponding Gs2-Inventory item count carried in the response of the purchase API is automatically reflected in the SDK cache. There is no need for the UI side to manually “re-fetch the inventory list”.

Design guidelines

Don’t hesitate to call read APIs

Read operations performed through Domain objects, such as ModelAsync / Model / Fetch, will issue a request to the server on the first call and serve subsequent calls from the cache. As a result, even if your UI reads a value every time it redraws, this will not lead to excessive request charges.

// Even if called on every UI redraw, calls after the first one are served from the SDK cache
var item = await gs2.Inventory.Namespace("namespace-0001")
    .Me(GameSession)
    .Inventory("inventory-0001")
    .ItemSet("item-0001")
    .ModelAsync();

Subscribe to cache updates

Domain objects expose an event mechanism that lets you observe when the SDK’s internal cache is updated. By subscribing to these events from your UI, you can reflect changes such as item count updates without polling.

For details, see the reference of each game-engine SDK.

When you must read straight from the server

The low-level APIs (those invoked directly through Gs2*RestClient / Gs2*WebSocketClient) always send a request to the server and bypass the cache. Use these low-level APIs when you must guarantee that you see the latest state on the server, such as for server-side re-validation against cheating.

Behavior during zone failover

A GS2 region is composed of multiple zones running in an Active / Active configuration (see Region). Because there is a slight replication delay between zones, you may experience a brief moment after a zone switch where “a value that was supposedly written cannot be read back”.

The SDK cache is designed so that a UI does not get stuck on a stale value through such transient inconsistencies; it keeps up with the latest state on a best-effort basis. The cache converges to the latest values in the new zone without any extra work from the game developer.