Difference between revisions of "OXP howto"

From Elite Wiki
(Config)
(Tutorials for Tools: replace deadlinks w WBMarchives)
(27 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
:''Shortcut: EW:OXP and EW:HOWDS redirect here''</br>
 
[[Image:oolite-oxp-icon.png|100px|right|OXP icon]]
 
[[Image:oolite-oxp-icon.png|100px|right|OXP icon]]
 
==Overview==
 
==Overview==
An '''Oolite Expansion Pack''' can cause many big changes or additions to Oolite's gameplay, or it may represent just a small, subtle alteration. By first appearances, there is no way to tell what is inside, as it's merely a folder with the added extension '''.oxp''', or in 1.79 onwards a compressed file in ZIP format with extension '''.oxz'''.  
+
An '''Oolite Expansion Pack''' can cause many big changes or additions to Oolite's gameplay, or it may represent just a small, subtle alteration. By first appearances, there is no way to tell what is inside, as it's merely a folder with the added extension '''.oxp'''.
 +
Oolite Version 1.79 onwards supports also compressed files in ZIP format with extension '''.oxz'''.  
  
==OXZ==
+
To learn starting with a non-compressed version have a look at [[OXP_tutorial]].
The new OXZ distribution format is strongly recommended. To make an OXZ file, use a ZIP program to compress the contents of the OXP folder, so that the [[manifest.plist]] file is in the root of the ZIP file, and the folders (AI, Config, etc) are folders in the ZIP file. Then, rename the ZIP file so that its extension is '''.oxz'''. To inspect an OXZ file, open it with your ZIP program.
+
 
 +
{{QuoteText|Text=It's worth saying I think that compared with a lot of game addon architectures, the OXP architecture as designed by Giles is already very good at avoiding conflicts compared with a lot of other games
 +
- you can save your game, add, remove and upgrade lots of OXPs, load your game, and have it work
 +
- you can do this repeatedly, while incrementally upgrading the core game, for years
 +
- as a player you basically never have to care about load order; as an OXP developer, rarely
 +
 
 +
It's also worth noting that a lot of types of OXP conflicts are inevitable due to resource conflicts - a planet can only have one diffuse map, a ship can only have one AI - or due to conceptual conflicts - OXP A removes all stations from a system; OXP B expects the player to dock there.|Source=([http://aegidian.org/bb/viewtopic.php?p=241733#p241733 Cim (3rd Lead Developer)])}}
 +
 
 +
== OXZ ==
 +
The new OXZ distribution format is strongly recommended. It makes version control and distribution just so much easier.
 +
 
 +
To make an OXZ file, use a ZIP program to compress the contents of the OXP folder, so that the [[manifest.plist]] file is in the root of the ZIP file, and the folders (AI, Config, etc) are folders in the ZIP file. Then, rename the ZIP file so that its extension is '''.oxz'''. To inspect an OXZ file, open it with your ZIP program.
  
 
Here is a sample: [[Media:X.0.1.oxz]] - just rename all "X" within to the title of your idea and put your name into the author fields.  
 
Here is a sample: [[Media:X.0.1.oxz]] - just rename all "X" within to the title of your idea and put your name into the author fields.  
Line 11: Line 24:
  
 
For more details read [http://aegidian.org/bb/viewtopic.php?f=4&t=16688 The All-in-One Guide to OXZ Packaging and Distribution].
 
For more details read [http://aegidian.org/bb/viewtopic.php?f=4&t=16688 The All-in-One Guide to OXZ Packaging and Distribution].
 +
 +
=== Creating an .oxz on an AppleMac ===
 +
When you compress the files/folders on the AppleMac to create the .oxz ''do not'' select them with your mouse! This way lies misery!
 +
 +
Rather, ensure the relevant files/folders are inside one overall folder. Then, use '''command-a''' to select all the ''contents'' of this overall folder and then select '''compress''' from the file menu on the finder's menu bar. Finally, rename your newly-created .zip file as an .oxz
  
 
==Structure==
 
==Structure==
Line 70: Line 88:
 
* ''[[scenarios.plist]]'' lists the starting scenarios in the Scenarios folder (v1.79).
 
* ''[[scenarios.plist]]'' lists the starting scenarios in the Scenarios folder (v1.79).
 
* ''[[screenbackgrounds.plist]]'' that contains references to background images (v1.74).
 
* ''[[screenbackgrounds.plist]]'' that contains references to background images (v1.74).
* ''[[Scripting Oolite with JavaScript|script.js]]'' is the equivalent of script.plist in JavaScript. It will be loaded in preference to script.plist if both exist and offers more flexibility and improved possibilities.
+
* ''[[Scripting Oolite with JavaScript|script.js]]'' is the successor of [[script.plist]] in JavaScript. It will be loaded in preference to script.plist if both exist and offers more flexibility and improved possibilities.
 
* ''[[shipdata.plist]]'' that introduces any new entity (ships, stations, objects etc.) to Oolite.
 
* ''[[shipdata.plist]]'' that introduces any new entity (ships, stations, objects etc.) to Oolite.
 
* ''[[shipdata-overrides.plist]]'' that selectively can replace shipentries in other shipdata.plists
 
* ''[[shipdata-overrides.plist]]'' that selectively can replace shipentries in other shipdata.plists
Line 86: Line 104:
  
 
=== Models===
 
=== Models===
Oolite models need to be in the '''.dat''' format. There are utilities available that convert models made in Wings 3D (.obj) and Meshwork (.mesh) into this. A .dat file can be opened in a plain text editor to view the object's assigned texture names and see that they correspond with the actual file names in the Textures folder. The .dat file must be named exactly as it is referenced in the shipdata ''model'' entry - case sensitive!!!
+
Oolite models need to be in an Oolite specific format using the the '''.dat''' file extension. There are utilities available that convert models made in Wings 3D (.obj) and Meshwork (.mesh) into this. A .dat file can be opened in a plain text editor to view the object's assigned texture names and see that they correspond with the actual file names in the Textures folder. The .dat file must be named exactly as it is referenced in the shipdata ''model'' entry - case sensitive!!!
  
* [[OXP howto model|Making Oolite models]]
+
* [[OXP howto model|Making Oolite models]] - tutorials for Wings3D & Blender, notes on sub-entities, links ''etc''.
* Video: [http://aegidian.org/bb/viewtopic.php?f=4&t=16123 From scratch to Mamba in under an hour]
+
* [http://aegidian.org/bb/viewtopic.php?f=4&t=12165 Model Converter utilities] (2012-17)
 +
* Video: [http://aegidian.org/bb/viewtopic.php?f=4&t=16123 From scratch to Mamba in under an hour] ([[Dertien]], 2013)
  
 
===Scripts===
 
===Scripts===
Line 113: Line 132:
 
==OXP Verifier==
 
==OXP Verifier==
  
Oolite has what amounts to a spell checker for shipdata.plist and other some plists, called the OXP verifier. The verifier detects unknown keys or wrong use of keys etc. It can currently only be invoked from the command line.  
+
Oolite has what amounts to a spell checker for shipdata.plist and some other plists, called the OXP verifier. The verifier detects unknown keys or wrong use of keys etc. It can currently only be invoked from the command line.  
  
 
On Windows or Linux:  
 
On Windows or Linux:  
Line 123: Line 142:
 
'''Oolite.app/Contents/MacOS/Oolite --verify-oxp <path to OXP>'''
 
'''Oolite.app/Contents/MacOS/Oolite --verify-oxp <path to OXP>'''
  
Most mac users will not be familiar to using the command line. Look inside your application folder for a utilities folder. Inside that you will find a program called terminal. Run it to open a terminal window. Now drop the oolite application on that window. That will generate the path to oolite on the command line. Delete the trailing space and paste the following text - including the trailing space- behind it: "/Contents/MacOS/Oolite --verify-oxp ".  Now drop the oxp you want to verify on the window. That will again create the path to the oxp behind the last entry. When you select the window and hit the <return> key, the verification will start. It should now open the console program, showing the results.
+
Most Mac users will not be familiar with using the command line. Look inside your application folder for a '''utilities folder'''. Inside that you will find a program called [https://en.wikipedia.org/wiki/Terminal_(macOS) Terminal]. <br>
 +
Run it to open a terminal window. Now drop the oolite application on that window. That will generate the path to oolite on the command line. Delete the trailing space and paste the following text - including the trailing space- behind it: "/Contents/MacOS/Oolite --verify-oxp ".  Now drop the oxp you want to verify on the window. That will again create the path to the oxp behind the last entry. <br>
 +
When you select the window and hit the <return> key, the verification will start. It should now open the Console program, showing the results. <br>
 +
'''Console''' is a log viewer developed by Apple Inc. and included with macOS, also in the utilities folder. It allows users to search through all of the system's logged messages, and can alert the user when certain types of messages are logged. The Console is generally used for troubleshooting when there is a problem with the computer. MacOS itself, as well as any applications that are used, send a constant stream of messages to the system in the form of log files. The console allows you to read the system logs, help find certain ones, monitor them, and filter their contents.
 +
 
 +
=== BB thread ===
 +
*[http://www.aegidian.org/bb/viewtopic.php?f=8&t=13400 plist Editor Pro for Windows] (2013 - full of relevant Red Herrings)
 +
 
 +
=== Correcting with plutil (Apple Macintosh Terminal utility) ===
 +
Since a very small mistake is enough to stop a .plist from being accepted, it's important to be exact about every letter and sign. The Mac Terminal utility has a very practical tool for catching parser errors. After opening Terminal, simply type plutil, add one space, and drag and drop the plist in question onto the Terminal window. This will cause the 'address' of the plist to be shown. Hit return, and Terminal will reveal whether or not the plist is OK. If it's not, you will be given a clue to what is wrong, and the line number of the error.
  
 
==Unique names==
 
==Unique names==
Line 133: Line 161:
  
 
==Scripting with JavaScript==
 
==Scripting with JavaScript==
Older OXPs (from [[User:Aegidian|Aegidian]]'s day were written in Legacy Script: see [[Methods]]. Modern OXPs are written in JavaScript. Specifically oolite.jsVersion 185, an Oolite specific variant of '''ECMAv5'''. It is the same Spidermonkey version that Firefox 4 shipped with many years ago, but it is a special build for Oolite. This is the version that we have almost always had and it has not changed between versions of the game. It is unlikely to change in the future.
+
Older OXPs (from [[User:Aegidian|Aegidian]]'s day were written in Legacy Script: see [[Methods]]. Modern OXPs are written in JavaScript. Specifically oolite.jsVersion 185, an Oolite specific variant of '''ECMAv5'''. It is the same Spidermonkey version that Firefox 4 shipped with many years ago, but it is a special build for Oolite. This is the version that we have almost always had and it has not changed between versions of the game. [http://aegidian.org/bb/viewtopic.php?p=256623#p256623 It is unlikely to change] in the future.
  
 
JavaScript is the preferred scripting interface for worldScripts and shipScripts. The legacy scripting interface (see [[script.plist]]) still works, but is not supported. See [[Scripting Oolite with JavaScript]] for more information.
 
JavaScript is the preferred scripting interface for worldScripts and shipScripts. The legacy scripting interface (see [[script.plist]]) still works, but is not supported. See [[Scripting Oolite with JavaScript]] for more information.
 +
 +
Note that most of the [[Legacy Scripting]] still works perfectly well (XML & OpenStep)!
  
 
==Hidden settings==
 
==Hidden settings==
Line 141: Line 171:
  
 
== See Also ==
 
== See Also ==
 +
*'''Context''': [http://www.aegidian.org/bb/viewtopic.php?p=275434#p275434 What can OXP's ''not'' change?] (2021)
 +
*It is often helpful to dip one's toes (claws?) in the water by experimenting with tweaking oxp's first: see [[How to tweak OXZ's]]
 +
*[[:Category:Oolite scripting]]
 +
*[[Javascript Operators]]
 +
*[[:Category:Oolite JavaScript Reference‎]]
 +
*[[:Category:Oolite Development]]
 +
*[[User:Montana05|Montana05]] recommends https://www.w3schools.com/js/js_array_sort.asp for better knowledge of the js on Oolite.
 +
*[http://aegidian.org/bb/viewtopic.php?f=4&t=12149 OXP Development Best Practices] (2012-7)
 +
*Some older oxp's are written in [[Legacy Scripting]]
 +
*[https://github.com/OoliteProject/oolite/find/master Github] vanilla game code repository - the resources section at the bottom of the page contains possibly useful parts of vanilla game coding, with occasional annotations.
 
=== Tools ===
 
=== Tools ===
 
*[[List of software]] that is helpful for creating OXPs (eg. editorial packages for javascript or 3D model creators)
 
*[[List of software]] that is helpful for creating OXPs (eg. editorial packages for javascript or 3D model creators)
 
*[[List of Planets used in OXPs]] for planets already used by other OXPs. Helps authors avoid overlapping with or breaking other OXPs.
 
*[[List of Planets used in OXPs]] for planets already used by other OXPs. Helps authors avoid overlapping with or breaking other OXPs.
 
*[[OXP_howto_Game_Balance|OXP howto Game Balance]] to avoid conflicts from accidental gameplay changes.
 
*[[OXP_howto_Game_Balance|OXP howto Game Balance]] to avoid conflicts from accidental gameplay changes.
 +
*[[Long Range Scanner]] is an OXP which allows you to jump around the star system to objects you have placed there - or to jump around within the galaxy. A "cheat" for players, but a useful tool for some OXP designers.
  
 
==== Tutorials for Tools ====
 
==== Tutorials for Tools ====
*[http://oolite.aegidian.org/cyoship/ Oolite Tutorial - Meshwork Shipbuilding (OSX only)]
+
*[https://web.archive.org/web/20050317033938/http://oolite.aegidian.org/cyoship/ Oolite Tutorial - Meshwork Shipbuilding (OSX only)] via WayBack Machine
*[http://oolite.aegidian.org/cyoship2/ Oolite Tutorial - Wings 3D Shipbuilding (Cross-platform)]
+
*[https://web.archive.org/web/20060621211940/http://oolite.aegidian.org/cyoship2/ Oolite Tutorial - Wings 3D Shipbuilding (Cross-platform)] via WayBack Machine
  
 
=== OXP tutorials ===
 
=== OXP tutorials ===
 
Oolite changes affecting different varieties of OXPs happened with v.1.76 (2011), v.1.80 (2014) & v1.82 (2015).
 
Oolite changes affecting different varieties of OXPs happened with v.1.76 (2011), v.1.80 (2014) & v1.82 (2015).
 
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=20937 MasterClass: How to OXP (updating SoThisTC)] by [[User:Spara|Spara]] who teaches computing in Helsinki! (2021)
 
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=20937 MasterClass: How to OXP (updating SoThisTC)] by [[User:Spara|Spara]] who teaches computing in Helsinki! (2021)
*[https://archive.org/details/GettingStartedWithOoliteOXZDevelopment Getting started with OXZ Development] ''An .odt for Open Office'': By Bugbear (2012). 2 example OXPs: a pirate-ridden solar systems warning tool & Witchspace Blockades
+
*[https://archive.org/details/GettingStartedWithOoliteOXZDevelopment Getting started with OXZ Development] ''An .odt for Open Office'': By Bugbear (2012). 2 example OXPs: a pirate-ridden solar systems warning tool & Witchspace Blockades [http://www.aegidian.org/bb/viewtopic.php?f=4&t=17731 BB Thread (2015)]
 
*[[OXP_tutorial|OXP Tutorial]] creating a new spaceship - and then tweaking it in different ways (2007-13)
 
*[[OXP_tutorial|OXP Tutorial]] creating a new spaceship - and then tweaking it in different ways (2007-13)
 
*[[OXP howto dockable stations|Creating a dockable station]] (2009-10)
 
*[[OXP howto dockable stations|Creating a dockable station]] (2009-10)
Line 159: Line 200:
  
 
*[http://aegidian.org/bb/viewtopic.php?f=4&t=18837 OXP Performance] BB thread (mostly 2017-8): improving your OXP (speed, ''etc'')
 
*[http://aegidian.org/bb/viewtopic.php?f=4&t=18837 OXP Performance] BB thread (mostly 2017-8): improving your OXP (speed, ''etc'')
 +
 +
*[https://aegidian.org/bb/viewtopic.php?f=4&t=18284 The bare minimum for a game-recognizable ship OXP] (thread: 2016)
 +
*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=14135 How to make a simple OXP?] (thread: 2013)
  
 
*[[Escape Pod Locator OXP]] has notes on programming on the bottom of the page regarding beacon transmission & location
 
*[[Escape Pod Locator OXP]] has notes on programming on the bottom of the page regarding beacon transmission & location
 +
 +
=== Helpful OXPs for your OXP===
 +
There are a number of OXPs which have been specifically written to allow your OXP to use them:
 +
*[[Library OXP|Library]]: a collection of useful snippets and helpers. Its main purpose is to simplify or unify some common tasks used by OXPers. There are examples of interractions with dynamic maps, music & animation. It also introduces a Personal Assistant Device for the player which can be used for details of people met, medals awarded etc. It also allows configuration of an oxp by the player.
 +
*[[GalCop Missions]] introduces many new pieces of equipment with wide varieties of use (Cargo Stoppers, Ejection Dampers, Range Finders, Solar Radiation Disrupter Missiles, Seismic Resonance Scanners, Patient Transport Modules ''etc''). It can also help with managing missions.
 +
*[[Diplomancy]] can be used to make states of war impact personally on the player
 +
*[[System Data Config]] helps re-organise the F7 screen to squeeze more information onto it
 +
 +
==== Stations ====
 +
*[[HD Backgrounds]] can provide a High Definition screenshot of a station lobby or other such for interaction with the player
 +
*[[BGS]] can help organise a customised docking or launching sequence (see the [[Riredi OXP]] or the [[Kiota Stations]]).
 +
*[[GNN]] can broadcast your news alerts (see how [[Diplomancy]] uses it for war & peace declarations). GNN also contains '''PhraseGen''' which can be used for randomizing text descriptions.
 +
*[[Station Validator]] will remember that a station has been destroyed and stop Oolite automatically replacing it on the next visit to the system
 +
*[[Station Dock Control]] can help interraction with other ships docked at the station
 +
*[[Bulletin Board System]] can help manage interractions at the station as can the [[Email System OXP]]
 +
*[[Ship Storage Helper]] allows storage of the player's ship whilst doing other things (such as flying another ship)
 +
 +
==== In-flight ====
 +
*[[MFD - Broadcast Comms]] can be used for in-flight interaction with NPC's
 +
*[[Bigships]] can be used to help with the AI for massive space ships which cannot dock at orbital stations
 +
*[[Montanas Resource Pack 01]] contains a number of resources for use (treasures, containers, escape/survival equipment)
 +
 +
==== Planet Surfaces ====
 +
*[[Planetfall OXP]] allows landing on the planet (used by [[Feudal States]] for access to the Royal Court, and by [[Astronaut]] for space-jumping)
  
 
=== Packaging and distribution ===
 
=== Packaging and distribution ===
 
*[http://aegidian.org/bb/viewtopic.php?f=4&t=16688 The All-in-One Guide to OXZ Packaging and Distribution].
 
*[http://aegidian.org/bb/viewtopic.php?f=4&t=16688 The All-in-One Guide to OXZ Packaging and Distribution].
 +
::And see [http://aegidian.org/bb/viewtopic.php?p=279034#p279034 this post] for AppleMac issues with the above.
 
*[[OXP Distribution]] The All-in-One Guide to OXP Packaging and Distribution (and [[OXP_standards]] for advice on which ways of doing things are supported and which are not).
 
*[[OXP Distribution]] The All-in-One Guide to OXP Packaging and Distribution (and [[OXP_standards]] for advice on which ways of doing things are supported and which are not).
  

Revision as of 23:35, 17 March 2022

Shortcut: EW:OXP and EW:HOWDS redirect here
OXP icon

Overview

An Oolite Expansion Pack can cause many big changes or additions to Oolite's gameplay, or it may represent just a small, subtle alteration. By first appearances, there is no way to tell what is inside, as it's merely a folder with the added extension .oxp. Oolite Version 1.79 onwards supports also compressed files in ZIP format with extension .oxz.

To learn starting with a non-compressed version have a look at OXP_tutorial.

It's worth saying I think that compared with a lot of game addon architectures, the OXP architecture as designed by Giles is already very good at avoiding conflicts compared with a lot of other games

- you can save your game, add, remove and upgrade lots of OXPs, load your game, and have it work - you can do this repeatedly, while incrementally upgrading the core game, for years - as a player you basically never have to care about load order; as an OXP developer, rarely

It's also worth noting that a lot of types of OXP conflicts are inevitable due to resource conflicts - a planet can only have one diffuse map, a ship can only have one AI - or due to conceptual conflicts - OXP A removes all stations from a system; OXP B expects the player to dock there.

(Cim (3rd Lead Developer))

OXZ

The new OXZ distribution format is strongly recommended. It makes version control and distribution just so much easier.

To make an OXZ file, use a ZIP program to compress the contents of the OXP folder, so that the manifest.plist file is in the root of the ZIP file, and the folders (AI, Config, etc) are folders in the ZIP file. Then, rename the ZIP file so that its extension is .oxz. To inspect an OXZ file, open it with your ZIP program.

Here is a sample: Media:X.0.1.oxz - just rename all "X" within to the title of your idea and put your name into the author fields.

You can use Total Commander or Krusader to edit files within .oxz directly, without unpacking.

For more details read The All-in-One Guide to OXZ Packaging and Distribution.

Creating an .oxz on an AppleMac

When you compress the files/folders on the AppleMac to create the .oxz do not select them with your mouse! This way lies misery!

Rather, ensure the relevant files/folders are inside one overall folder. Then, use command-a to select all the contents of this overall folder and then select compress from the file menu on the finder's menu bar. Finally, rename your newly-created .zip file as an .oxz

Structure

Inside the .oxp folder, or the .oxz file, it will at least contain a folder (Config, AIs, Models, Textures, etc...) that holds scripts, plists or other things like textures or models. It is down to the goal of the OXP, which ways to combine elements to the OXP's contents. To get a feeling for it, simply take a look in other oxps. (If they are in .oxz format, any normal unzip program can inspect their contents - many will even let you edit the contents without having to unzip and rezip the file)

The structure for OXPs:

AddOns (folder)
-.oxp (folder) - Holds requires.plist, manifest.plist and the other folders
--> AIs (folder) - Holds AI plists
--> Config (folder) - Holds all other plists
--> Images (folder) - Holds background images
--> Models (folder) - Holds the .dat files
--> Music (folder) - Surprise - holds music files
--> Scenarios (folder) - Holds new game scenarios (v1.79)
--> Scripts (folder) - Holds scripts (worldScripts and shipScripts)
--> Shaders (folder) - Holds Vertex and Fragment shaders (v1.69)
--> Sounds (folder) - Holds sound files
--> Textures (folder) - Holds models textures

If the OXP is in the uncompressed OXP folder format, the .oxp folder must contain a requires.plist file. If it is in the compressed OXZ single-file format, it must contain a manifest.plist file.

AIs

The folder named AIs contains any AI.plist additions the OXP might use.

In Oolite 1.79 AIs may be written in Javascript using .js files in this folder. A helper library is provided to make writing complex JS AIs simpler.

Config

All plist files except for those introducing new AIs, requires.plist, manifest.plist or info.plist, belong in Config.

In its simplest form, an OXP could contain only a Config with an altering script.plist or planetinfo.plist. An OXP that adds a new ship needs a shipdata.plist entry, and unless it is based entirely on existing Oolite data, would include a model and texture.


This folder contains Property lists such as:

Deprecated:

  • demoships.plist that selects demoships to show on startup (replaced - approximately - by shiplibrary.plist in 1.79 and later)
  • script.plist to handle conditional script actions. (deprecated)
  • script.oos was briefly introduced during 1.70 development but is now deprecated in favour of JS.)

Models

Oolite models need to be in an Oolite specific format using the the .dat file extension. There are utilities available that convert models made in Wings 3D (.obj) and Meshwork (.mesh) into this. A .dat file can be opened in a plain text editor to view the object's assigned texture names and see that they correspond with the actual file names in the Textures folder. The .dat file must be named exactly as it is referenced in the shipdata model entry - case sensitive!!!

Scripts

Scripts are in text format. In this folder you can put both js scripts as well as legacy scripts. New OXPs should only use Javascript here.

Textures

Oolite's textures are in the .png format, usually at a standard 512x512 size, and must be named exactly as they are named in the .dat file.

Viewing a specific texture and / or model in Oolite. "I made one. How do I proof it?"

OXP Verifier

Oolite has what amounts to a spell checker for shipdata.plist and some other plists, called the OXP verifier. The verifier detects unknown keys or wrong use of keys etc. It can currently only be invoked from the command line.

On Windows or Linux: Code: oolite.app/oolite --verify-oxp <path to OXP>

On Mac OS X: Code: Oolite.app/Contents/MacOS/Oolite --verify-oxp <path to OXP>

Most Mac users will not be familiar with using the command line. Look inside your application folder for a utilities folder. Inside that you will find a program called Terminal.
Run it to open a terminal window. Now drop the oolite application on that window. That will generate the path to oolite on the command line. Delete the trailing space and paste the following text - including the trailing space- behind it: "/Contents/MacOS/Oolite --verify-oxp ". Now drop the oxp you want to verify on the window. That will again create the path to the oxp behind the last entry.
When you select the window and hit the <return> key, the verification will start. It should now open the Console program, showing the results.
Console is a log viewer developed by Apple Inc. and included with macOS, also in the utilities folder. It allows users to search through all of the system's logged messages, and can alert the user when certain types of messages are logged. The Console is generally used for troubleshooting when there is a problem with the computer. MacOS itself, as well as any applications that are used, send a constant stream of messages to the system in the form of log files. The console allows you to read the system logs, help find certain ones, monitor them, and filter their contents.

BB thread

Correcting with plutil (Apple Macintosh Terminal utility)

Since a very small mistake is enough to stop a .plist from being accepted, it's important to be exact about every letter and sign. The Mac Terminal utility has a very practical tool for catching parser errors. After opening Terminal, simply type plutil, add one space, and drag and drop the plist in question onto the Terminal window. This will cause the 'address' of the plist to be shown. Hit return, and Terminal will reveal whether or not the plist is OK. If it's not, you will be given a clue to what is wrong, and the line number of the error.

Unique names

On loading the oxps, Oolite will add all files in the AIs, Models, Sound and Scripts folders in one big folder for its own use. That means that all files need unique names or one file will overwrite another with the same name. Files in Textures are not pre-loaded, but when looking for a specific texture Oolite looks in all Texture folders until it finds a texture file with a matching name. If another oxp contains a texture with identical name, Oolite could use that texture.

For the Config folder something similar happens. Here the plists all have the same name, but the content of all oxp plists is loaded per type in one big plist. e.g. all individual shipData.plist go in one big shipData.plist file. And within a single plist, all keys must be unique. When two plists use the same key, the later loading key will overwrite the former.

Generally it is a good habit to precede your chosen filenames and keys with the name of the oxp, or another unique prefix, to make sure the names stay unique and no other oxp will use the same names.

Scripting with JavaScript

Older OXPs (from Aegidian's day were written in Legacy Script: see Methods. Modern OXPs are written in JavaScript. Specifically oolite.jsVersion 185, an Oolite specific variant of ECMAv5. It is the same Spidermonkey version that Firefox 4 shipped with many years ago, but it is a special build for Oolite. This is the version that we have almost always had and it has not changed between versions of the game. It is unlikely to change in the future.

JavaScript is the preferred scripting interface for worldScripts and shipScripts. The legacy scripting interface (see script.plist) still works, but is not supported. See Scripting Oolite with JavaScript for more information.

Note that most of the Legacy Scripting still works perfectly well (XML & OpenStep)!

Hidden settings

There are several Hidden_Settings_in_Oolite that make life for an oxp creator easier. One of them is the setting always-flush-cache. It makes every startup a bit slower, but it prevents Oolite working with cached data instead of your newly changed file. For someone that only does occasional oxp changes it will be enough to flush the cache by holding the shift key when starting Oolite but if you are writing oxps, this is the way to prevent frustrations.

See Also

Tools

  • List of software that is helpful for creating OXPs (eg. editorial packages for javascript or 3D model creators)
  • List of Planets used in OXPs for planets already used by other OXPs. Helps authors avoid overlapping with or breaking other OXPs.
  • OXP howto Game Balance to avoid conflicts from accidental gameplay changes.
  • Long Range Scanner is an OXP which allows you to jump around the star system to objects you have placed there - or to jump around within the galaxy. A "cheat" for players, but a useful tool for some OXP designers.

Tutorials for Tools

OXP tutorials

Oolite changes affecting different varieties of OXPs happened with v.1.76 (2011), v.1.80 (2014) & v1.82 (2015).

  • Escape Pod Locator OXP has notes on programming on the bottom of the page regarding beacon transmission & location

Helpful OXPs for your OXP

There are a number of OXPs which have been specifically written to allow your OXP to use them:

  • Library: a collection of useful snippets and helpers. Its main purpose is to simplify or unify some common tasks used by OXPers. There are examples of interractions with dynamic maps, music & animation. It also introduces a Personal Assistant Device for the player which can be used for details of people met, medals awarded etc. It also allows configuration of an oxp by the player.
  • GalCop Missions introduces many new pieces of equipment with wide varieties of use (Cargo Stoppers, Ejection Dampers, Range Finders, Solar Radiation Disrupter Missiles, Seismic Resonance Scanners, Patient Transport Modules etc). It can also help with managing missions.
  • Diplomancy can be used to make states of war impact personally on the player
  • System Data Config helps re-organise the F7 screen to squeeze more information onto it

Stations

  • HD Backgrounds can provide a High Definition screenshot of a station lobby or other such for interaction with the player
  • BGS can help organise a customised docking or launching sequence (see the Riredi OXP or the Kiota Stations).
  • GNN can broadcast your news alerts (see how Diplomancy uses it for war & peace declarations). GNN also contains PhraseGen which can be used for randomizing text descriptions.
  • Station Validator will remember that a station has been destroyed and stop Oolite automatically replacing it on the next visit to the system
  • Station Dock Control can help interraction with other ships docked at the station
  • Bulletin Board System can help manage interractions at the station as can the Email System OXP
  • Ship Storage Helper allows storage of the player's ship whilst doing other things (such as flying another ship)

In-flight

  • MFD - Broadcast Comms can be used for in-flight interaction with NPC's
  • Bigships can be used to help with the AI for massive space ships which cannot dock at orbital stations
  • Montanas Resource Pack 01 contains a number of resources for use (treasures, containers, escape/survival equipment)

Planet Surfaces

Packaging and distribution

And see this post for AppleMac issues with the above.
  • OXP Distribution The All-in-One Guide to OXP Packaging and Distribution (and OXP_standards for advice on which ways of doing things are supported and which are not).
  • Gameplay Balance Indicator and Difficulty Indicator. Add these to your wiki page to show effects on Game Balance and the Difficulty Level of your OXP/OXZ. The first indicates the impact on play (equipment making the game easier/more difficult), the second indicates the suggested Elite Rating needed to attempt the mission/defeat the ship etc.