Scripting Oolite with JavaScript

Oolite 1.68 and later supports scripts written in ECMAScript (more commonly known as JavaScript) in addition to its traditional model based on property lists. This page provides an overview of how JavaScript is used in Oolite. The page Oolite JavaScript Reference: object model provides reference for Oolite-specific objects and methods. The page Oolite JavaScript Reference: World script event handlers provides reference for the event handlers Oolite supports. The language standards and some tutorials can be found through the Wiki links provided above. The announcement here may be of use (scroll down to "Javascipt").

Using JavaScript

Currently, JavaScript is supported for “worldScripts”, that is, as a replacement for scripts in script.plist and shipScripts, that acts as expansion for the ships AI. While a script.plist file may contain any number of separate scripts, a single JavaScript file may contain only one script.

If your OXP only uses one script, place a JavaScript file named script.js (or script.es) in the OXP’s Config directory. If you wish to use multiple scripts, you may instead create file named world-scripts.plist in the Config directory. This property list file should consist of an array of worldScript names; the named scripts should exist in a directory named Scripts inside your OXP. As with most “atomic” files (files which cannot be merged), such script files must have a unique name to avoid conflicts with other OXPs. Using the world-scripts.plist method, you can combine JavaScript, plist and OOS scripts however you wish.

Whereas plist scripts are based on polling – all scripts are run at semi-regular intervals, whether they need to be or not – scripts written in JavaScript are “event driven” – different functions, or event handlers, in the script are called in response to state changes in the game, or when other events of interest happen. For instance, willExitWitchSpace is called just before player exits witchspace, and alertConditionChanged is called whenever the alert condition changes.

See the event handler reference for a full list of handlers and when Oolite will call them.

script.js File Template

Copy and paste this template into a file called script.js in the OXP Config directory. Ensure you change at least the Name value. Every script must have a unique name. If multiple scripts with the same name are encountered, Oolite will arbitrarily select one and discard the others.

Note: If you do not want to react to one of these events anyway you can fully remove that function. This list is complete now as it is easier for novice users to remove than to add.

this.name           = "My OXP Script";
this.author         = "Your Name Here";
this.copyright      = "(C) 2021 Me.";
this.licence        = "CC-NC-by-SA 2.0";
this.description    = "This OXP doesn't do very much yet.";
this.version        = "1.0 alpha 1";

"use strict";

// Game State

this.gamePaused = function()
{
    log(this.name, "gamePaused()");
}

this.gameResumed = function()
{
    log(this.name, "gameResumed()");
}

this.playerWillSaveGame = function()
{
    log(this.name, "playerWillSaveGame()");
}

this.startUp = function()
{
    log(this.name, "startup()");
}

this.startUpComplete = function()
{
    log(this.name, "startupComplete()");
}

// Docking

this.shipWillDockWithStation = function(station)
{
    log(this.name, "shipWillDockWithStation("+station+")");
}

this.shipDockedWithStation = function(station)
{
    log(this.name, "shipDockedWithStation("+station+")");
}

this.shipWillLaunchFromStation = function(stationLaunchedFrom)
{
    log(this.name, "shipWillLaunchFromStation("+stationLaunchedFrom+")");
}

this.shipLaunchedFromStation = function(stationLaunchedFrom)
{
    log(this.name, "shipLaunchedFromStation("+stationLaunchedFrom+")");
}

this.playerStartedAutoPilot = function()
{
    log(this.name, "playerStartedAutoPilot()");
}

this.playerCancelledAutoPilot = function()
{
    log(this.name, "playerCancelledAutoPilot()");
}

this.playerDockingClearanceCancelled = function()
{
    log(this.name, "playerDockingClearanceCancelled()");
}

this.playerDockingClearanceExpired = function()
{
    log(this.name, "playerDockingClearanceExpired()");
}

this.playerDockingClearanceGranted = function()
{
    log(this.name, "playerDockingClearanceGranted()");
}

this.playerDockingRefused = function()
{
    log(this.name, "playerDockingRefused()");
}

this.playerRequestedDockingClearance = function(message)
{
    log(this.name, "playerRequestedDockingClearance("+message+")");
}

this.playerRescuedEscapePod = function(fee, reason, occupant)
{
    log(this.name, "playerRescuedEscapePod("+fee + ", " + reason + ", " + occupant+")");
}

this.playerCompletedContract = function(type, result, fee, contract)
{
    log(this.name, "playerCompletedContract("+fee + ", " + reason + ", " + occupant+")");
}

