API Reference

The SkyScript API provides JavaScript/TypeScript access to X-Plane SDK functionality. All APIs are accessed through the global XPlane object. App management is available through the global SkyScript object.

API Overview

Namespace	Description
XPlane.dataref	Read and write simulator data
XPlane.scenery	Load objects, probe terrain, magnetic variation
XPlane.instance	Create and manage object instances
XPlane.graphics	Coordinate system conversions
SkyScript	App management and debugging

Quick Examples

Reading Flight Data

// Current altitude in feet
const altitudeFt = XPlane.dataref.getFloat("sim/flightmodel/position/elevation") * 3.28084;

// Aircraft heading
const heading = XPlane.dataref.getFloat("sim/flightmodel/position/mag_psi");

// GPS coordinates
const lat = XPlane.dataref.getDouble("sim/flightmodel/position/latitude");
const lon = XPlane.dataref.getDouble("sim/flightmodel/position/longitude");

Writing Data

// Set autopilot altitude
if (XPlane.dataref.canWrite("sim/cockpit/autopilot/altitude")) {
  XPlane.dataref.setFloat("sim/cockpit/autopilot/altitude", 35000);
}

// Toggle landing lights
XPlane.dataref.setInt("sim/cockpit/electrical/landing_lights_on", 1);

Placing Objects

// Load and place an object
const obj = XPlane.scenery.loadObject("path/to/object.obj");
const instance = XPlane.instance.create(obj);

// Get ground position
const probe = XPlane.scenery.createProbe();
const terrain = XPlane.scenery.probeTerrain(probe, x, y, z);

// Position on ground
XPlane.instance.setPosition(instance, {
  x: terrain.x,
  y: terrain.y,
  z: terrain.z,
  heading: 90
});

// Cleanup
XPlane.scenery.destroyProbe(probe);

Coordinate Conversion

// Convert GPS to local coordinates
const local = XPlane.graphics.worldToLocal(47.45, -122.31, 100);

// Convert local back to GPS
const world = XPlane.graphics.localToWorld(local.x, local.y, local.z);

App Management (SkyScript API)

// List all installed apps
const apps = SkyScript.listApps();
console.log(`Installed apps: ${apps.join(', ')}`);

// Open an app window
SkyScript.openAppWindow('hello-world');

// Open the developer inspector for debugging an app
SkyScript.openAppInspector('hello-world');

// Reload an app to refresh its HTML/JS
SkyScript.reloadApp('hello-world');

TypeScript Support

SkyScript provides full TypeScript definitions. Add them to your project:

// tsconfig.json
{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./src/types"]
  }
}

Then copy the type definitions from the SkyScript repository.

Checking API Availability

Always check if the API is available before using it:

if (typeof XPlane !== 'undefined') {
  // Safe to use XPlane API
  const altitude = XPlane.dataref.getFloat("sim/flightmodel/position/elevation");
} else {
  // Running outside X-Plane (e.g., in browser during development)
  console.log("XPlane API not available");
}

Error Handling

Most API functions return null or false on failure:

const obj = XPlane.scenery.loadObject("invalid/path.obj");
if (!obj) {
  console.error("Failed to load object");
  return;
}

const success = XPlane.dataref.setFloat("sim/readonly/dataref", 100);
if (!success) {
  console.error("Failed to write dataref (may be read-only)");
}

Finding DataRefs

X-Plane has thousands of DataRefs. Use these resources to find the ones you need:

• DataRefTool - In-sim DataRef browser
• X-Plane DataRefs - Official documentation
• SimInnovations DataRef Search - Searchable database