Context API

Core APIs for plugin lifecycle, storage, and game state management

The context object provides core functionality for OpenRCT2 plugins, including access to storage, game actions, event subscriptions, and utility functions.

Properties

apiVersion · number

The current version of the plugin API. This integer increments by 1 with each API change.

console.log(`API Version: ${context.apiVersion}`);

configuration · Configuration

The user’s current configuration settings.

const language = context.configuration.get('general.language');

sharedStorage · Configuration

Shared generic storage for all plugins. Data persists across OpenRCT2 instances and is stored as a single JSON file in the OpenRCT2 user directory.

Objects and arrays are only copied by reference. The external file is only written when using the set method.

context.sharedStorage.set('myPlugin.lastRun', Date.now());
const lastRun = context.sharedStorage.get('myPlugin.lastRun');

mode · GameMode

The current game mode/screen. Can be:

• "normal" - Regular gameplay
• "title" - Title screen
• "scenario_editor" - Scenario editor
• "track_designer" - Track designer
• "track_manager" - Track manager

if (context.mode === 'normal') {
  console.log('Game is running');
}

paused · boolean

Whether the game is currently paused. Readonly in network mode.

context.paused = true; // Pause the game

Storage Methods

getParkStorage()

Gets the storage for the current plugin or a specified plugin. Data is persisted within the .park file.

pluginName · string

The name of the plugin to get storage for. If undefined, uses the current plugin’s name. Plugin names are case sensitive.

const storage = context.getParkStorage();
storage.set('rideCount', map.numRides);

const otherStorage = context.getParkStorage('OtherPlugin');
const data = otherStorage.get('someKey');

All data is serialized every time the park is saved, including automatic saves. Keep storage data minimal for performance.

Rendering Methods

captureImage()

Renders the current map state and saves to disk. Useful for server administration and timelapse creation.

options · CaptureOptions · required

Options controlling the capture and output file.

Show CaptureOptions Properties

filename · string

Relative filename from the screenshot directory. Auto-generated by default using system date/time.

width · number

Width in pixels. Omit for giant screenshot.

height · number

Height in pixels. Omit for giant screenshot.

position · CoordsXY

Map position to center the view on. Omit for giant screenshot.

zoom · number · required

Zoom level: 0 is 1:1, 1 is 2:1, 2 is 4:1, etc.

rotation · number · required

Camera rotation from 0 to 3.

transparent · boolean

Enable transparency in the screenshot.

context.captureImage({
  filename: 'my-park.png',
  width: 1920,
  height: 1080,
  position: { x: 2048, y: 2048 },
  zoom: 0,
  rotation: 0,
  transparent: false
});

Utility Methods

getRandom()

Generates a random integer using the game’s pseudo-random number generator. This is part of the game state and shared across all clients.

min · number · required

The minimum value (inclusive).

max · number · required

The maximum value (exclusive).

// Get random value between 0 and 99
const random = context.getRandom(0, 100);

Use this instead of Math.random() during game logic routines to maintain synchronization in multiplayer.

formatString()

Formats a string using OpenRCT2’s formatting codes and arguments.

fmt · string · required

The format string (e.g., “Guests: ”)

args · any[]

Arguments to insert into the string.

const text = context.formatString('Park rating: {INT32}', park.rating);
const currency = context.formatString('Cash: {CURRENCY}', park.cash);

getIcon()

Gets the image number for a given icon name.

iconName · IconName · required

The name of the icon.

const guestIcon = context.getIcon('guests');
const rideIcon = context.getIcon('new_ride');

Game Actions

registerAction()

Registers a custom game action that allows clients to interact with the game.

action · string · required

The unique name of the action.

query · function · required

Logic for validating and returning a price for an action.

execute · function · required

Logic for validating and executing the action.

context.registerAction(
  'mycustomaction',
  (args) => {
    // Query: validate and return cost
    return { cost: 1000 };
  },
  (args) => {
    // Execute: perform the action
    console.log('Action executed!');
    return { cost: 1000 };
  }
);

queryAction()

Queries the result of running a game action without executing it.

action · string · required

The name of the action.

args · object · required

The action parameters.

callback · function

Function called with the result.

context.queryAction('ridesetprice', {
  ride: 0,
  price: 500,
  isPrimaryPrice: true
}, (result) => {
  console.log('Cost:', result.cost);
});

executeAction()

Executes a game action. In multiplayer, this sends a request to the server.

action · string · required

The name of the action.

args · object · required

The action parameters.

callback · function

Function called with the result.

context.executeAction('parksetname', {
  name: 'My Amazing Park'
}, (result) => {
  if (result.error === 0) {
    console.log('Park renamed!');
  }
});

Event Subscription

subscribe()

Subscribes to game events. Returns an IDisposable that can be used to unsubscribe.

hook · HookType · required

The event type to subscribe to.

callback · Function · required

Function to call when the event occurs.

Interval Events

// Called every game tick (~40 times per second)
context.subscribe('interval.tick', () => {
  console.log('Tick!');
});

// Called once per in-game day
context.subscribe('interval.day', () => {
  console.log('New day!');
});

Map Events

// Called when the map changes
context.subscribe('map.change', () => {
  console.log('Map modified!');
});

// Called when the park is saved
context.subscribe('map.save', () => {
  console.log('Park saved!');
});

Network Events

context.subscribe('network.join', (e) => {
  console.log(`Player ${e.player} joined`);
});

context.subscribe('network.chat', (e) => {
  console.log(`${e.player}: ${e.message}`);
});

Action Events

context.subscribe('action.execute', (e) => {
  console.log(`Action: ${e.action}`);
});

Timers

setInterval()

Registers a function to be called repeatedly at a specified interval.

callback · Function · required

The function to call.

delay · number · required

The delay in milliseconds between calls.

const handle = context.setInterval(() => {
  console.log('Called every second');
}, 1000);

// Later, stop the interval
context.clearInterval(handle);

setTimeout()

Registers a function to be called once after a specified delay.

callback · Function · required

The function to call.

delay · number · required

The delay in milliseconds.

const handle = context.setTimeout(() => {
  console.log('Called after 5 seconds');
}, 5000);

// Can be cancelled before it executes
context.clearTimeout(handle);

Track Segments

getTrackSegment()

Gets track segment information for a given type.

type · number · required

The track segment type.

const segment = context.getTrackSegment(0);
if (segment) {
  console.log(segment.description);
  console.log('Length:', segment.length);
}

getAllTrackSegments()

Gets all available track segments.

const segments = context.getAllTrackSegments();
console.log(`Total segments: ${segments.length}`);