sphinx-nostalgistjs

Sphinx extension for embedding RetroArch in HTML documents, using NostalgistJS. Styling and layout depend on Bootstrap v5, not included.

This package is released on pypi.

Basic Usage

Add this extension to your Sphinx conf.py, like so:

extensions = [
    "sphinx_nostalgistjs",
    ⋯
]

You have to at least configure where to find the JS file to be used whenever a document uses this extension, also in conf.py:

nostalgistjs_script_url = "https://unpkg.com/nostalgist"

In this case, we are using UNPKG as a CDN. You can always download a release of NostalgisJS and place it in your _static folder, loading it like so:

nostalgistjs_script_url = "/_static/nostalgist.js"

If the extension was successfully installed, you can include an emulator in a document, using the following directive:

For reStructuredText:
:::{nostalgistjs}
    :rom_url: "30yearsofnintendont.bin"
    :core_id: genesis_plus_gx
:::    

For Myst: (used throughout this document)
```{nostalgistjs}
    :rom_url: "30yearsofnintendont.bin"
    :core_id: genesis_plus_gx
```

This will embed an emulator that loads the given ROM with the respective emulation core. If rom_url is not an URL, and instead, just a plain filename, NostalgistJS will try to load the ROM from retrobrews, as of the latest version. This uses the file extesnsion in an attempt to determine the target system automatically. The core is not important in this case.

Please consult the launch(...) API of NostalgistJS to understand these arguments, and the available cores. As for the core to use, as a general rule:

System	Core
Mega Drive	genesis_plus_gx
NES	fceumm
SNES	snes9x
GB, GBC, GBA	mgba

Some configuration options allow a document's author to inject arbitrary JavaScript into the page.
This plugin is not appropriate for environments where this may be a security issue.

Advanced Usage

It is possible to change most parameters of NostalgistJS using the directive.

Inside the directive, if there is any content, there must be a JSON object that can configure the emulator in various ways. Most notably, the 'nostalgist_options' is an object that can be used to add options to be passed to the launch(...) API of NostalgistJS.

Here is an example of advanced usage. This injects preamble JS code to setup input device types and mappings, specific to the ROM being used. It can get a bit ugly, though:

```{nostalgistjs}
    :rom_url: "https://example.site/rom.bin"
    :core_id: genesis_plus_gx
    {
        "nostalgist_options": {
            "retroarchConfig": {
                "video_smooth": true,
                "input_auto_mouse_grab": true
            }
        },
        "before_launch_preamble": "let efs = nostalgist.getEmscriptenFS(); efs.mkdirTree('/home/web_user/retroarch/userdata/config/remaps/Genesis Plus GX'); efs.writeFile('/home/web_user/retroarch/userdata/config/remaps/Genesis Plus GX/rom.rmp',  'input_libretro_device_p1 = \"1\"\\ninput_libretro_device_p2 = \"2\"');"
    }
```

Directive options

nostalgist_options

These are the options passed straight to NostalgistJS for configuring the emulator. Consult the NostalgistJS documentation for more info.

The options rom and core are filled in from the directive's rom_url and core_id parameters, and don't need to be specified again. Also, respondToGlobalEvents is set to false by default, but this can be overriden.

Note that there's no need to specify the element option, this is handled automatically by the plugin. Doing so will break the UI controls.

omit_attribution

A boolean. If set to true, this will hide the credits that are rendered at the bottom. Defaults to false.

extra_nostalgist_options

A string. This will be output directly in the JavaScript source, inside an object literal. The resulting object is merged into the options object used for launching NostalgistJS.

This can be used to add options that cannot be expressed in JSON, such as callback functions. Defaults to an empty string.

Custom code injection

before_launch_preamble

A piece of JS code to be executed before the emulator starts, and before any UI setup code runs.

before_launch_epilogue

A piece of JS code to be executed before the emulator starts, but after all UI setup code runs.

on_launch_preamble

A piece of JS code to be executed after the emulator starts, but before any UI setup code runs.

on_launch_epilogue

A piece of JS code to be executed after the emulator starts, and after all UI setup code runs.

Troubleshooting

In case the ROM doesn't load, it may be related to CORS configuration issues. Please refer to the browser's "Developer Tools" console and network tabs for clues of what may be happening.

License

This project is licensed under the GPLv3 license.