this.playerEnteredContract = function(type, contract)
{
    log(this.name, "playerEnteredContract("+type + ", " + contract + ")");
}

// Witchspace jumps

this.playerStartedJumpCountdown = function(type, seconds)
{
    log(this.name, "playerStartedJumpCountdown("+type + ", " + seconds + ")");
}

this.playerCancelledJumpCountdown = function()
{
    log(this.name, "playerCancelledJumpCountdown()");
}

this.playerJumpFailed = function(reason)
{
    log(this.name, "playerJumpFailed(" + reason + ")" );
}

this.shipWillEnterWitchspace = function(cause, destination)
{
    log(this.name, "shipWillEnterWitchspace(" + cause + ", " + destination + ")");
}

this.shipWillExitWitchspace = function()
{
    log(this.name, "shipWillEnterWitchspace()");
}

this.shipExitedWitchspace = function()
{
    log(this.name, "shipExitedWitchspace()");
}

this.playerEnteredNewGalaxy = function(galaxyNumber)
{
    log(this.name, "playerEnteredNewGalaxy(" + galaxyNumber + ")");
}

// Enter/Exit Aegis
this.shipEnteredStationAegis = function(station)
{
    log(this.name, "shipEnteredStationAegis(" + station + ")");
}

this.shipExitedStationAegis = function(station)
{
    log(this.name, "shipExitedStationAegis(" + station + ")");
}

this.shipEnteredPlanetaryVicinity = function(planet)
{
    log(this.name, "shipEnteredPlanetaryVicinity(" + planet + ")");
}

this.shipExitedPlanetaryVicinity = function(planet)
{
    log(this.name, "shipExitedPlanetaryVicinity(" + planet + ")");
}

this.shipApproachingPlanetSurface = function(planet)
{
    log(this.name, "shipApproachingPlanetSurface(" + planet + ")");
}

this.shipLeavingPlanetSurface = function(planet)
{
    log(this.name, "shipLeavingPlanetSurface(" + planet + ")");
}

// Combat

this.alertConditionChanged = function(newCondition, oldCondition)
{
    log(this.name, "alertConditionChanged(" + newCondition + ", " + oldCondition + ")");
}

this.playerTargetedMissile = function(missile)
{
    log(this.name, "playerTargetedMissile(" + missile + ")");
}

this.shipAttackedOther = function(other)
{
    log(this.name, "shipAttackedOther(" + other + ")");
}

this.shipAttackedWithMissile = function(missile, whom)
{
    log(this.name, "shipAttackedWithMissile(" + missile + ", " + whom + ")");
}

this.shipBeingAttacked = function(whom)
{
    log(this.name, "shipBeingAttacked(" +  whom + ")");
}

this.shipBeingAttackedByCloaked = function()
{
    log(this.name, "shipBeingAttackedByCloaked()");
}

this.shipKilledOther = function(whom, damageType)
{
    log(this.name, "shipKilledOther(" +  whom + ", " + damageType + ")");
}

this.shipReleasedEquipment = function(mine)
{
    log(this.name, "shipReleasedEquipment(" +  mine  + ")");
}


this.shipTargetDestroyed = function(target)
{
    log(this.name, "shipTargetDestroyed(" +  target  + ")");
}

this.shipDied = function(whom, why)
{
    log(this.name, "shipDied(" +  whom + ", " + why  + ")");
}

this.shipFiredMissile = function(missile, target)
{
    log(this.name, "shipFiredMissile(" +  missile + ", " + target  + ")");
}

this.shipTargetLost = function(target)
{
    log(this.name, "shipTargetLost(" + target  + ")");
}

this.shipTargetCloaked = function()
{
    log(this.name, "shipTargetCloaked()");
}

this.weaponsSystemsToggled = function(state)
{
    log(this.name, "weaponsSystemsToggled(" + state  + ")");
}

// Equipment and Cargo

this.equipmentAdded = function(equipmentKey)
{
    log(this.name, "equipmentAdded(" + equipmentKey  + ")");
}

this.equipmentDamaged = function(equipment)
{
    log(this.name, "equipmentDamaged(" + equipment  + ")");
}

this.equipmentRemoved = function(equipmentKey)
{
    log(this.name, "equipmentRemoved(" + equipmentKey  + ")");
}

this.equipmentRepaired = function(equipment)
{
    log(this.name, "equipmentRepaired(" + equipment  + ")");
}

this.playerBoughtCargo = function(commodity, units, price)
{
    log(this.name, "playerBoughtCargo(" + commodity + ", " + units + ", " + price + ")");
}

