Interface URLLoadOptions

Options to load a movie by URL.

interface URLLoadOptions {
    url: string;
    allowScriptAccess?: boolean;
    parameters?: null | string | URLSearchParams | Record<string, string>;
    autoplay?: AutoPlay;
    backgroundColor?: null | string;
    letterbox?: Letterbox;
    unmuteOverlay?: UnmuteOverlay;
    upgradeToHttps?: boolean;
    compatibilityRules?: boolean;
    favorFlash?: boolean;
    warnOnUnsupportedContent?: boolean;
    logLevel?: LogLevel;
    showSwfDownload?: boolean;
    contextMenu?: boolean | ContextMenu;
    preloader?: boolean;
    splashScreen?: boolean;
    maxExecutionDuration?: Duration;
    base?: null | string;
    menu?: boolean;
    salign?: string;
    forceAlign?: boolean;
    quality?: string;
    scale?: string;
    forceScale?: boolean;
    allowFullscreen?: boolean;
    frameRate?: null | number;
    wmode?: WindowMode;
    playerVersion?: null | number;
    preferredRenderer?: null | RenderBackend;
    publicPath?: null | string;
    polyfills?: boolean;
    openUrlMode?: OpenURLMode;
    allowNetworking?: NetworkingAccessMode;
    openInNewTab?: null | (swf: URL) => void;
    socketProxy?: SocketProxy[];
    fontSources?: string[];
    defaultFonts?: DefaultFonts;
    credentialAllowList?: string[];
    playerRuntime?: PlayerRuntime;
}

Hierarchy (View Summary)

Properties

url: string

The URL to load a movie from.

If there is a query portion of this URL, then default parameters will be extracted from that.

allowScriptAccess?: boolean

If set to true, the movie is allowed to interact with the page through JavaScript, using a flash concept called ExternalInterface.

This should only be enabled for movies you trust.

false
parameters?: null | string | URLSearchParams | Record<string, string>

Also known as "flashvars" - these are values that may be passed to and loaded by the movie.

If a URL if specified when loading the movie, some parameters will be extracted by the query portion of that URL and then overwritten by any explicitly set here.

{}
autoplay?: AutoPlay

Controls the auto-play behaviour of Ruffle.

AutoPlay.Auto
backgroundColor?: null | string

Controls the background color of the player. Must be an HTML color (e.g. "#FFFFFF"). CSS colors are not allowed. null uses the background color of the SWF file.

null
letterbox?: Letterbox

Controls letterbox behavior when the Flash container size does not match the movie size.

Letterbox.Fullscreen
unmuteOverlay?: UnmuteOverlay

Controls the visibility of the unmute overlay when the player is started muted.

UnmuteOverlay.Visible
upgradeToHttps?: boolean

Whether or not to auto-upgrade all embedded URLs to https.

Flash content that embeds http urls will be blocked from accessing those urls by the browser when Ruffle is loaded in a https context. Set to true to automatically change http:// to https:// for all embedded URLs when Ruffle is loaded in an https context.

true
compatibilityRules?: boolean

Enable (true) or disable (false) Ruffle's built in compatibility rules.

These are rules that may make some content work by deliberately changing behaviour, for example by rewriting requests or spoofing SWF urls if they rely on websites that no longer exist.

true
favorFlash?: boolean

Favor using the real Adobe Flash Player over Ruffle if the browser supports it.

true
warnOnUnsupportedContent?: boolean

This is no longer used and does not affect anything. It is only kept for backwards compatibility.

Previously: "Whether or not to display an overlay with a warning when loading a movie with unsupported content."

true
logLevel?: LogLevel

Console logging level.

LogLevel.Error
showSwfDownload?: boolean

If set to true, the context menu has an option to download the SWF.

false
contextMenu?: boolean | ContextMenu

Whether or not to show a context menu when right-clicking a Ruffle instance.

ContextMenu.On
preloader?: boolean

