# extension-playables

**Namespace:** `playables`
**Language:** Lua
**Type:** Extension

Functions for interacting with the YouTube Playables SDK.

## API

### playables.is_in_playables_env
*Type:* FUNCTION
Returns whether the SDK reports that the game is running in the Playables environment. Returns false if the SDK is not loaded.

**Returns**

- `boolean` - True when the SDK is loaded and IN_PLAYABLES_ENV is true, otherwise false.

### playables.get_sdk_version
*Type:* FUNCTION
Returns the loaded YouTube Playables SDK version, or nil if it is unavailable.

**Returns**

- `['string', 'nil']` - The value of SDK_VERSION, or nil if the SDK or its version is unavailable.

### playables.game_ready
*Type:* FUNCTION
Notifies YouTube that the loading screen is gone and the game is ready for players to interact with. The extension automatically calls firstFrameReady() during initialization.

### playables.load_data
*Type:* FUNCTION
Loads serialized game data from YouTube. Only one load request may be in progress at a time. The request remains in progress until its callback returns, so the callback cannot start another load_data() request.

**Parameters**

- `callback` (function)
  - `self` (object) - The calling script instance.
  - `data` (string | nil) - The serialized game data on success, otherwise nil.
  - `error` (string | nil) - The SDK error message on failure, otherwise nil.

### playables.save_data
*Type:* FUNCTION
Saves valid UTF-8 text to YouTube, with a maximum size of 3 MiB. Invalid UTF-8 returns false and an error through the callback before the SDK is called. Base64-encode binary data such as sys.serialize() output before saving. Only one save request may be in progress at a time. The request remains in progress until its callback returns, so the callback cannot start another save_data() request.

**Parameters**

- `data` (string) - The serialized game data as valid UTF-8 text. Embedded zero bytes are supported.
- `callback` (function)
  - `self` (object) - The calling script instance.
  - `success` (boolean) - True when the save completed successfully.
  - `error` (string | nil) - The UTF-8 decoding or SDK error message on failure, otherwise nil.

### playables.is_audio_enabled
*Type:* FUNCTION
Returns whether game audio is enabled in the player's YouTube settings. Use this to initialize the game audio state.

**Returns**

- `boolean` - True when game audio is enabled.

### playables.on_audio_enabled_change
*Type:* FUNCTION
Registers a callback for YouTube audio-setting changes. Before the callback runs, the extension automatically mutes the master sound group when audio is disabled, or unmutes it when audio is enabled and the game is not paused. A new callback replaces the previous one. Pass nil to unregister it. This function cannot be called from its own callback.

**Parameters**

- `callback` (function | nil) - The event callback, or nil to unregister the current callback.
  - `self` (object) - The calling script instance.
  - `is_audio_enabled` (boolean) - True when game audio should be enabled.

### playables.on_pause
*Type:* FUNCTION
Registers a callback for YouTube pause events. The extension automatically mutes the master sound group before the callback runs. A new callback replaces the previous one. Pass nil to unregister it. This function cannot be called from its own callback. A paused game is not guaranteed to resume.

**Parameters**

- `callback` (function | nil) - The event callback, or nil to unregister the current callback.
  - `self` (object) - The calling script instance.

### playables.on_resume
*Type:* FUNCTION
Registers a callback for YouTube resume events. Before the callback runs, the extension automatically unmutes the master sound group if YouTube audio is enabled, or keeps it muted if audio is disabled. A new callback replaces the previous one. Pass nil to unregister it. This function cannot be called from its own callback.

**Parameters**

- `callback` (function | nil) - The event callback, or nil to unregister the current callback.
  - `self` (object) - The calling script instance.

### playables.get_language
*Type:* FUNCTION
Gets the language in the player's YouTube settings as a BCP-47 language tag. Only one request may be in progress at a time. The request remains in progress until its callback returns, so the callback cannot start another get_language() request.

**Parameters**

- `callback` (function)
  - `self` (object) - The calling script instance.
  - `language` (string | nil) - The BCP-47 language tag on success, otherwise nil.
  - `error` (string | nil) - The SDK error message on failure, otherwise nil.

### playables.send_score
*Type:* FUNCTION
Sends an integer score to YouTube. Use one consistent score dimension across the game. Only one request may be in progress at a time. The request remains in progress until its callback returns, so the callback cannot start another send_score() request.

**Parameters**

- `score` (number) - An integer no greater than JavaScript's maximum safe integer.
- `callback` (function)
  - `self` (object) - The calling script instance.
  - `success` (boolean) - True when the request succeeded.
  - `error` (string | nil) - The SDK error message on failure, otherwise nil.

### playables.open_yt_content
*Type:* FUNCTION
Requests that YouTube open a video or another Playable. The content type is optional and defaults to CONTENT_TYPE_VIDEO. Only one request may be in progress at a time. The request remains in progress until its callback returns, so the callback cannot start another open_yt_content() request.

**Parameters**

- `content_id` (string) - The YouTube video or Playable ID.
- `content_type` (number) - CONTENT_TYPE_VIDEO or CONTENT_TYPE_PLAYABLE.
- `callback` (function)
  - `self` (object) - The calling script instance.
  - `success` (boolean) - True when the request succeeded. This does not guarantee that the content opened.
  - `error` (string | nil) - The SDK error message on failure, otherwise nil.

### playables.request_interstitial_ad
*Type:* FUNCTION
Requests an interstitial ad. Success does not guarantee that an ad was shown. Do not use this API to grant rewards. Only one interstitial request may be in progress at a time. The request remains in progress until its callback returns, so the callback cannot start another request_interstitial_ad() request. Keep handling YouTube audio, pause, and resume events during ads.

**Parameters**

- `callback` (function)
  - `self` (object) - The calling script instance.
  - `success` (boolean) - True when the request succeeded. This does not guarantee that an ad was shown.
  - `error` (string | nil) - The SDK error message on failure, otherwise nil.

### playables.request_rewarded_ad
*Type:* FUNCTION
Requests a rewarded ad. Grant a reward only when reward_earned is true. Only one rewarded request may be in progress at a time. The request remains in progress until its callback returns, so the callback cannot start another request_rewarded_ad() request. Keep handling YouTube audio, pause, and resume events during ads.

**Parameters**

- `reward_id` (string) - A stable ID unique to the reward type. Reuse it for each offer of that reward and do not include user data.
- `callback` (function)
  - `self` (object) - The calling script instance.
  - `reward_earned` (boolean | nil) - True if a reward was earned, false if no reward was earned, or nil if the request failed.
  - `error` (string | nil) - The SDK error message on failure, otherwise nil.

### playables.log_error
*Type:* FUNCTION
Reports an error occurrence to YouTube. Takes no arguments and returns no value. Reporting is best-effort and rate-limited, so delivery is not guaranteed.

### playables.log_warning
*Type:* FUNCTION
Reports a warning occurrence to YouTube. Takes no arguments and returns no value. Reporting is best-effort and rate-limited, so delivery is not guaranteed.

### CONTENT_TYPE_VIDEO
*Type:* VARIABLE
Opens a YouTube video.

### CONTENT_TYPE_PLAYABLE
*Type:* VARIABLE
Opens another YouTube Playable.