The hot reload feature allows you to develop plugins rapidly by automatically reloading your script in real-time whenever you save your JavaScript file. This eliminates the need to restart the game or reload your park after making changes.
Enabling Hot Reload
Locate your config file
Find your config.ini file in your OpenRCT2 user directory:
- Windows:
C:\Users\YourName\Documents\OpenRCT2\config.ini
- Mac:
/Users/YourName/Library/Application Support/OpenRCT2/config.ini
- Linux:
$XDG_CONFIG_HOME/OpenRCT2/config.ini or $HOME/.config/OpenRCT2/config.ini
Edit the configuration
Open config.ini in a text editor and find the [plugin] section. If it doesn’t exist, create it.Set enable_hot_reloading to true:[plugin]
enable_hot_reloading = true
Save and restart OpenRCT2
Save the config.ini file and restart OpenRCT2 for the change to take effect.
How Hot Reload Works
When hot reload is enabled:
- OpenRCT2 monitors your plugin files for changes
- When you save a JavaScript file, the game detects the change
- The plugin is automatically reloaded without restarting the game
- Your changes take effect immediately
Hot reload works best with plugins that create UI windows or subscribe to events. You can close and reopen custom windows to see your changes instantly.
Demo Video
A demonstration of hot reload in action can be found on YouTube: OpenRCT2 plugin hot-reload demo
The video shows:
- Writing code in Visual Studio Code
- Saving the file
- Seeing changes immediately reflected in OpenRCT2
- Opening and closing custom windows to preview updates
Development Workflow
With hot reload enabled, your development workflow becomes much faster:
Set up your environment
- Enable hot reload in
config.ini
- Open your park in OpenRCT2
- Open your plugin file in your code editor (VS Code recommended)
Make changes
Edit your plugin code in your editor
Save and test
Save the file (Ctrl+S / Cmd+S)The plugin automatically reloads in OpenRCT2
Repeat
Continue making changes and saving - no need to restart!
Example: Developing a Custom Window
Here’s a typical workflow when developing a custom UI window:
function main() {
if (typeof ui === 'undefined') return;
ui.registerMenuItem('My Window', function() {
openMyWindow();
});
}
function openMyWindow() {
var window = ui.openWindow({
classification: 'my-window',
title: 'My Custom Window',
width: 200,
height: 100,
widgets: [
{
type: 'label',
x: 10,
y: 20,
width: 180,
height: 14,
text: 'Park cash: ' + park.cash
}
]
});
}
registerPlugin({
name: 'Custom Window',
version: '1.0',
authors: ['Your Name'],
type: 'local',
licence: 'MIT',
targetApiVersion: 34,
main: main
});
- Open the window using the menu item
- Make changes to the window layout or content
- Save the file
- Close the window in OpenRCT2
- Reopen it from the menu
- See your changes instantly!
Best Practices
Clean Up Resources
When your plugin is reloaded, the old instance is disposed. Make sure to clean up any resources:
var subscriptions = [];
function main() {
// Store subscriptions so they can be disposed
subscriptions.push(
context.subscribe('interval.day', function() {
console.log('Day elapsed');
})
);
}
// Clean up is handled automatically on reload
Use Window Classifications
Give your custom windows unique classifications to prevent duplicates:
function openMyWindow() {
// Close existing window if open
var existing = ui.getWindow('my-unique-window');
if (existing) {
existing.close();
}
var window = ui.openWindow({
classification: 'my-unique-window',
title: 'My Window',
// ...
});
}
Separate Development and Production
You might want different behavior during development:
var isDevelopment = context.configuration.get('my-plugin.development', false);
function main() {
if (isDevelopment) {
console.log('Development mode - verbose logging enabled');
}
// Rest of plugin code
}
context.configuration.set('my-plugin.development', true);
Limitations
Syntax Errors
If your plugin has syntax errors, hot reload will fail and an error will be logged to the console. Fix the syntax error and save again.
State Persistence
When a plugin is reloaded:
- All variables are reset
- Event subscriptions are disposed and re-created
- Windows remain open but need to be manually closed and reopened to see changes
Data stored in plugin variables will be lost on reload. Use context.sharedStorage or context.getParkStorage() to persist data across reloads.
Persisting Data Across Reloads
function main() {
var storage = context.getParkStorage();
// Load saved state
var counter = storage.get('counter', 0);
console.log('Counter value:', counter);
// Increment and save
counter++;
storage.set('counter', counter);
// This counter persists across hot reloads!
}
TypeScript Watch Mode
tsc --watch --target ES5 my-plugin.ts
Webpack Watch Mode
If using webpack for bundling:
VS Code Task
Create a .vscode/tasks.json file:
{
"version": "2.0.0",
"tasks": [
{
"label": "Watch TypeScript",
"type": "shell",
"command": "tsc",
"args": ["--watch", "--target", "ES5"],
"isBackground": true,
"problemMatcher": "$tsc-watch"
}
]
}
Ctrl+Shift+B (or Cmd+Shift+B on Mac).
Troubleshooting
Hot Reload Not Working
- Check config.ini: Ensure
enable_hot_reloading = true under [plugin]
- Restart OpenRCT2: Config changes require a restart
- Check file location: Plugin must be in the
plugin directory
- Check file extension: File must end with
.js
- Check console: Look for error messages in the console
Changes Not Appearing
- Close and reopen windows: Custom windows need to be reopened to show changes
- Check syntax: Syntax errors prevent reloading
- Check file saved: Ensure you actually saved the file
- Check build output: If using TypeScript/webpack, ensure compilation succeeded
Multiple Reloads
If the plugin reloads multiple times:
- Your build tool might be writing the file multiple times
- Try adding a small delay in your build process
- Check that you don’t have multiple watchers running
Complete Example
Here’s a complete example showing hot reload in action:
var windowCounter = 0;
function main() {
if (typeof ui === 'undefined') return;
// Register menu item
ui.registerMenuItem('Counter Window', function() {
openCounterWindow();
});
console.log('Counter plugin loaded (hot reload active)');
}
function openCounterWindow() {
// Get persisted counter value
var storage = context.getParkStorage();
var count = storage.get('counter', 0);
var window = ui.openWindow({
classification: 'counter-window',
title: 'Counter Example',
width: 200,
height: 80,
widgets: [
{
type: 'label',
x: 10,
y: 20,
width: 180,
height: 14,
text: 'Count: ' + count
},
{
type: 'button',
x: 10,
y: 40,
width: 80,
height: 14,
text: 'Increment',
onClick: function() {
count++;
storage.set('counter', count);
window.close();
openCounterWindow(); // Reopen with new value
}
}
]
});
}
registerPlugin({
name: 'Counter Example',
version: '1.0',
authors: ['Your Name'],
type: 'local',
licence: 'MIT',
targetApiVersion: 34,
main: main
});
- Change the window layout and see it immediately
- Modify button text or colors
- Add new widgets
- Change the counter logic
All without restarting OpenRCT2! 