Whether or not to show a splash screen before the SWF has loaded with Ruffle (backwards-compatibility).

true
splashScreen?: boolean

Whether or not to show a splash screen before the SWF has loaded with Ruffle.

true
maxExecutionDuration?: Duration

Maximum amount of time a script can take before scripting is disabled.

15
base?: null | string

Specifies the base directory or URL used to resolve all relative path statements in the SWF file. null means the current directory.

null
menu?: boolean

If set to true, the built-in context menu items are visible

This is equivalent to Stage.showMenu.

true
salign?: string

This is equivalent to Stage.align.

""
forceAlign?: boolean

If set to true, movies are prevented from changing the stage alignment.

false
quality?: string

This is equivalent to Stage.quality.

"high"
scale?: string

This is equivalent to Stage.scaleMode.

"showAll"
forceScale?: boolean

If set to true, movies are prevented from changing the stage scale mode.

false
allowFullscreen?: boolean

If set to true, the Stage's displayState can be changed

false
frameRate?: null | number

Sets and locks the player's frame rate, overriding the movie's frame rate.

null
wmode?: WindowMode

The window mode of the Ruffle player.

This setting controls how the Ruffle container is layered and rendered with other content on the page.

WindowMode.Window
playerVersion?: null | number

The emulated version of the player.

This controls the version that is reported to the movie. null means latest version.

null
preferredRenderer?: null | RenderBackend

The preferred render backend of the Ruffle player.

This option should only be used for testing; the available backends may change in future releases. By default, Ruffle chooses the most featureful backend supported by the user's system, falling back to more basic backends if necessary. The available values in order of default preference are: "webgpu", "wgpu-webgl", "webgl", "canvas".

null
publicPath?: null | string

The URL at which Ruffle can load its extra files (i.e. .wasm).

null
polyfills?: boolean

Whether or not to enable polyfills on the page.

Polyfills will look for "legacy" flash content like <object> and <embed> elements, and replace them with compatible Ruffle elements.

true
openUrlMode?: OpenURLMode

The handling mode of links opening a new website.

OpenURLMode.Allow
allowNetworking?: NetworkingAccessMode

Which flash networking APIs may be accessed.

NetworkingAccessMode.All
openInNewTab?: null | (swf: URL) => void

A function to call for opening content in a new tab.

This is only used if the content cannot be loaded due to CORS, and the Extension version of Ruffle will override this to provide a local player.

null
socketProxy?: SocketProxy[]

An array of SocketProxy objects.

When a SWF tries to establish a Socket connection, Ruffle will search for a matching SocketProxy object in this array and use it to establish a WebSocket connection, through which all communication is tunneled through.

When none are found, Ruffle will fail the connection gracefully. When multiple matching SocketProxy objects exist, the first one is used.

[]
fontSources?: string[]

An array of font URLs to eagerly load and provide to Ruffle.

These will be fetched by the browser as part of the loading of Flash content, which may slow down load times.

Currently only SWFs are supported, and each font embedded within that SWF will be used as device font by Flash content.

If any URL fails to load (either it's an invalid file, or a network error occurs), Ruffle will log an error but continue without it.

[]
defaultFonts?: DefaultFonts

The font names to use for each "default" Flash device font.

{}
credentialAllowList?: string[]

An array of origins that credentials may be sent to. Credentials are cookies, authorization headers, or TLS client certificates.

Entries should include the protocol and host, for example https://example.org or http://subdomain.example.org.

Cookies will always be sent to the same origin as the page the content was loaded on. If you configure this to send cookies to an origin but that origin does not configure CORS to allow it, then requests will start failing due to CORS. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials.

This directly corresponds to https://developer.mozilla.org/en-US/docs/Web/API/fetch#credentials Every request will be same-origin unless specified here, in which case it will be include.

[]
playerRuntime?: PlayerRuntime

The player runtime to emulate

This allows you to emulate Adobe AIR or Adobe Flash Player.