---
title: "Godot SDK reference"
description: "GDScript methods, typed results, feature snapshots, and scene-safe subscriptions."
sidebar:
  label: "Godot"
search:
  tags: ["sdk", "reference", "godot"]
  keywords: ["GDScript", "Godot", "configure", "identify", "consumeFeature", "App Action"]
---

The `Nuxie` autoload provides the GDScript interface for identity, Experiences, and access. [Install and configure the addon](/docs/sdks/godot), then call its methods on the Godot thread.

<span id="interfaces-and-contracts" />

## Configuration

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

| Property | Default | Description |
| --- | --- | --- |
| `ios_api_key`, `android_api_key` | Running platform's key required | Publishable app keys. |
| `environment` | `PRODUCTION` | `PRODUCTION` or `DEVELOPMENT`. |
| `log_level` | `WARNING` | `WARNING`, `DEBUG`, `INFO`, `ERROR`, `NONE`, or `VERBOSE`. |
| `locale` | Empty | Empty follows the device locale. |
| `billing` | Native | `NuxieBilling.external(controller)` selects your checkout integration. |

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

```gdscript
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

```gdscript
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

```gdscript
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

```gdscript
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.

| Operation | Result |
| --- | --- |
| Purchase | `NuxiePurchaseResult.purchased()`, `cancelled()`, `pending()`, or `failed(message)` |
| Restore | `NuxieRestoreResult.restored()`, `no_purchases()`, or `failed(message)` |

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:

| Fields | Description |
| --- | --- |
| `platform`, `product_id`, `store_product_id`, `placement_id` | Platform and product identifiers. |
| `display_name`, `description`, `display_price`, `product_type` | Customer-facing product information. |
| `period`, `period_count`, `billing_plan` | iOS subscription terms, where applicable. |
| `eligibility_jws`, `introductory_terms` | iOS introductory offer information. |
| `base_plan_id`, `purchase_option_id`, `offer_id`, `pricing_phases` | Selected Google Play product and offer information. |

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.

| Signal | Payload |
| --- | --- |
| `status_changed` | `NuxieStatus` |
| `identity_changed` | `NuxieIdentity` |
| `features_changed` | `NuxieFeatureSnapshot` |
| `activity_received` | `NuxieActivity`, with ID, name, timestamps, and properties |
| `app_action_received` | `NuxieAppAction`, with name, payload, and Experience context |
| `error_received` | `NuxieError` for errors outside an awaited operation |

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.

<span id="shared-platform-behavior" />

See [Features and entitlements](/docs/monetization/features-and-entitlements) for access configuration and the [GDScript API reference](https://github.com/nuxieai/nuxie-godot/blob/main/docs/api-reference.md) for complete result types and signals.