Overview
This section is under construction
Installing
Extensions should be unpacked to /Data/Extensions
where an example path would be /Data/Extensions/MyFirstExtension
.
Developer Note: Try to keep extension folder names unique as to not risk collision with other extensions.
Running
Extensions are automatically loaded on Launcher startup with no ability to disable them. If you want to reload an extension you must currently restart the Launcher.
Creating
All extensions require a package.json
manifest at the root of their extension path. You'll recognize this if you've written Node JS modules before. An example is below, with explanations beneath.
An extension should be packed as to be easily installable as described in the Installing
section above. In the future the Launcher will be able to install them itself.
{
"name": "my-first-extension",
"displayName": "My First Extension",
"author": "your-name",
"version": "0.0.1",
"launcherVersion": "9.0.0",
"description": "Example of an Extension",
"icon": "/path/to/icon",
"contributes": {}
}
name - Name of the extension. Must have no spaces or special characters.
displayName - (Optional) - Name displayed to the user. Will use name
if missing.
author - Name of the author. Must have no spaces or special characters.
version - Version of the extension.
launcherVersion - Minimum launcher version supported. Use a wildcard if not applicable.
description - (Optional) - Description of the extension displayed to the user.
icon - (Optional) - Icon to display to the user.
contributes - (Optional) - Used to declare contributions. Relevance is explained in other documentation when relevant.
Code
Extensions may have TypeScript / JavaScript which will be dynamically loaded in to register various things with the API. Check the API documentation for specifics, this will cover it broadly.
Live documentation can be found here: https://flashpointproject.github.io/launcher_ApiDocs/
Your entry point must be declared in package.json
like it would in a Node JS module with main
. If you're using TypeScript make sure this points to the build output, more details below.
{
"main": "./path/to/extension.js"
}
The example below logs Hello World!
to the Logs page, check it after launch to see its results. TypeScript specific instructions are below it.
JavaScript file example
const flashpoint = require('flashpoint-launcher');
function activate(context) {
flashpoint.log.info('Hello World!');
}
exports.activate = activate;
If you're using TypeScript then make sure that TypeScript is installed as a dev dependency with npm install --save-dev typescript
as well. An example tsconfig.json is provided below to build from ./src
into ./dist
(E.G ./src/extension.ts
to ./dist/extension.js
)
You should also install the @types/flashpoint-launcher
package so TypeScript can detect the proper API typings.
Example tsconfig.json
{
"compilerOptions": {
"module": "commonjs",
"outDir": "./dist",
},
"exclude": [
"./dist"
],
"include": [
"./typings",
"./src"
]
}
A simple build script is below to include in package.json
to run npm run build
to rebuild your extension.
Build script
{
"scripts": {
"build": "tsc"
}
}
TypeScript file example
import * as flashpoint from 'flashpoint-launcher';
export function activate(context: flashpoint.ExtensionContext) {
flashpoint.log.info('Hello World!');
}
Themes
You can find information specific to making themes in the Themes documentation, this section will only cover including them in an extension.
Themes are declared as part of the extensions manifest, package.json
. Multiple themes can be declared, but they should have unique IDs. Be careful not to make them too generic as to collide with other extensions.
{
"contributes": {
"themes": [
{
"id": "my-first-theme",
"path": "./themes/MyTheme",
"logoSet": "my-first-logoset"
}
]
}
}
The theme path should be the folder in which theme.css
resides. All files the theme uses should be kept inside this folder. Any attempts to access files outside it will cause an illegal file request warning instead.
Optionally, a logo set can be applied whenever the theme is. Set the logoSet
parameter to the ID of a logo set. It is recommended you include the logo set in the same extension with the theme. See more about logo sets below.
Logo Sets
You can find information specific to making logo sets in the Logo Sets documentation, this section will only cover including them in an extension.
Logo Sets are declared as part of the extensions manifest, package.json
. Multiple logo sets can be declared, but they should have unique IDs. Be careful not to make them too generic as to collide with other extensions.
{
"contributes": {
"logoSets": [
{
"id": "my-first-logoset",
"name": "My Logo Set",
"path": "./logoSets/MyLogoSet"
}
]
}
}
Unlike Themes, the name shown in the Config page is declared here as name
instead.
Logos for platforms will then be read relative to the folder, e.g ./logoSets/MyLogoSet/Flash.png
Context Buttons
Extensions can provide context buttons to show when right-clicking Playlists or Games. The registered command is then run with either the Playlist or Game as an argument when clicked. See API documentation on ``commands.registerCommand` and for more details.
NOTE: runWithNoCuration will allow Curation context buttons to be pressed without a selected Curation (The curation will still be passed as an argument if selected)
{
"contributes": {
"contextButtons": [
{
"context": "game" / "playlist" / "curation",
"name": "Click Me",
"command": "my-first-extension.do-something",
"runWithNoCuration": true
}
]
}
}
Curation Templates
Curation templates can be used when creating new curations, selectable in a dropdown. The meta is applied to the empty curation before being saved.
{
"contributes": {
"curationTemplates": [
{
"name": "Example Template",
"logo": "Flash",
"meta": {
"title": "Example Title",
"originalDescription": "I'm a description"
}
}
]
}
}
name
is the name to display on the new curation button.
logo
will choose the Logo to display next to the name in the dropdown, these are the same as defined by the Logo Set.
meta
is a subset of CurationMeta (see typescript docs) with the ommission of the tags
field. (Will come at a later date)
Applications
Extensions can provide Applications for the launcher to use. Whenever one of the strings in provides
is used the path, url or command is used to run the application instead of defaulting to a relative path to the Flashpoint folder.
Be sure to read past the example for more important information.
{
"applications": [
{
"provides": [
":my-application:"
],
"name": "My Application",
"path": "<extPath>/app.exe"
}
]
}
In this example, any game run with the :my-application:
application path will use <extPath>/app.exe
in its place when launching, where <extPath>
will be replaced with the path of the Extension on disk.
However, Applications can also provide url
or command
instead. The full details of all 3 including path
are listed below.
path
will launch the application with the launch command as its arguments. You must use the <exePath>
or <fpPath>
substitutions to correctly reference the application.
url
will launch that URL in Flashpoints Browser Mode (Electron). The launch command must be substituted since it can not be given as an argument this way. See below for allowed substitutions.
command
will run a registered command that is given the launching Game as an argument and expects a valid response of either a string (path
) or BrowserApplicationOpts (url
) which will then be run accordingly. Substitutions cannot be used on the returned values, although you may find their equivalents in the API, with an exception of os, arch and cwd which you may use Node types for. (@types/node
)
url
and path
string substitutes:
- <exePath> - Path to the extension.
- <fpPath> - Path to the Flashpoint folder.
- <os> - See https://nodejs.org/api/process.html#process_process_platform
- <arch> - See https://nodejs.org/api/process.html#process_process_arch
- <exeDataURL> - URL to the Extensions 'static' folder. Useful for Browser Mode.
- <launchCommand> - Launch Command of the application. Useful for Browser Mode,
path
applications will have it included as arguments already. - <cwd> - Current working directory. This is not guaranteed to be anywhere relative to Flashpoint.exe nor the Flashpoint folder, do not use unless certain.
- <extConf:com.example.value> - Extension config value. Place the config id after the semi-colon.
Configuration
{
"configuration": [
{
"title": "Test Extension",
"properties": {
"title": "Test Select",
"type": "string",
"enum": [
"string1",
"string2"
],
"default": "string1",
"description": "Example of an extension config prop",
}
}
]
}
title - Title of the Configuration section to display on the Config page.
properties - Array of various Configuration props to be editable under this section.
- title - Title of the configuration prop
- description - Description of the configuration prop
- type - Type of this configuration prop's value (string, boolean or object)
- enum - (Optional) - Array of enums to use when you want a Select config box instead of an Input config box.
- default - Default value of this configuration prop