Neocortex Usage Gate

The NeocortexUsageGate class turns the read-only account and usage endpoints into simple flags and events, so your game can gate Smart NPC features gracefully instead of failing mid-conversation.

These endpoints are read-only. Results are cached, usage is only re-fetched when the cache is older than MinRefreshInterval (30 seconds by default), on an explicit refresh call, or via auto-refresh.

using Neocortex;

var usageGate = new NeocortexUsageGate();

if (await usageGate.CanUseService())
{
    smartAgent.TextToText("Hello!");
}
else
{
    // Fall back to scripted dialogue
}

Methods

CanUseService

Returns false when team credits are empty or the player/character is over a developer-configured cap. Uses the cached result when it is fresh, so it is safe to call before every chat message. Fails open: when no usage data is available at all (e.g. offline before the first fetch), it returns true rather than blocking the game.

• Parameters:
  • playerId (optional): Player to check. Defaults to the device unique identifier, which is the player ID the SDK sends on every chat request.
  • characterId (optional): Character to check.
• Returns: Task<bool>

RefreshUsage

Fetches usage from the server and raises the gating events.

• Parameters:
  • playerId (optional): Defaults to the device unique identifier.
  • characterId (optional): Character to include per-character usage for.
• Returns: Task<ApiUsageResponse>, null on failure (the last cached value stays in LastUsage).

ApiUsageResponse usage = await usageGate.RefreshUsage();
Debug.Log($"Status: {usage.status}, Credits: {usage.creditsRemaining}");

GetUsageCached

Returns usage, served from the cache while it is younger than MinRefreshInterval. Falls back to the last cached value when the request fails; null when nothing has ever been fetched.

• Returns: Task<ApiUsageResponse>

RefreshAccount

Fetches the developer account info (tier, email, credits remaining, next refresh date).

• Returns: Task<ApiAccountResponse>, null on failure (the last cached value stays in LastAccount).

ApiAccountResponse account = await usageGate.RefreshAccount();
Debug.Log($"Tier: {account.tier}, Credits: {account.creditsRemaining}");

StartAutoRefresh / StopAutoRefresh

Refreshes usage on a low-frequency interval until StopAutoRefresh is called or the application quits. Keep the interval high; these values change slowly.

• Parameters:
  • intervalSeconds: Refresh interval, 300 seconds by default.
  • playerId / characterId (optional): Passed to each refresh.

usageGate.StartAutoRefresh(intervalSeconds: 300f);

Events

Threshold events fire on the transition only, so a popup hooked to them shows once instead of on every refresh.

OnUsageUpdated

Raised after every successful usage fetch, with the latest ApiUsageResponse.

OnLowCredits

Raised once when team credits drop below the dashboard low-credit threshold.

OnCreditsEmpty

Raised once when team credits run out.

OnPlayerOverLimit

Raised once when the queried player goes over a developer-configured cap.

OnCharacterOverLimit

Raised once when the queried character goes over a developer-configured cap.

OnRequestFailed

Raised when a request fails (offline, invalid key, ...). The game keeps running.

usageGate.OnLowCredits += usage =>
{
    Debug.LogWarning($"Credits are low: {usage.creditsRemaining} remaining");
};
usageGate.OnCreditsEmpty += _ =>
{
    DisableSmartNpcFeatures();
};

Response Data

public class ApiUsageResponse
{
    public UsageStatus status;        // Ok, Low, or Empty
    public int creditsRemaining;
    public PlayerUsage player;        // Only present when a playerId was passed
    public CharacterUsage character;  // Only present when a characterId was passed
}

public class PlayerUsage
{
    public int interactionsToday;
    public int creditsUsedAllTime;
    public bool overLimit;
}

public class CharacterUsage
{
    public int creditsUsedAllTime;
    public bool overLimit;
}

public class ApiAccountResponse
{
    public string tier;
    public string email;
    public int creditsRemaining;
    public DateTime? nextRefresh;
}

Account Status Window

You can check your account status without leaving the editor via the Tools > Neocortex menu, which shows your tier, remaining credits, and next credit refresh using the same endpoints.