Make plugins

Plugins change FPV Sim however you like: put text and panels on the screen, add menu tabs and settings, bind keys, build things on the map, bend the physics or react to tricks, crashes and chat. They're plain JavaScript files: no compiler, no tools, just a text editor.

Your first plugin

Make a file called hello.js with this in it:

export const info = {
  id: 'hello',
  name: 'Hello',
  version: '1.0.0',
  description: 'Says hello and shows your speed.',
  api: 1,
};

export default function (api) {
  // Text on the screen while you fly (x / y are 0..1 of the screen).
  const label = api.ui.text('Hello pilot!', { x: 0.05, y: 0.5 });

  // Runs every frame.
  api.on('frame', () => {
    label.set(`Speed: ${(api.drone.speed * 3.6).toFixed(0)} km/h`);
  });

  api.on('crash', ({ speed }) => api.ui.popup(`Ouch! ${speed.toFixed(1)} m/s`, 'bail'));
}

In the game, open the Plugins tab → + Add plugin (.js) → pick hello.js. Press FLY: your text is on the screen.

Adding, updating and removing plugins

• Add: Plugins tab → + Add plugin (.js). You can pick several files at once. A plugin starts as soon as it's added.
• Update: add the file again. A plugin with the same id replaces the old one.
• Turn off / on: the button on its card. Everything it added through the API (text, panels, tabs, settings, keys, 3D objects, timers) is removed when it's off.
• Reload all restarts every plugin that's on.
• Save .js downloads a plugin's file (handy for the examples).
• Plugins are saved in the game on that device and start again every time the game opens.

File format

A plugin is a JavaScript module with two exports:

You can import from full URLs (for example a library on a CDN), but most plugins don't need to: three.js comes with the API as api.THREE.

Good to know

• Distances are in metres, speeds in m/s, angles in radians, time in seconds.
• The world uses three.js axes: +Y is up, the ground is the X/Z plane, and heading 0 faces −Z ("north", up on the map).
• A plugin that throws errors over and over (say every frame) is switched off automatically, and the error shows on its card.
• Plugins run on your device only. In multiplayer, other pilots don't get your plugins, and the server still decides things like who's on it and the chat.
• Flight Path XP is checked by the server (daily and per-minute limits), so a plugin can't level you up faster than flying can.

Servers and plugins

Server owners decide whether players may use plugins on their server, in server.settings (or live with the set command):

# true: players may use plugins here. false: their plugins are paused while they're on this server.
allow-plugins=true
# Empty = any plugin. Or only these plugin ids, separated by commas:
allowed-plugins=speed-hud,lap-timer

When you join, plugins the server doesn't allow are paused (their card says Paused by server) and start again when you leave. Needs server 1.2.0 or newer; older servers allow everything.

Events

api.on(name, fn) runs fn(data) when something happens. It returns a function that stops listening.

const stop = api.on('trick', (t) => api.log(t.name, t.points));
// later: stop();

api.drone

The drone you're flying. position, velocity, quaternion and rates are the live three.js objects: change them and the drone changes.

// A "boost" shortcut (declared in info.keys, see below): shoot forward.
api.keys.bind('boost', () => {
  const fwd = new api.THREE.Vector3(0, 0, -1).applyQuaternion(api.drone.quaternion);
  api.drone.velocity.addScaledVector(fwd, 15);
});
// Indestructible drone.
api.drone.spec.crashSpeed = 999;

api.world and 3D

const { THREE } = api;
api.on('flightStart', () => {
  const box = new THREE.Mesh(new THREE.BoxGeometry(2, 2, 2), new THREE.MeshStandardMaterial({ color: 0x39ff6a }));
  box.position.copy(api.world.spawn).add(new THREE.Vector3(0, 3, -10));
  api.world.add(box);
});

Objects you add are drawn but the drone doesn't collide with them; use the drone's position to make your own triggers (see the Ring Race example).

api.ui: screen, menus and settings

Text on the screen

api.ui.text(content, options) returns { el, set(text), show(on), remove() }.

Panels

api.ui.panel(title, { x, y, width, when }) gives a boxed window with a title and a hide button. Put anything in .body. It returns { el, body, show(on), remove() }. Panels take clicks; text doesn't. when defaults to 'always'.

const p = api.ui.panel('Tools', { x: 0.02, y: 0.3, width: 200, when: 'flying' });
p.body.append(
  api.ui.el('button', { textContent: 'Back to start', onclick: () => api.drone.reset() }),
);

Building elements

api.ui.el(tag, props, children) makes an HTML element. props can set any property (textContent, value, class…), style as an object, and events as onclick, onchange, oninput… You can also use normal DOM code (document.createElement).

A menu tab

api.ui.menuTab(title, render) adds a tab to the main menu. render(container) draws it every time it's opened. Returns { open(), redraw() }. Class names that match the game's look: mp-box (a panel), sub (grey text), cards wide + card (a grid of cards), fly (an orange button).

