defold/extension-playables/playables
Functions for interacting with the YouTube Playables SDK.
- GitHub: defold/extension-playables — pinned to
b1122a7- 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— togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as playables from "playables"
- This repo publishes no releases or tags. Add a commit archive URL — for the pinned commit,
Functions
playables.is_in_playables_env(): booleanplayables.get_sdk_version(): string | nilplayables.game_ready()playables.load_data(callback: function)playables.save_data(data: string, callback: function)playables.is_audio_enabled(): booleanplayables.on_audio_enabled_change(callback: function | nil)playables.on_pause(callback: function | nil)playables.on_resume(callback: function | nil)playables.get_language(callback: function)playables.send_score(score: number, callback: function)playables.open_yt_content(content_id: string, content_type: number | undefined, callback: function)playables.request_interstitial_ad(callback: function)playables.request_rewarded_ad(reward_id: string, callback: function)playables.log_error()playables.log_warning()
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:functionself: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:functionself: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:functionself: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:functionself: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:functionself: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:functionself: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:functionself: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.