frontend-utils: Update bundle specification

Co-authored-by: Nathan Adams <dinnerbone@dinnerbone.com>

frontend-utils/src/bundle/README.md

@@ -12,6 +12,23 @@ A bundle can be a directory or a renamed zip file, and must contain at minimum a
     * [`[bundle]`](#bundle)
       * [`name` - The name of the bundle](#name---the-name-of-the-bundle)
       * [`url` - The url of the Flash content to open](#url---the-url-of-the-flash-content-to-open)
+    * [`[player]`](#player)
+      * [`[parameters]` - A list of parameters to pass to the starting movie](#parameters---a-list-of-parameters-to-pass-to-the-starting-movie)
+      * [`script_timeout` - Script execution timeout](#script_timeout---script-execution-timeout)
+      * [`base_url` - Base URL for relative file paths](#base_url---base-url-for-relative-file-paths)
+      * [`quality` - Quality that the content starts with](#quality---quality-that-the-content-starts-with)
+      * [`align` - Stage Alignment that the content starts with](#align---stage-alignment-that-the-content-starts-with)
+      * [`force_align` - Allow or disallow the content from changing its Stage Alignment](#force_align---allow-or-disallow-the-content-from-changing-its-stage-alignment)
+      * [`scale_mode` - Stage Scale Mode that the content starts with](#scale_mode---stage-scale-mode-that-the-content-starts-with)
+      * [`force_scale_mode` - Allow or disallow the content from changing its Stage Alignment](#force_scale_mode---allow-or-disallow-the-content-from-changing-its-stage-alignment)
+      * [`upgrade_http_to_https` - Whether to upgrade HTTP urls to HTTPS silently](#upgrade_http_to_https---whether-to-upgrade-http-urls-to-https-silently)
+      * [`load_behavior` - How Ruffle should load movies](#load_behavior---how-ruffle-should-load-movies)
+      * [`letterbox` - Controls visual letterboxing around the content](#letterbox---controls-visual-letterboxing-around-the-content)
+      * [`spoof_url` - URL to pretend the initial SWF is being loaded from](#spoof_url---url-to-pretend-the-initial-swf-is-being-loaded-from)
+      * [`version` - Version of the Flash Player to emulate](#version---version-of-the-flash-player-to-emulate)
+      * [`runtime` - Which type of runtime to emulate](#runtime---which-type-of-runtime-to-emulate)
+      * [`frame_rate` - Override the target frame rate of this movie](#frame_rate---override-the-target-frame-rate-of-this-movie)
+      * [`mock_external_interface` - Provide a mocked ExternalInterface](#mock_external_interface---provide-a-mocked-externalinterface)
 <!-- TOC -->
 
 ## Directory structure
@@ -62,3 +79,155 @@ This way, an internet connection is not required, and the bundle won't stop work
 
 Remember - the `content/` directory is accessible through `file:///` - so if you have a game at `content/game.swf`, you'll want to use `url = "file:///game.swf"`.
 
+
+### `[player]`
+This section contains player options, which change how Ruffle emulates the content in this bundle.
+
+These options may be overridden by users.
+
+#### `[parameters]` - A list of parameters to pass to the starting movie
+These are sometimes also called 'FlashVars' by Flash developers. This is appended to any parameters given in the query string of the `bundle.url`.
+
+All values must be strings.
+
+Example:
+```toml
+[player.parameters]
+key = "value"
+favourite_number = "5"
+```
+
+#### `script_timeout` - Script execution timeout
+How long a single script execution (e.g. a frame of ActionScript 3) can take, before it's considered to be stuck or broken.
+Value should be in seconds - fractional values are allowed.
+
+Example with a 5-second limit on scripts:
+```toml
+[player]
+script_timeout = 5
+```
+
+#### `base_url` - Base URL for relative file paths
+By default, this is the `bundle.url`, but some content may require something else.
+
+When content looks up a **relative** path, as opposed to an absolute path, it makes it relative to this base url instead.
+
+Example:
+```toml
+[player]
+base_url = "https://example.org"
+```
+
+#### `quality` - Quality that the content starts with
+The movie has the capacity to change this automatically at runtime, and the user may also change it at will.
+The default value generally depends on the users hardware, and it's advisable to leave it to do so unless content requires
+a specific quality for aesthetics.
+
+Whilst Flash [does technically support many quality modes](https://web.archive.org/web/20240420201659/https://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/display/StageQuality.html);
+Ruffle currently only implements `low`, `medium` and `high`.
+
+Example:
+```toml
+[player]
+quality = "low"
+```
+
+#### `align` - Stage Alignment that the content starts with
+The movie has the capacity to change this automatically at runtime, unless `player.force_align` is set to `true`.
+
+This controls the position of the movie after scaling to fill the viewport.
+
+This may be one of the following values:
+- `bottom`: Specifies that the Stage is aligned at the bottom.
+- `bottom_left`: Specifies that the Stage is aligned in the bottom-left corner.
+- `bottom_right`: Specifies that the Stage is aligned in the bottom-right corner.
+- `left`: Specifies that the Stage is aligned on the left.
+- `right`: Specifies that the Stage is aligned to the right.
+- `top`: Specifies that the Stage is aligned at the top.
+- `top_left`: Specifies that the Stage is aligned in the top-left corner.
+- `top_right`: Specifies that the Stage is aligned in the top-right corner.
+- `center` (Default): Specified that the Stage is aligned in the center.
+
+Example:
+```toml
+[player]
+align = "bottom_right"
+```
+
+#### `force_align` - Allow or disallow the content from changing its Stage Alignment
+If set to `true`, content may not change its own Stage Alignment value (see `player.align`). Default is `false`.
+
+#### `scale_mode` - Stage Scale Mode that the content starts with
+The movie has the capacity to change this automatically at runtime, unless `player.force_scale_mode` is set to `true`.
+
+This controls the behavior when the player viewport size differs from the SWF size.
+
+This may be one of the following values:
+- `exact_fit`: The movie will be stretched to fit the container.
+- `no_border`: The movie will maintain its aspect ratio, but will be cropped.
+- `no_scale`: The movie is not scaled to fit the container, and the content is assumed to adjust itself with scripts.
+- `show_all` (Default): The movie will scale to fill the container and maintain its aspect ratio, but will be letterboxed.
+
+Example:
+```toml
+[player]
+scale_mode = "no_border"
+```
+
+#### `force_scale_mode` - Allow or disallow the content from changing its Stage Alignment
+If set to `true`, content may not change its own Stage Scale Mode value (see `player.scale_mode`). Default is `false`.
+
+#### `upgrade_http_to_https` - Whether to upgrade HTTP urls to HTTPS silently
+If `true`, all `http://` URLs will be replaced with `https://`.
+
+#### `load_behavior` - How Ruffle should load movies
+Some movies expect to be streamed, or expect to load instantly. This allows you to work around any potential issues by
+forcing a specific loading behaviour.
+
+This may be one of the following values:
+- `streaming` (Default): Allow movies to execute before they have finished loading.
+- `delayed`: Delay execution of loaded movies until they have finished loading.
+- `blocking`: Block Ruffle until movies have finished loading.
+
+#### `letterbox` - Controls visual letterboxing around the content
+If the contents aspect ratio does not match the players aspect ratio, Ruffle may put up letterboxes for aesthetics and
+to hide objects that perhaps should not be visible.
+
+This may be one of the following values:
+- `off`: The content will not be letterboxed, everything will be visible.
+- `fullscreen`: The content will only be letterboxed if viewed in Full Screen and the aspect ratio doesn't match.
+- `on` (Default): The content will always be letterboxed if the aspect ratio doesn't match.
+
+#### `spoof_url` - URL to pretend the initial SWF is being loaded from
+If set to a valid URL, we will **pretend** that the `bundle.url` SWF is actually being loaded from this location instead.
+This is often required for site locks that check if the content is being loaded from the original domain.
+
+We do not *actually* load the URL, and all other assets/SWFs are not affected.
+
+#### `version` - Version of the Flash Player to emulate
+Whilst it's not common, some content depends on behaviour from specific Flash Players. You may set this to force Ruffle
+to try and emulate that behaviour.
+
+Default is likely to be `32`, but may be subject to change.
+
+#### `runtime` - Which type of runtime to emulate
+Unfortunately content does not indicate which runtime it wants, so if there's AIR content it must be called out by setting
+this value appropriately.
+
+This may be one of the following values:
+- `flash_player` (Default): The original Flash Player, no thrills.
+- `air`: The Adobe AIR runtime, an extension of Flash Player with more native capabilities.
+
+#### `frame_rate` - Override the target frame rate of this movie
+If set, the movies preferred frame rate is ignored and this value is used instead.
+May be used to speed up or slow down movies, but some content keeps its own time tracking and may not be affected. Value can both be an integer and a fractional value.
+
+Example:
+```toml
+[player]
+frame_rate = 30.0
+```
+
+#### `mock_external_interface` - Provide a mocked ExternalInterface
+Some content used JavaScript calls to query things like the page URL. By setting this value to `true`, Ruffle will provide
+a mocked up ExternalInterface that responds to some of the common JavaScript calls appropriately.