chore: Document web with readmes
This commit is contained in:
Nathan Adams
Mike Welsh
parent
df6764a69c
commit
75759d9b3b
30
README.md
30
README.md
|
|
@ -32,29 +32,9 @@ Ruffle is in the proof-of-concept stage and can currently run early Flash animat
|
|||
|
||||
* `cargo run --package=ruffle_desktop -- test.swf`
|
||||
|
||||
### Web
|
||||
|
||||
* Install [Node.js](https://nodejs.org/en/)
|
||||
* Install [wasm-pack](https://rustwasm.github.io/wasm-pack/installer/)
|
||||
|
||||
#### Running the web demo
|
||||
|
||||
* `cd web/demo`
|
||||
* `npm run bootstrap`
|
||||
* `npm run demo`
|
||||
* Load indicated page in browser (usually http://localhost:8080)
|
||||
|
||||
#### Hosting on your own site
|
||||
|
||||
* `cd web/selfhosted`
|
||||
* `npm run bootstrap`
|
||||
* `npm run build`
|
||||
* Follow the wiki instructions for [using Ruffle on your own site](https://github.com/ruffle-rs/ruffle/wiki/Using-Ruffle#web)
|
||||
|
||||
#### Browser extension
|
||||
|
||||
* Follow the wiki instructions for [building the Ruffle browser extension](https://github.com/ruffle-rs/ruffle/wiki/Building-Ruffle#building-the-web-extension)
|
||||
* Follow the wiki instructions for [using the Ruffle browser extension](https://github.com/ruffle-rs/ruffle/wiki/Using-Ruffle#browser-extension)
|
||||
### Web or Extension
|
||||
Follow [the instructions in the web directory](web/README.md#building-from-source) for building
|
||||
either the web or browser extension version of Ruffle.
|
||||
|
||||
### Scanner
|
||||
|
||||
|
|
@ -76,7 +56,7 @@ This currently requires hardware acceleration, but can be run headless (with no
|
|||
|
||||
- `core` contains the core emulator and common code
|
||||
- `desktop` contains the desktop client (uses `wgpu-rs`)
|
||||
- `web` contains the web client (uses `wasm-bindgen`)
|
||||
- [`web`](web) contains the web client and browser extension (uses `wasm-bindgen`)
|
||||
- `scanner` contains a utility to bulk parse swf files
|
||||
- `exporter` contains a utility to generate PNG screenshots of a swf file
|
||||
|
||||
|
|
@ -99,7 +79,7 @@ Sincere thanks to the diamond level sponsors of Ruffle:
|
|||
<a href="https://www.crazygames.com">
|
||||
<img src="assets/crazygames_logo.png" alt="Crazy Games">
|
||||
</a>
|
||||
</a>
|
||||
</p>
|
||||
|
||||
## License
|
||||
|
||||
|
|
|
|||
|
|
@ -3,6 +3,12 @@ name = "ruffle_web"
|
|||
version = "0.1.0"
|
||||
authors = ["Mike Welsh <mwelsh@gmail.com>"]
|
||||
edition = "2018"
|
||||
license = "MIT OR Apache-2.0"
|
||||
description = "Web (WASM) bindings to the Ruffle flash player"
|
||||
readme = "README.md"
|
||||
homepage = "https://ruffle.rs"
|
||||
repository = "https://github.com/ruffle-rs/ruffle/"
|
||||
publish = false # This crate is useless alone, people should use the npm package
|
||||
|
||||
[lib]
|
||||
crate-type = ["cdylib", "rlib"]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,95 @@
|
|||
# ruffle-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](https://github.com/ruffle-rs/ruffle/wiki/Using-Ruffle#web),
|
||||
or as a [browser extension](https://github.com/ruffle-rs/ruffle/wiki/Using-Ruffle#browser-extension).
|
||||
|
||||
## How it works
|
||||
|
||||
We compile Ruffle down to a Wasm ([WebAssembly](https://webassembly.org/)) 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](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API).
|
||||
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](https://developer.mozilla.org/en-US/docs/Web/API/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](https://www.rust-lang.org/tools/install) 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).
|
||||
|
||||
#### Node.js
|
||||
|
||||
Follow the instructions [to install node.js](https://nodejs.org/en/) on your machine.
|
||||
|
||||
We recommend using the currently active LTS 12, but we do also run tests with maintenance LTS 10.
|
||||
|
||||
#### wasm-pack
|
||||
|
||||
Follow the instructions [to install wasm-pack](https://rustwasm.github.io/wasm-pack/installer/) on your machine.
|
||||
|
||||
### Building
|
||||
|
||||
In this project, you may run the following commands to build all packages:
|
||||
|
||||
- `npm run bootstrap`
|
||||
- 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/` of each package (for example, `./packages/selfhosted/dist`),
|
||||
save for the extension which is directory `build/`.
|
||||
|
||||
From here, you may follow the instructions to [use Ruffle on your website](packages/selfhosted/README.md),
|
||||
or run a demo locally with `npm run demo`.
|
||||
|
||||
### Testing
|
||||
|
||||
To run all of the tests in this project, we currently require that you have [Chrome installed to its default location](https://www.google.com/chrome/).
|
||||
|
||||
First, ensure you've build every package (see above), and then run `npm run test` to run the full suite of tests.
|
||||
|
||||
## Structure
|
||||
|
||||
- This directory is a cargo crate which is the actual Flash player, and also a root node package.
|
||||
- [packages/core](packages/core) is a node package which contains the core ruffle web API & wasm bindings.
|
||||
- [packages/selfhosted](packages/selfhosted) is a node package intended for consumption by websites to include Ruffle on their site.
|
||||
- [packages/extension](packages/extension) is a node package that turns Ruffle into a browser extension.
|
||||
- [packages/demo](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](../CONTRIBUTING.md).
|
||||
|
||||
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!
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
# ruffle-core
|
||||
|
||||
ruffle-core is the core javascript bindings to the Wasm ruffle-web binary,
|
||||
and contains the bulk of the public API.
|
||||
|
||||
## Using ruffle-core
|
||||
|
||||
Please do not use this package directly, either use [ruffle-selfhosted](../selfhosted/) or
|
||||
[ruffle-extension](../extension). This page may be merged into ruffle-selfhosted at a later
|
||||
date.
|
||||
|
||||
## Building, testing or contributing
|
||||
|
||||
Please see [the ruffle-web README](../../README.md).
|
||||
|
|
@ -0,0 +1,69 @@
|
|||
# ruffle-demo
|
||||
|
||||
ruffle-demo is an example of how to include Ruffle in your website.
|
||||
It also serves as a nice local test to run Ruffle in the web locally, for developers.
|
||||
|
||||
## Using ruffle-demo
|
||||
|
||||
### Hosted demo
|
||||
|
||||
To view this demo online right now, [check out the hosted demo](http://ruffle-rs.s3-website-us-west-1.amazonaws.com/builds/web-demo/index.html).
|
||||
|
||||
It's exactly the same code as this directory, updated nightly.
|
||||
|
||||
### Run your own demo
|
||||
|
||||
After [building ruffle-web](../../README.md#building-from-source),
|
||||
you can run `npm run demo` in the `web` folder to launch the demo.
|
||||
|
||||
It will start a local web server and print the address in the console.
|
||||
Navigate to that website (usually [http://localhost:8080](http://localhost:8080)) in your browser.
|
||||
|
||||
### Configuring the demo
|
||||
|
||||
The demo provides the ability to have a list of sample SWFs to choose from.
|
||||
This can be helpful if you have a list of useful SWFs to test through, and we use it ourselves
|
||||
to showcase Ruffle on various games or animations.
|
||||
|
||||
To use this, add a new file `swfs.json` next to `index.html` in the demo. The contents should look like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"swfs": [
|
||||
{
|
||||
"location": "swfs/alien_hominid.swf",
|
||||
"title": "Alien Hominid",
|
||||
"author": "Tom Fulp and Dan Paladin",
|
||||
"authorLink": "https://www.newgrounds.com"
|
||||
},
|
||||
{
|
||||
"location": "swfs/saturday_morning_watchmen.swf",
|
||||
"title": "Saturday Morning Watchmen",
|
||||
"author": "Harry Partridge",
|
||||
"authorLink": "https://twitter.com/HappyHarryToons"
|
||||
},
|
||||
{
|
||||
"location": "swfs/synj1.swf",
|
||||
"title": "Synj vs. Horrid Part 1",
|
||||
"author": "Dan Paladin",
|
||||
"authorLink": "https://www.thebehemoth.com"
|
||||
},
|
||||
{
|
||||
"location": "swfs/synj2.swf",
|
||||
"title": "Synj vs. Horrid Part 2",
|
||||
"author": "Dan Paladin",
|
||||
"authorLink": "https://www.thebehemoth.com"
|
||||
},
|
||||
{
|
||||
"location": "swfs/wasted_sky.swf",
|
||||
"title": "Wasted Sky",
|
||||
"author": "Tom Fulp",
|
||||
"authorLink": "https://www.newgrounds.com"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Building, testing or contributing
|
||||
|
||||
Please see [the ruffle-web README](../../README.md).
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
# ruffle-extension
|
||||
|
||||
ruffle-extension is all of the power of Ruffle, in your browser.
|
||||
|
||||
Without needing websites to do anything, the browser extension will automatically replace any Flash content on websites
|
||||
with the Ruffle player.
|
||||
|
||||
The extension will automatically negotiate with websites that do have Ruffle installed, to ensure that there is no
|
||||
conflict between the versions. Newer version of ruffle, either from the website or extension,
|
||||
will always take precedence and disable the other.
|
||||
|
||||
## Using ruffle-extension
|
||||
|
||||
The browser extension is built to work in both Chrome and Firefox.
|
||||
|
||||
We do not yet have a signed release of the extension, so you must load it as a temporary "unpacked" extension.
|
||||
|
||||
Before you can install the extension, you must either download the
|
||||
[latest build](https://ruffle-rs.s3-us-west-1.amazonaws.com/builds/extension/ruffle_extension_latest.zip)
|
||||
or [build it yourself](../../README.md). For the purposes of these instructions, you want the extension as a loose
|
||||
folder and not a packed zip.
|
||||
|
||||
### Chrome
|
||||
|
||||
- Navigate to chrome://extensions/
|
||||
- Turn on Developer mode in the top right corner.
|
||||
- Click Load unpacked.
|
||||
- Select the extension folder.
|
||||
|
||||
### Firefox
|
||||
|
||||
- Navigate to about:debugging
|
||||
- Click on This Firefox.
|
||||
- Click Load Temporary Add-on...
|
||||
- Select manifest.json from your extension folder.
|
||||
|
||||
## Building, testing or contributing
|
||||
|
||||
Please see [the ruffle-web README](../../README.md).
|
||||
|
|
@ -0,0 +1,53 @@
|
|||
# ruffle-selfhosted
|
||||
|
||||
ruffle-selfhosted is the intended way to get Ruffle onto your website.
|
||||
|
||||
You may either include it and forget about it, and we will polyfill existing Flash content,
|
||||
or use our APIs for custom configurations or more advanced usages of the Ruffle player.
|
||||
|
||||
## Using ruffle-selfhosted
|
||||
|
||||
For more examples and in-depth documentation on how to use Ruffle on your website, please
|
||||
[check out our wiki](https://github.com/ruffle-rs/ruffle/wiki/Using-Ruffle#web).
|
||||
|
||||
### Host Ruffle
|
||||
|
||||
Before you can get started with using Ruffle on your website, you must host its files yourself.
|
||||
Either take the [latest build](https://ruffle-rs.s3-us-west-1.amazonaws.com/builds/web/ruffle_web_latest.zip)
|
||||
or [build it yourself](../../README.md), and make these files accessible by your web server.
|
||||
|
||||
Please note that the `.wasm` file must be served properly, and some web servers may not do that
|
||||
correctly out of the box. Please see [our wiki](https://github.com/ruffle-rs/ruffle/wiki/Using-Ruffle#configure-wasm-mime-type)
|
||||
for instructions on how to configure this, if you encounter a `Incorrect response MIME type` error.
|
||||
|
||||
### "Plug and Play"
|
||||
|
||||
If you have an existing website with flash content, you can simply include Ruffle as a script and
|
||||
our polyfill magic will replace everything for you. No fuss, no mess.
|
||||
|
||||
```html
|
||||
<script src="path/to/ruffle/ruffle.js"></script>
|
||||
```
|
||||
|
||||
### Javascript API
|
||||
|
||||
If you want to control the Ruffle player, you may use our Javascript API.
|
||||
|
||||
```html
|
||||
<script>
|
||||
window.RufflePlayer = window.RufflePlayer || {};
|
||||
|
||||
window.addEventListener("DOMContentLoaded", () => {
|
||||
let ruffle = window.RufflePlayer.newest();
|
||||
let player = ruffle.create_player();
|
||||
let container = document.getElementById("container");
|
||||
container.appendChild(player);
|
||||
player.stream_swf_url("movie.swf");
|
||||
});
|
||||
</script>
|
||||
<script src="path/to/ruffle/ruffle.js"></script>
|
||||
```
|
||||
|
||||
## Building, testing or contributing
|
||||
|
||||
Please see [the ruffle-web README](../../README.md).
|
||||
Loading…
Reference in New Issue