api.ui.menuTab('My Tab', (box) => {
  box.append(api.ui.el('div', { class: 'mp-box' }, [
    api.ui.el('h2', { textContent: 'Hello from a plugin' }),
    api.ui.el('button', { class: 'fly', textContent: 'Fly Old Town', onclick: () => { api.game.settings.mapId = 'town'; } }),
  ]));
});

Settings

api.ui.settingsSection(title, render) adds a section at the end of Settings. Use the field class for a label + control row like the game's own settings, and api.storage to remember choices.

Messages

Shortcuts (api.keys)

Declare your plugin's shortcuts in info.keys. Each one gets a row in Settings → Plugin shortcuts, where the player can set it to any key or controller button (or both). Then bind it by its name:

export const info = {
  id: 'turbo', name: 'Turbo', api: 2,
  keys: {
    boost: { name: 'Boost', key: 'KeyB', pad: 3 },   // default: B, or Y on a controller
    panel: { name: 'Open panel', key: 'F4' },
  },
};

export default function (api) {
  api.keys.bind('boost', () => { /* … */ });
  api.ui.osd(`Boost: ${api.keys.label('boost')}`);  // what it's set to now, e.g. "B / 🎮 Y"
}

Shortcuts never fire while the player types in a text box (like the chat), and a key a plugin uses (F5, PageUp…) won't also reload or scroll the page. In Settings, a key the game itself uses is outlined in yellow. The game uses W A S D, X, Shift, the arrows, Space, Enter, Esc, P, R, C, N, M, V and T.

api.physics and api.time

Multipliers on the real physics: 1 is normal. If two plugins change the same value, they multiply together. Everything goes back to normal when the plugin stops.

// Break the top speed: about 112 → 190 km/h on a Freestyle 5".
api.physics.propSpeed = 2;
api.physics.thrust = 1.4;
api.physics.drag = 0.55;

api.input: the sticks

input.modify(fn) runs fn(sticks) every flight frame, before the flight controller reads the sticks. Change the values to fly the drone yourself: autopilots, assists, input curves, return to home…

// Altitude hold: keep the height you had when you pressed the shortcut.
let target = null, base = 0.5;
api.keys.bind('hold', () => {
  target = target === null ? api.drone.position.y : null;
  base = api.input.sticks.throttle;
});
api.input.modify((s) => {
  if (target === null) return;
  const err = target - api.drone.position.y;
  base += err * 0.0004;
  s.throttle = base + err * 0.06 - api.drone.velocity.y * 0.05;
});

api.camera

api.sound

api.storage

Saved on the device, separately for each plugin, and kept across restarts. Values can be anything JSON can hold.

const best = api.storage.get('best', 0);   // second value = default
api.storage.set('best', 42.5);
api.storage.remove('best');

api.game

api.multiplayer

Listen with api.on('chat', …).

Timers, logs and cleanup

Example plugins

These come with the game (Plugins tab → Examples) and are here to download and change.

Recipes

Do something once per second

api.every(1000, () => { if (api.game.state === 'flying') api.log(api.drone.position); });

A chat command

api.on('chat', ({ from, text }) => {
  if (text === '!where') api.ui.popup(`${from} wants to know where you are`);
});

Slow motion while you hold a key

let slow = false;
api.keys.bind('KeyQ', () => (slow = !slow));
api.on('frame', ({ dt, state }) => {
  if (!slow || state !== 'flying') return;
  api.drone.velocity.multiplyScalar(1 - 2 * dt);  // heavy air
});

Restyle the game

api.ui.css(`#osd { color: #39ff6a; }  #fly { background: #2e7dff; }`);

Ideas to build

Looking for something to make? Every one of these can be done with the API above:

• Autopilots: altitude hold, position hold, GPS rescue (fly home and land), a waypoint mission, "follow that drone" in multiplayer.
• Game modes: ring races, a slalom, tag in multiplayer, a precision-landing challenge, deliveries between two spots, a crash-free streak score.
• Training: a hover trainer that scores how still you hold, a stick display, a throttle-control meter, a power-loop coach that checks your height.
• Physics toys: Moon or Jupiter gravity, slow motion, a turbo button, a heavy-payload mode, infinite battery, a speed unlocker.
• Tools: a ghost of your best run, lap timers on any map, a speed trap, a flight logger that saves CSV, a drone trail, waypoints and teleports.
• Look and sound: new HUD styles, a sports-caster voice for tricks, new colours for the whole game with ui.css.

Autocomplete in your editor (types)

Download flysim-plugin.d.ts, put it next to your plugin, and add this line at the top of the plugin. Editors like VS Code then show every API function with its description as you type.

/** @param {import('./flysim-plugin').PluginApi} api */
export default function (api) { … }

Debugging

• If a plugin fails to start, or keeps throwing errors, the message shows on its card in the Plugins tab.
• Windows app: press Ctrl+Shift+F12 to open the developer tools. The Console shows api.log output and full errors with line numbers.
• Web version: F12 in your browser.
• Edit your file, add it again (same id replaces it), and it restarts with the changes.