Plugin Examples
Complete plugins you can copy and adapt. Each one is a manifest.json and an index.js in a folder; see Creating Your First Plugin for how to install and reload them.
Downloading an emulator for Retro
This plugin adds a one-click emulator setup for Retro: it downloads DuckStation, extracts it into the plugin's folder, and sets it as the PlayStation 1 emulator. Retro then launches games with it as usual.
manifest.json:
{
"name": "DuckStation Installer",
"version": "1.0.0",
"author": "your-name",
"description": "Downloads DuckStation and sets it up for PlayStation 1 in Retro.",
"permissions": ["downloads"]
}index.js:
// Release file names change over time. Check the project's releases page.
const DOWNLOAD =
"https://github.com/stenzek/duckstation/releases/download/latest/duckstation-windows-x64-release.zip";
const EXECUTABLE = "emulators/duckstation/duckstation-qt-x64-ReleaseLTCG.exe";
async function install(ascendara) {
ascendara.toast("Downloading DuckStation…");
await ascendara.download(DOWNLOAD, "downloads/duckstation.zip", {
onProgress: ({ received, total }) =>
total && ascendara.log(`${Math.round((received / total) * 100)}%`),
});
await ascendara.extract("downloads/duckstation.zip", "emulators/duckstation");
await ascendara.files.remove("downloads");
// Keep the user's ROM folders and save folder; only set the emulator.
const state = await window.electron.retro.getState();
if (!state.success) throw new Error(state.error);
const current = state.data.profiles.ps1 || {};
const saved = await window.electron.retro.saveProfile("ps1", {
romFolders: [],
saveFolder: "",
fullscreen: true,
...current,
adapter: "duckstation",
executable: `${ascendara.dataPath}/${EXECUTABLE}`,
});
if (!saved.success) throw new Error(saved.error);
ascendara.toast("DuckStation is ready for PlayStation 1 in Retro", "success");
}
module.exports = {
async start(ascendara) {
if (ascendara.platform !== "win32") return;
if (await ascendara.files.exists(EXECUTABLE)) return;
try {
await install(ascendara);
} catch (error) {
ascendara.toast(`DuckStation setup failed: ${error.message}`, "error");
}
},
};Things to notice:
downloadandextracttake paths inside the plugin's data folder.dataPathturns them into the absolute path Retro needs.- The plugin checks whether the emulator is already there, so it only downloads once.
- Retro's own launch presets (
duckstation,pcsx2,dolphin, and so on) handle the launch arguments. Useadapter: "custom"withargumentsfor other emulators. See Custom emulator arguments. window.electron.retroisn't part of the stable plugin API. SetminAppVersionand test on new Ascendara versions.
Running a tool alongside a game
Some games work better with a helper program running, such as an overlay, a controller mapper, or a performance tool. This plugin starts one when any game launches and closes it when the game exits.
manifest.json:
{
"name": "Overlay Companion",
"version": "1.0.0",
"author": "your-name",
"description": "Starts your overlay with every game and closes it afterwards.",
"permissions": ["processes"]
}index.js:
module.exports = {
start(ascendara) {
const running = new Map();
ascendara.games.onLaunch(async gameName => {
const program = ascendara.storage.get("program");
if (!program || running.has(gameName)) return;
try {
running.set(gameName, await ascendara.run(program, []));
} catch (error) {
ascendara.toast(`Couldn't start the overlay: ${error.message}`, "error");
}
});
ascendara.games.onExit(gameName => {
running.get(gameName)?.kill();
running.delete(gameName);
});
// Let the user choose the program from any game's Manage menu.
ascendara.gameScreen.addAction({
label: "Choose overlay program",
async onClick() {
const program = await window.electron.openFileDialog();
if (!program) return;
ascendara.storage.set("program", program);
ascendara.toast("Overlay program saved", "success");
},
});
},
};Adding a game tool to the Manage menu
Run a program on the selected game, for example a mod manager that takes the game's folder:
module.exports = {
start(ascendara) {
ascendara.gameScreen.addAction({
label: "Open in Mod Manager",
when: game => !game.isCustom,
async onClick(game) {
const folder = await ascendara.games.directory(game);
if (!folder) throw new Error("Couldn't find this game's folder");
await ascendara.run("tools/modmanager/ModManager.exe", ["--game", folder]);
},
});
},
};This needs the processes permission. If the action throws, Ascendara shows the error message as a toast.
Changing a page directly
When there's no helper for what you want, change the page yourself and clean up in onCleanup. This adds a line of text to the top of the Library page:
module.exports = {
start(ascendara) {
let note;
ascendara.onNavigate(route => {
note?.remove();
note = null;
if (route !== "/library") return;
// Wait a moment for the page to render.
setTimeout(() => {
const main = document.querySelector("main") || document.body;
note = document.createElement("p");
note.textContent = "Hello from my plugin!";
note.style.cssText = "padding: 8px 16px; opacity: 0.7;";
main.prepend(note);
}, 300);
});
ascendara.onCleanup(() => note?.remove());
},
};Ascendara's pages are React components and can re-render. For anything more than a small addition, prefer CSS with addStyle, which keeps working when a page re-renders.
Restyling Ascendara
A CSS-only plugin needs no script:
manifest.json:
{
"name": "Rounded Covers",
"version": "1.0.0",
"author": "your-name",
"style": "style.css"
}style.css:
/* Hide the Workshop button and round off images. */
[data-nav-path="/workshopdownloader"] {
display: none !important;
}
img {
border-radius: 12px;
}For colors, use a theme instead (Settings → General → Appearance). Themes are easier to share and switch between than CSS.