Getting Started

SkyScript is a C++ static library that adds CEF browser windows to X-Plane 12 plugins. This guide covers two topics:

1. Integrating the library into your X-Plane plugin
2. Building a web app that runs inside a SkyScript browser window

Integrating the Library

Prerequisites

• CMake 3.25.1+, C++23 compiler
• X-Plane SDK 4.2.0
• Pre-built CEF binaries (included in lib/<platform>/cef/)

CMake Setup

SkyScript builds as a static library (SkyScriptLib). Link it from your plugin's CMakeLists.txt:

add_subdirectory(path/to/skyscript)
target_link_libraries(MyPlugin PUBLIC SkyScriptLib)

Minimal Plugin

#include "skyscript.h"

PLUGIN_API int XPluginStart(char* name, char* sig, char* desc) {
    strcpy(name, "My Plugin");
    strcpy(sig, "com.example.myplugin");
    strcpy(desc, "Plugin with embedded browser");

    SkyScript::initialize();   // Registers flight loop, VR monitoring, cursor
    return 1;
}

PLUGIN_API void XPluginStop() {
    SkyScript::shutdown();     // Unregisters flight loop, destroys all windows
}

PLUGIN_API int XPluginEnable() {
    SkyScript::loadAppsFromDirectory();  // Scan apps/ folder
    return 1;
}

PLUGIN_API void XPluginDisable() {}

Bundling Assets

The SkyScript library distribution includes an assets/ folder containing icons, sounds, and other resources used by SkyScript UI elements (back buttons, notifications, etc.).

If you are building a third-party plugin that uses SkyScript as a library, you need to:

1. Copy the assets/ directory from the library distribution into your plugin folder.
2. Call SkyScript::setAssetsPath() after initialize() to tell SkyScript where to find the assets.

#include "skyscript.h"
#include <XPLMPlugin.h>

PLUGIN_API int XPluginStart(char* name, char* sig, char* desc) {
    strcpy(name, "My Plugin");
    strcpy(sig, "com.example.myplugin");
    strcpy(desc, "Plugin with embedded browser");

    SkyScript::initialize();

    // Point SkyScript to the assets bundled with your plugin
    char pluginPath[512];
    XPLMGetPluginInfo(XPLMGetMyID(), nullptr, pluginPath, nullptr, nullptr);
    std::string myPluginDir = std::string(pluginPath).substr(0, std::string(pluginPath).rfind('/'));
    SkyScript::setAssetsPath(myPluginDir + "/assets");

    return 1;
}

Without this step, SkyScript will look for assets in its own plugin directory (Resources/plugins/SkyScript/assets/), which won't exist if SkyScript is only used as a library.

For Go bindings, the equivalent call is:

skyscript.Initialize()
skyscript.SetAssetsPath(myPluginDir + "/assets")

See the C++ Library API for the full reference and the example/ folder in the repo for a complete working plugin.

---

Building a Web App

This section walks you through creating a SkyScript app using the Hello World example as a reference.

Prerequisites

• Node.js 18 or later
• A text editor

Scaffold the Project

Create a new folder inside apps/ in your SkyScript plugin directory (or in the repo if you're developing from source):

mkdir apps/my-app && cd apps/my-app

Create the manifest

Every app needs a manifest.yaml at its root. Create apps/my-app/manifest.yaml:

name: My App
hide_addressbar: true
framerate: 20

See the Manifest Reference for all available fields.

Bootstrap with Create React App

The Hello World example uses React with TypeScript. You can use any framework — or plain HTML — but React is a good starting point:

npx create-react-app . --template typescript

Set the homepage field in package.json so the built assets use relative paths:

{
  "homepage": "."
}

Project structure

After scaffolding, your app should look like this:

apps/my-app/
├── manifest.yaml        # Required — app metadata
├── package.json
├── public/
│   └── index.html
├── src/
│   ├── index.tsx
│   ├── App.tsx
│   └── ...
└── tsconfig.json

Add TypeScript Declarations

Create src/react-app-env.d.ts (or add to your existing one) so TypeScript knows about the SkyScript API:

/// <reference types="react-scripts" />

interface SkyscriptXplm {
  getDataref(ref: string): Promise<number | string | number[]>;
  setDataref(ref: string, value: number | string, valueType?: string): Promise<void>;
  executeCommand(command: string): Promise<void>;
}

interface Window {
  skyscript: {
    xplm: SkyscriptXplm;
  };
}

Write Your App

Replace src/App.tsx with a simple component that reads a dataref:

import { useState } from 'react';

function App() {
  const [zuluTime, setZuluTime] = useState('--');

  async function readTime() {
    try {
      const value = await window.skyscript.xplm.getDataref(
        'sim/time/zulu_time_sec'
      );
      setZuluTime(Number(value).toFixed(1));
    } catch (err: any) {
      setZuluTime(`Error: ${err.message}`);
    }
  }

  return (
    <div style={{ padding: 40, textAlign: 'center', color: '#e0e0e0' }}>
      <h1>My App</h1>
      <p>Zulu time: {zuluTime}</p>
      <button onClick={readTime}>Read Dataref</button>
    </div>
  );
}

export default App;

Build

npm run build

This produces a build/ folder containing index.html and static assets. SkyScript serves this folder directly.

Deploy to X-Plane

If you're developing outside the plugin directory, copy the built output:

cp -r build/ /path/to/X-Plane/Resources/plugins/SkyScript/apps/my-app/
cp manifest.yaml /path/to/X-Plane/Resources/plugins/SkyScript/apps/my-app/

If you're developing inside the repo's apps/ folder, the build script handles this automatically:

# From the repo root
./build_platforms.sh mac

This compiles the plugin, builds all apps, and copies everything to the X-Plane plugins folder.

Test

1. In X-Plane, go to Plugins > SkyScript > Reload configuration.
2. Open Plugins > SkyScript > My App.
3. Click Read Dataref — you should see the current Zulu time.

Next Steps

• Read the full JavaScript API Reference to learn about setDataref and executeCommand.
• Read the C++ Library API for the full reference.
• Check the Manifest Reference for options like user_agent, framerate, and audio_muted.
• Look at the Hello World source for a more complete example with polling, custom dataref input, and command execution.