this.playerBoughtEquipment = function(equipment, paid)
{
    log(this.name, "playerBoughtEquipment(" + equipment + ", " + paid + ")");
}

this.playerBoughtNewShip = function(ship, price)
{
    log(this.name, "playerBoughtNewShip(" + ship + ", " + price + ")");
}

this.playerChangedPrimedEquipment = function(equipmentKey)
{
    log(this.name, "playerChangedPrimedEquipment(" + equipmentKey + ")");
}

this.playerReplacedShip = function(ship)
{
    log(this.name, "playerReplacedShip(" + ship + ")");
}

this.playerSoldCargo = function(commodity, units, price)
{
    log(this.name, "playerSoldCargo(" + commodity + ", " + units + ", " + price + ")");
}

this.shipScoopedFuel = function()
{
    log(this.name, "shipScoopedFuel()");
}

this.shipScoopedOther = function(whom)
{
    log(this.name, "shipScoopedOther(" + whom + ")");
}

this.playerWillBuyNewShip = function(dataKey, shipyard, price, tradeIn)
{
    log(this.name, "playerWillBuyNewShip(" + dataKey + ", " + shipyard + ", " + price + ", " + tradeIn + ")");
}

this.playerWillReplaceShip = function(dataKey)
{
    log(this.name, "playerWillReplaceShip(" + dataKey + ")");
}

// Other

this.chartHightlightModeChanged = function(newMode)
{
    log(this.name, "chartHightlightModeChanged(" + newMode + ")");
}

this.compassTargetChanged = function(whom, mode)
{
    log(this.name, "compassTargetChanged(" + whom + ", " + mode + ")");
}

this.dayChanged = function(newday)
{
    log(this.name, "dayChanged(" + newday + ")");
}

this.escapePodSequenceOver = function() 
{
    log(this.name, "escapePodSequenceOver()");
}

this.guiScreenChanged = function(to, from)
{
    log(this.name, "guiScreenChanged(" + to + ", " + from + ")");
}

this.guiScreenWillChange = function(to, from)
{
    log(this.name, "guiScreenWillChange(" + to + ", " + from + ")");
}

this.infoSystemChanged = function(to, from)
{
    log(this.name, "infoSystemChanged(" + to + ", " + from + ")");
}

this.infoSystemWillChange = function(to, from)
{
    log(this.name, "infoSystemWillChange(" + to + ", " + from + ")");
}

this.mfdKeyChanged = function(activeMFD, mfdKey)
{
    log(this.name, "mfdKeyChanged(" + activeMFD + ", " + mfdKey + ")");
}

this.missionChoiceWasReset= function()
{
    log(this.name, "missionChoiceWasReset()");
}

this.missionScreenEnded = function()
{
    log(this.name, "missionScreenEnded()");
}

this.missionScreenOpportunity= function()
{
    log(this.name, "missionScreenOpportunity()");
}

this.reportScreenEnded = function()
{
    log(this.name, "reportScreenEnded()");
}

this.selectedMFDChanged = function(activeMFD)
{
    log(this.name, "selectedMFDChanged(" + activeMFD + ")");
}

this.shipCollided = function(otherShip)
{
    log(this.name, "shipCollided(" + otherShip + ")");
}

this.shipSpawned = function(ship)
{
    log(this.name, "shipSpawned(" + ship + ")");
}

this.shipLaunchedEscapePod = function(escapepod)
{
    log(this.name, "shipLaunchedEscapePod(" + escapepod + ")");
}


this.systemInformationChanged = function(galaxy,system,key,newValue)
{
    log(this.name, "systemInformationChanged(" + galaxy + ", " + system + ", " + key + ", " + newValue + ")");
}

this.viewDirectionChanged = function(viewString)
{
    log(this.name, "viewDirectionChanged(" + viewString + ")");
}

AppleMacs

... Strict semicolon parsing is a Mac thing. Windows and Linux use GNUstep to parse plists and that apparently is more relaxed syntax-wise than whatever it is that the Mac uses. Another_commander from A possible solution? (2018).

See Also

• Understanding JavaScript, maybe (Jens Ayton, 2011) An essay on how Oolite's Javascript works
• Mozilla JavaScript reference pages
• Oolite JavaScript event handler reference
• Oolite JavaScript object model
• Variables in Oolite JavaScripts
• Javascript Operators
• Handling OXP Dependencies with JavaScript
• Optimization tips

History

• Anyone want to write scripts using JavaScript? (Dajt, 2007)

Updating Javascript/Spidermonkey

• Issues with updating (2021)