Interface PlayerElement

A Ruffle player's HTML element.

This is either created through window.RufflePlayer.newest().createPlayer(), or polyfilled from a <embed>/<object> tag.

In addition to usual HTML attributes, this player contains methods and properties that belong to both the Flash JS API and legacy Ruffle APIs. You are strongly discouraged from using them, and should instead use .ruffle(version) to access a versioned API interface.

interface PlayerElement {
    ruffle<V extends 1 = 1>(version?: V): APIVersions[V];
    onFSCommand: null | (command: string, args: string) => void;
    config: object | URLLoadOptions | DataLoadOptions;
    loadedConfig: null | URLLoadOptions | DataLoadOptions;
    get readyState(): ReadyState;
    get metadata(): null | MovieMetadata;
    reload(): Promise<void>;
    load(options: string | URLLoadOptions | DataLoadOptions): Promise<void>;
    play(): void;
    get isPlaying(): boolean;
    get volume(): number;
    set volume(value: number): void;
    get fullscreenEnabled(): boolean;
    get isFullscreen(): boolean;
    setFullscreen(isFull: boolean): void;
    enterFullscreen(): void;
    exitFullscreen(): void;
    pause(): void;
    set traceObserver(observer: null | (message: string) => void): void;
    downloadSwf(): Promise<void>;
    displayMessage(message: string): void;
    PercentLoaded(): number;
}

Hierarchy (View Summary)

Properties

onFSCommand config loadedConfig

Accessors

readyState metadata isPlaying volume fullscreenEnabled isFullscreen traceObserver

Methods

ruffle reload load play setFullscreen enterFullscreen exitFullscreen pause downloadSwf displayMessage PercentLoaded

Properties

onFSCommand

onFSCommand: null | (command: string, args: string) => void

Adds a handler for arbitrary "fs commands" from a movie in this player.

Type declaration

  • null
  • (command: string, args: string) => void
      • (command: string, args: string): void

      • Parameters

        • command: string

          An arbitrary name of a command.

        • args: string

          An arbitrary argument to the command.

        Returns void

Remarks

If script access is allowed, a movie may communicate to the page through the ActionScript method fscommand(name, args).

The exact commands and their arguments are more or less arbitrary and up to the movie. This is an incredibly deprecated way of communicating between Flash and JavaScript, and was deprecated in favor of ExternalInterface in Flash Player 8 (2005).

Deprecated

Please use ruffle() to access a versioned API. This method may be replaced by Flash and is not guaranteed to exist. A direct replacement is PlayerV1.addFSCommandHandler, which supports multiple handlers.

config

config: object | URLLoadOptions | DataLoadOptions

Any configuration that should apply to this specific player. This will be defaulted with any global configuration.

Deprecated

Please use ruffle() to access a versioned API. This method may be replaced by Flash and is not guaranteed to exist. A direct replacement is PlayerV1.config

ReadonlyloadedConfig

loadedConfig: null | URLLoadOptions | DataLoadOptions

The effective config loaded with the last call to load(). If no such call has been made, this will be null.

Deprecated

Please use ruffle() to access a versioned API. This method may be replaced by Flash and is not guaranteed to exist. A direct replacement is PlayerV1.loadedConfig

Accessors

readyState

  • get readyState(): ReadyState

  • Indicates the readiness of the playing movie.

    Returns ReadyState

    The ReadyState of the player.

    Deprecated

    Please use ruffle() to access a versioned API. This method may be replaced by Flash and is not guaranteed to exist. A direct replacement is PlayerV1.readyState

metadata

  • get metadata(): null | MovieMetadata

  • The metadata of the playing movie (such as movie width and height). These are inherent properties stored in the SWF file and are not affected by runtime changes. For example, metadata.width is the width of the SWF file, and not the width of the Ruffle player.

    Returns null | MovieMetadata

    The metadata of the movie, or null if the movie metadata has not yet loaded.

    Deprecated

    Please use ruffle() to access a versioned API. This method may be replaced by Flash and is not guaranteed to exist. A direct replacement is PlayerV1.metadata

isPlaying

  • get isPlaying(): boolean

  • Checks if this player is not suspended.

    A suspended movie will not execute any frames, scripts or sounds. This movie is considered inactive and will not wake up until resumed. If no movie is loaded, this method will return true.

    Returns boolean

    True if this player is playing, false if it's paused or hasn't started yet.

    Remarks

    This method was confusingly named and kept for legacy compatibility. "Playing" in this context referred to "not being suspended", and not the Flash concept of playing/paused.

    Deprecated

    Please use ruffle() to access a versioned API. This method may be replaced by Flash and is not guaranteed to exist. A direct replacement is PlayerV1.suspended (though inversed!)

