Skip to Content
defold-typescript libraries
defold (official)

defold/extension-playables/playables

Functions for interacting with the YouTube Playables SDK.

  • GitHub: defold/extension-playables — pinned to b1122a7
    1. This repo publishes no releases or tags. Add a commit archive URL — for the pinned commit, https://github.com/defold/extension-playables/archive/b1122a7a81dd23a573856a263003c3dcebf2cbb5.zip — to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as playables from "playables"

Functions

playables.is_in_playables_env(): boolean

Returns whether the SDK reports that the game is running in the Playables environment. Returns false if the SDK is not loaded.

Returns

  • in_playables_env: boolean — True when the SDK is loaded and IN_PLAYABLES_ENV is true, otherwise false.

playables.get_sdk_version(): string | nil

Returns the loaded YouTube Playables SDK version, or nil if it is unavailable.

Returns

  • sdk_version: string | nil — The value of SDK_VERSION, or nil if the SDK or its version is unavailable.

playables.game_ready()

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(callback: 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(data: string, callback: 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(): boolean

Returns whether game audio is enabled in the player's YouTube settings. Use this to initialize the game audio state.

Returns

  • is_audio_enabled: boolean — True when game audio is enabled.

playables.on_audio_enabled_change(callback: function | nil)

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(callback: function | nil)

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(callback: function | nil)

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(callback: 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(score: number, callback: 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(content_id: string, content_type: number | undefined, callback: 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 | undefined — 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(callback: 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(reward_id: string, callback: 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()

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()

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.

Constants

playables.CONTENT_TYPE_VIDEO

Opens a YouTube video.

playables.CONTENT_TYPE_PLAYABLE

Opens another YouTube Playable.

On this page