Godot SDK reference

GDScript methods, typed results, feature snapshots, and scene-safe subscriptions.

The Nuxie autoload provides the GDScript interface for identity, Experiences, and access. Install and configure the addon, then call its methods on the Godot thread.

Configuration

Await Nuxie.configure(options) with a NuxieOptions resource:

Use the public pk_test_ key for preview content and the pk_live_ key for live content. Keep the default service environment for both. The development environment selects a separate Nuxie service; it does not select test mode for your app.

Changing the options resource after configuration does not change the session. Equivalent configuration calls share setup; await shutdown() before changing configuration or the purchase controller.

is_available() reports whether the native bridge is present. get_status() returns a NuxieStatus with kind: UNCONFIGURED, CONFIGURING, READY, SHUTTING_DOWN, or FAILED, and an optional error. Availability does not test network connectivity.

Identify a player

var result: NuxieResult = await Nuxie.identify("player-123")
if not result.ok:
    push_error(result.error.message)

Await get_identity() to receive a NuxieIdentityResult. After checking result.ok, read distinct_id, anonymous_id, and is_identified from result.value. Call reset() on sign-out to rotate the anonymous ID. Await each identity change before starting another.

Pass NuxieIdentityOptions to identify() for properties to update and properties_set_once to set only when absent. set_locale(locale) changes the app’s locale; an empty string restores the device locale.

Trigger an Experience

var result: NuxieResult = await Nuxie.trigger("shop_requested")
if not result.ok:
    push_error(result.error.message)

A successful result acknowledges the event. The published delivery rules determine whether an Experience appears. Use dismiss() to close the current presentation.

Event properties and customer attributes accept finite JSON values with string keys. Do not pass Nodes, Resources, cycles, or more than 32 nested levels. Integer values must fit within the portable exact range, from -9,007,199,254,740,991 to 9,007,199,254,740,991.

Check feature access

var result: NuxieFeatureResult = await Nuxie.check_feature("premium")
if result.ok and result.value.allowed:
    # Enable the premium feature.
    pass

Pass a NuxieFeatureQuery to set required_balance, entity_id, or a cache policy. get_feature_state() reads current access without a request. Its state is UNKNOWN while loading, RECONCILING while purchase access is being synchronized, or READY. Show a loading or neutral UI while access is unknown.

Access and snapshots

NuxieFeatureAccess contains allowed, unlimited, nullable balance, and type: boolean, metered, or creditSystem. A feature query never consumes usage.

NuxieFeatureQuery.required_balance defaults to 1. Set policy to NuxieFeatureQuery.Policy.REMOTE to request current access from the server; the default is CACHE_FIRST. Entity-specific query results do not replace the global snapshot.

get_feature_snapshot() returns kind, customer_id, identity_generation, and revision. The counters are decimal strings to preserve their exact values. Call select(feature_id) for one NuxieFeatureState, or get_all() for a dictionary of access values. A state can be ready with no access entry.

Consume usage

var command := NuxieFeatureCommand.new()
command.operation_id = "generation-123"
command.quantity = 5

var result: NuxieUsageResult = await Nuxie.consume_feature("credits", command)
if result.ok and result.value.accepted:
    # Apply the action once.
    pass

Save the operation ID before sending. Reuse it for retries and inspect accepted before performing the action. An accepted use can leave the balance at zero.

Usage receipts

NuxieFeatureCommand requires operation_id; quantity defaults to 1, and entity_id is optional. Both quantity and a query’s required balance must be positive integers up to 9,007,199,254,740,991.

A successful NuxieUsageResult.value is a NuxieUsageReceipt with customer_id, feature_id, operation_id, quantity, nullable occurred_at_ms, accepted, code, nullable balance, unlimited, active, and idempotent_replay. A replay returns the earlier operation’s result without another deduction.

Spend shared credits by passing the credit feature’s key and the cost in credits. The game must also apply each accepted action once, even if it receives the receipt again.

Checkout integration

For existing billing, configure NuxieBilling.external(controller) with a NuxiePurchaseController. Implement purchase(product) and restore(). Each method can return immediately or await your provider.

Return an outcome for every request. External billing leaves transaction finishing and acknowledgement to your provider. Restores requested from an Experience reach restore().

NuxieStoreProduct identifies the exact product and offer selected in the Experience:

Platform-specific values may be absent. Preserve the supplied selection when calling your provider rather than choosing another offer by price.

Receive updates

Connect features_changed to update access UI and activity_received for analytics. Use app_action_received when an Experience needs your game to do something, such as open the shop: match the action’s name to a handler and read its payload for supplied values. Connect before reading the current state and disconnect on scene exit.

The autoload persists across scenes. Your game controls pause, audio, and input while a native Experience appears.

Callbacks run on the Godot thread, including while the SceneTree is paused. OS suspension can delay callbacks until the app resumes.

Results, errors, and shutdown

Every awaited result has ok and error. Check ok before reading value from NuxieIdentityResult, NuxieFeatureResult, or NuxieUsageResult. NuxieResult acknowledges operations with no returned value.

NuxieError contains code, message, and details. Handle codes such as invalidArgument, notConfigured, alreadyConfigured, lifecycleBusy, identityChanged, sdkShutdown, operationTimeout, invalidResponse, incompatibleBridge, and unsupportedPlatform; do not branch on message text.

Await shutdown() to end the session, settle pending calls, and clear access state. A timeout or shutdown stops waiting for a request but does not undo a completed consumption. Retry with the saved operation ID. Await identity changes before issuing requests for the next player.

See Features and entitlements for access configuration and the GDScript API reference for complete result types and signals.