Skip to content

Latest commit

 

History

History
165 lines (107 loc) · 8.43 KB

README.md

File metadata and controls

165 lines (107 loc) · 8.43 KB
Raw

ruffle-web

Test Web

ruffle-web is a Wasm version of Ruffle, intended for use by either using the ruffle-selfhosted or ruffle-extension NPM packages.

This project is split into two parts: The actual Flash player written in Rust, and a javascript interface to it. Most of the time, you will be building the actual rust part through the npm build scripts.

Using ruffle-web

Please refer to our wiki for instructions on how to use Ruffle either on your own website, or as a browser extension.

How it works

We compile Ruffle down to a Wasm (WebAssembly) binary, which will be loaded into web pages either deliberately (installing the selfhosted package onto the website), or injected by users as a browser extension.

By default we will detect and replace any embedded Flash content on websites with the Ruffle player (we call this "polyfilling"), but this can be configured by the website. This means that Ruffle is an "out of the box" solution for getting Flash to work again; include Ruffle and it should just work™.

For rendering the content, we prefer to use WebGL. WebGL is very accurate, hardware-accelerated and very fast, but is not universally supported. Additionally, many privacy related browsers or extensions will disable WebGL by default. For this reason, we include a fallback using the canvas API.

Building from source

Requirements

Before you are able to build this project, you must first install a few dependencies:

Rust

Follow the instructions to install rust on your machine.

We do not have a Minimum Supported Rust Version policy. If it fails to build, it's likely you may need to update to the latest stable version of rust. You may run rustup update to do this (if you installed rust using the above instructions).

For the compiler to be able to output WebAssembly, an additional target has to be added to it: rustup target add wasm32-unknown-unknown

Java

Follow the instructions to install OpenJDK on your machine.

We do not have a specific Java support policy. Any Java version that supports running the AS3 compiler should work. Additionally, headless JREs should also work.

Node.js

Follow the instructions to install Node.js on your machine.

We recommend using the currently active LTS 20, but we do also run tests with current Node.js 22.

Note that npm 7 or newer is required. It should come bundled with Node.js 15 or newer, but can be upgraded with older Node.js versions using npm install -g npm as root/Administrator.

wasm-bindgen

This can be installed with cargo install wasm-bindgen-cli --version 0.2.93. Be sure to install this specific version of wasm-bindgen-cli to match the version used by Ruffle.

Binaryen

This is optional, used to further optimize the built WebAssembly module. Some ways to install Binaryen:

Just make sure the wasm-opt program is in $PATH, and that it works.

Optional features

jpegxr

The release version of the extension is compiled with jpegxr. To enable it, set the the env CARGO_FEATURES="jpegxr".

Windows dependencies:

  • Install LLVM and add the full path of its bin folder (example: C:\Program Files\LLVM-18.1.6\bin) to your env PATH.
  • Set env LIBCLANG_PATH with the same bin folder.

Building

In this project, you may run the following commands to build all packages:

  • npm install
    • This will install every dependency for every package.
    • Run this every time you pull in new changes, otherwise you may be missing a package and the build will fail.
  • npm run build
    • This will build the wasm binary and every node package (notably selfhosted and extension).
    • Output will be available in the dist/ folder of each package (for example, ./packages/selfhosted/dist).
    • You may also use npm run build:debug to disable Webpack optimizations and activate the (extremely verbose) ActionScript debugging output.
    • There is npm run build:dual-wasm as well, to build a second WebAssembly module that makes use of some WebAssembly extensions, potentially resulting in better performance in browsers that support them, at the expense of longer build time.
    • npm run build:repro enables reproducible builds. Note that this also requires a version_seal.json, which is not provided in the normal Git repository - only specially-marked reproducible source archives. Running this without a version seal will generate one based on the current state of your environment.

From here, you may follow the instructions to use Ruffle on your website, run a demo locally with npm run demo, or install the extension in your browser.

Testing

There are two parts of tests to this project:

  • Regular node tests, ran through npm run test. You must have built everything first as above. These have no special requirements.
  • Browser based tests, ran through npm run wdio with extra arguments as below. These take longer to run and require some setup.

Browser Based Tests

There are full integration tests that require a browser to run. We don't make any assumptions about your environment, and so you must specify it yourself.

To run these tests, first build the project as above, then use npm run wdio -- --arg1 --arg2 etc.

Local Browsers

These are additive - you can specify multiple at the same time. You must have the given browsers installed locally though, or it will fail.

  • --chrome for Chrome
  • --firefox for Firefox
  • --edge for Edge

BrowserStack (Mobile Browsers)

To run tests on mobile devices on BrowserStack, pass the --browserstack argument. We also have our "minimum supported desktop browsers" available too, by additionally passing --oldVersions.

You will need a BrowserStack account (Maintainers may contact @Dinnerbone on Discord for an invite to the Ruffle team), and set the appropriate values to BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY environment variables.

Other Options

Pass --headless to hide the browser windows. This is useful and recommended in almost every case, but if you want to debug why a test fails then it's very useful to not pass this.

Pass --spec <name> to filter a test based on name. For example, --spec external_interface to tests with external_interface in the path.

Testing tips!

If debugging a failing test, use await browser.pause(100000); in the test file to pause it, and don't start the test with --headless. That way you can actually see what's happening, and manually get involved to debug it.

Structure

  • This directory is a cargo crate which is the actual Flash player, and also a root node package.
  • packages/core is a node package which contains the core ruffle web API & wasm bindings.
  • packages/selfhosted is a node package intended for consumption by websites to include Ruffle on their site.
  • packages/extension is a node package that turns Ruffle into a browser extension.
  • packages/demo is an example node package of how to use self-hosted ruffle on your site, and testing it locally.

Contributing

Please follow the general contribution guidelines for Ruffle.

In addition to those, we ask that you ensure that you pass all tests with npm run test, and check the automatic code linting & styler by running npm run format before you commit.

Where possible, please add tests to all new functionality or bug fixes that you contribute.

Thank you!