OXP howto

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.

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)

Structure

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

In 1.79 a new distribution format OXZ is available and strongly recommended for released OXPs. 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.

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.

• Making Oolite AI

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.

• Oolite PriorityAI Documentation
• Oolite PriorityAI Tutorial

Config

All plist files except for those introducing new AIs, requires.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.

• Making Oolite plists

This folder contains Property lists such as:

• characters.plist that adds non-player characters to Oolite.
• commodities.plist that contains information for each commodity in a market.
• crosshairs.plist that contains the look for your weapons (v1.73).
• customsounds.plist that contains references to ingame used sounds.
• demoships.plist that selects demoships to show on startup (in v1.79 and later demoships are no longer shown at startup - shiplibrary.plist performs a similar but not identical function)
• descriptions.plist that adds vocabulary to Oolite texts.
• effectdata.plist defines custom visual effects (v1.77).
• equipment.plist lists upgrades available from the Shipyard.
• hud.plist and hud-small.plist that allows for changes or a radically new Head-Up Display.
• illegal_goods.plist that contains a list of banned/forbidden items. GalCop has an eye on that.
• keyconfig.plist that allows for changes of the keymapping.
• missiontext.plist contains texts for the mission screens.
• OXPMessages.plist adds warnings to testversions of an oxp.
• pirate-victim-roles.plist that defines which roles should act as traders. (deprecated in v1.79)
• planetinfo.plist that plots system specific changes from the default. May also contain script actions.
• role-categories.plist for specifying groups of roles with similar properties (v1.79)
• scenarios.plist lists the starting scenarios in the Scenarios folder (v1.79).
• screenbackgrounds.plist that contains references to background images (v1.74).
• script.plist to handle conditional script actions. (deprecated)
• script.js is the equivalent 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-overrides.plist that selectively can replace shipentries in other shipdata.plists
• shiplibrary.plist that gives information for the ship description library viewable from the startup screen (v1.79)
• shipyard.plist that introduces new ships available for player purchase.
• shipyard-overrides.plist that selectively can replace shipentries in other shipyard.plists
• speech_pronunciation_guide.plist is another of the other custom methods.
• worldScripts.plist that contains a list of scripts (if more than one worldScript should be used).

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 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!!!

• Making Oolite models
• Video: From scratch to Mamba in under an hour

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.

• Scripting Oolite with Javascript
• Scripting reference

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.

• Making Oolite textures

• Smivs' guide to making Oolite textures

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

• Viewing a Texture or Model

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.

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 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.

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

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.

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

• Gameplay_and_Balance_Indicator and OXP_Levelindicators. Add to your wiki page to show affects on Game Balance, and difficulty level of your OXP/OXZ.
• OXP howto Game Balance to avoid conflicts from accidental gameplay changes.
• OXP Tutorial
• How to create dockable stations
• List of software that is helpful for creating OXPs
• OXP Distribution for best practices on OXP packaging and distribution, and OXP_standards for advice on which ways of doing things are supported and which are not.
• List of Planets used in OXPs for planets already used by OXPs. This is to help authors avoid overlap or breaking other OXPs.

External links

• Oolite Tutorial-Meshwork Shipbuilding
• Oolite Tutorial-Wings 3D Shipbuilding