volume

  • get volume(): number

  • Returns the master volume of the player.

    The volume is linear and not adapted for logarithmic hearing.

    Returns number

    The volume. 1.0 is 100% volume.

    Deprecated

    Please use ruffle() to access a versioned API. This method may be replaced by Flash and is not guaranteed to exist. A direct replacement is PlayerV1.volume

  • set volume(value: number): void

  • Sets the master volume of the player.

    The volume should be linear and not adapted for logarithmic hearing.

    Parameters

    • value: number

      The volume. 1.0 is 100% volume.

    Returns void

    Deprecated

    Please use ruffle() to access a versioned API. This method may be replaced by Flash and is not guaranteed to exist. A direct replacement is PlayerV1.volume

fullscreenEnabled

  • get fullscreenEnabled(): boolean

  • Checks if this player is allowed to be fullscreen by the browser.

    Returns boolean

    True if you may call enterFullscreen.

    Deprecated

    Please use ruffle() to access a versioned API. This method may be replaced by Flash and is not guaranteed to exist. A direct replacement is PlayerV1.fullscreenEnabled

isFullscreen

  • get isFullscreen(): boolean

  • Checks if this player is currently fullscreen inside the browser.

    Returns boolean

    True if it is fullscreen.

    Deprecated

    Please use ruffle() to access a versioned API. This method may be replaced by Flash and is not guaranteed to exist. A direct replacement is PlayerV1.isFullscreen

traceObserver

  • set traceObserver(observer: null | (message: string) => void): void

  • Sets a trace observer on this flash player.

    The observer will be called, as a function, for each message that the playing movie will "trace" (output).

    Parameters

    • observer: null | (message: string) => void

      The observer that will be called for each trace.

    Returns void

    Deprecated

    Please use ruffle() to access a versioned API. This method may be replaced by Flash and is not guaranteed to exist. A direct replacement is PlayerV1.traceObserver

Methods

ruffle

  • ruffle<V extends 1 = 1>(version?: V): APIVersions[V]

  • Access a specific version of the Ruffle API. If the given version is not supported, an error is thrown.

    Type Parameters

    • V extends 1 = 1

    Parameters

    • Optionalversion: V

      Version of the API to access. Defaults to 1.

    Returns APIVersions[V]

reload

  • reload(): Promise<void>

  • Reloads the player, as if you called load with the same config as the last time it was called.

    If this player has never been loaded, this method will return an error.

    Returns Promise<void>

    Deprecated

    Please use ruffle() to access a versioned API. This method may be replaced by Flash and is not guaranteed to exist. A direct replacement is PlayerV1.reload

load

  • load(options: string | URLLoadOptions | DataLoadOptions): Promise<void>

  • Loads a specified movie into this player.

    This will replace any existing movie that may be playing.

    Parameters

    • options: string | URLLoadOptions | DataLoadOptions

      One of the following:

      • A URL, passed as a string, which will load a URL with default options.
      • A URLLoadOptions object, to load a URL with options.
      • A DataLoadOptions object, to load data with options. The options, if provided, must only contain values provided for this specific movie. They must not contain any default values, since those would overwrite other configuration settings with a lower priority (e.g. the general RufflePlayer config).

      The options will be defaulted by the config field, which itself is defaulted by a global window.RufflePlayer.config.

    Returns Promise<void>

    Deprecated

    Please use ruffle() to access a versioned API. This method may be replaced by Flash and is not guaranteed to exist. A direct replacement is PlayerV1.load

play

  • play(): void

  • Resumes the movie from suspension.

    The movie will now resume executing any frames, scripts and sounds. If the movie is not suspended or no movie is loaded, this method will do nothing.

    Returns void

    Remarks

    This method was confusingly named and kept for legacy compatibility. "Playing" in this context referred to "not being suspended", and not the Flash concept of playing/paused.

    Deprecated

    Please use ruffle() to access a versioned API. This method may be replaced by Flash and is not guaranteed to exist. A direct replacement is PlayerV1.resume

setFullscreen

enterFullscreen

exitFullscreen

pause

  • pause(): void

  • Suspends the movie.

    A suspended movie will not execute any frames, scripts or sounds. This movie is considered inactive and will not wake up until resumed. If the movie is already suspended or no movie is loaded, this method will do nothing.

    Returns void

    Remarks

    This method was confusingly named and kept for legacy compatibility. "Pause" in this context referred to "suspended", and not the Flash concept of playing/paused.

    Deprecated

    Please use ruffle() to access a versioned API. This method may be replaced by Flash and is not guaranteed to exist. A direct replacement is PlayerV1.suspend

downloadSwf

displayMessage

PercentLoaded

  • PercentLoaded(): number

  • Returns the movies loaded process, in a percent from 0 to 100. Ruffle may just return 0 or 100.

    Returns number

    a value from 0 to 100, inclusive.

Settings

Member Visibility

On This Page

Properties
Accessors
Methods