The Dark Side

"Modding" or tweaking and writing OXPs - and eventually maybe even tampering with the Vanilla game code if you get to be good enough!

Overview

Sneak a peek at How to tweak OXZ's ... and see where it leads you! One of Aegidian/Giles's desires was to use Oolite to teach people how to code.

Just for shock effect, the older OXPs are written in legacy scripting - either XML or OpenStep. Javascript was slowly introduced after 2006 as an option, and then as the best way of writing OXPs (one can do so much more with it).

Oolite itself (the Vanilla game code, not the oxp's) is currently written in Objective-C (72.5%), C (19%), and JavaScript (7%) with fragments in other stuff.

The Perils of the Dark Side

From the Tales from the spacelanes... thread (2014):

Bugger this game is taking over my life!! The funny thing is that between wings3d, photoshop, reading 500 wiki pages about the JS commands for plists and now thoughts of a cockpit console.. well I realised that its been almost a week since i actually played the game as a game instead of test flying the model I'm trying to get working.. lol  spud42

<chuckles> Smivs

Beware the attraction of the darkside - it will consume you! Cody

And now you know why we call it "The Dark Side".. :twisted: :lol: :mrgreen: Diziet Sma/Dizzy

“Inquisitiveness is the path to the dark side. Inquisitiveness leads to tweaking. Tweaking leads to modelling. Modelling leads to publishing and updating the OXP list...” - Commander Yoda
"Can not run out of time, there is infinite time. You are finite. Oolite is finite. This... is wrong tool. No. No. Not good. No. No. Never use this." - Commander Zathras
:D Commander Ranthe

Understanding what really goes on

So I'm on my way to Erlaza, I decide to fly in along the main route and see what I can pick up along the way and the first thing I meet is a Boa with four escorts. Now it strikes me that if I join them I might see a bit more action but at the same time I wouldn't have to deal with it entirely on my own. Sure enough, within minutes there's a Fer-de-Lance shooting at us.

Erm... did I say us?

I'm a Python in formation with a Boa and four escourts and he's completely ignoring the others and has locked on to me. What's more, when I turn to deal with him, what to the others do? They go on their own sweet way leaving me to deal with him on my own. B*****ds!
 

The Fer-de-Lance suffered the consequences and having picked up the ton of luxuries that he left me in his will, I'm following the Boa back to the space station. I'm wondering whether to rejoin them and give them an energy bomb as a token of thanks for their assistance when one of the escorts breaks formation and heads off at 11 o'clock. The others soon follow and I realise that they are under attack from a Python and a couple of smaller ships.

The next thing I know, the Boa is on the radio asking for help!

Yeah. Right. Count the fingers mate.  ("AndySlater", 2006)

Spoiler (why what happened made sense and how the game programmes it)---->

Pirates use a "scanForNearestMerchantmen" (traders, miners and the player), they then use a "Oddsgood" / "Oddseven" / "Oddsbad" to decide if they attack and who. The pirates are "smart" enough to "know" that a ship with the role "escort" will defend its mother. To put it in plain English:- That fer-de-lance considered attacking all the ships it saw, but it knew that if it attacked the convoy it would have to deal with the the Traders escorts as well as the Trader if it attacked him. When it scanned you, it knew you were without escorts and so chose to attack the easier prey (ie you!).

If he had a few wing-men, he might have decided that his side was well enough equipped to make attacking the convoy (bigger risk but better rewards) worth it! (done with random numbers against an Odds risk)

If he had missed his intended target (you!) and hit the Trader, then the trader would have responded. He consults his own AI to decide how to respond, but having cowardly TraderAI he might have decided to run for the planet rather than returning fire or he might have returned fire on the fer-de-lance. The Escorts would probably have attacked the fer-de-lance (as their AI is pretty brave - Someone attacking our mothership - Get Him, even if Mum runs away!). Had there been some cargo pods lying about the Fer-de-lance would probably not have attacked at all and scooped the free cargo, rather than risk a fight (as his AI also includes a scanForLoot, found = setstate to scooploot). Equally had his hold been full, he would have gone to the Station to sell his ill-gotten gains, as he "knows" that there is no point blowing up a trader if you can't scoop his stuff! (done in code by a simple HOLD_FULL = switchAI to route1traderAI)

Obviously it's Giles's code that does all this, but us players can write AIs that the code will follow. You then assign this to a new ship you have built to make it behave as you want. If you want your ship to be a typical pirate / policeship / miner / escort etc, then you just give it one of the native AIs. Fiddling with Oolite is almost as much fun as playing it!

By LittleBear‎ in Any benefits in flying near/with other ships? (2006) Note that this is all in "Legacy Scripting".

Links

• See The Embrace of the Dark Side in the Applied Theology section on the page for the Church of Giles the Creator
• Forgot to play? Programming vs Playing (2015)
• How many of you OXP authors are programmers? (2016+)

Finding things

Am I the only person who finds the js sections almost impossible to navigate? Is there an index page or something I've missed? (Smivs, 2011)

• Category:Oolite JavaScript Reference
• Category:Oolite scripting
• And Commander McLane's post (taken from here (2011))

Smivs was asking for help:

For an OXP idea I'm working on, I have an asteroid as a sub-entity of a ship - the idea is it's a space wreck and the asteroid has hit the ship at low speed and the ship is now 'crunched' onto the asteroid. So far so good. However I want to be able to salvage stuff from the ship by destroying it. Again so far so good. The problem is that sometimes the asteroid breaks into boulders during this and sometimes it doesn't. I would like to guarantee that the asteroid breaks into about 4-5 boulders every time.
The weird thing is, I tried increasing the 'likely cargo' to 100 to generate boulders on the destruction of the asteroid, and this works very well... except the 100 boulders appear about 10 000Km from the original asteroid.

McLane posted this response:

Try Category:Oolite JavaScript Reference

And for all .plist stuff see Category:Oolite scripting (the JS_reference is the first subcategory of this page). The scripting index page itself is among the subcategories of Category:Oolite.

If you have a look at the first page, the only thing you need to know is which JS object you want to manipulate.

For a boulder it would be a ship, because it is a ship which spawns the boulder. Therefore the reference page you need is Oolite JavaScript Reference: Ship, and indeed that is where you find the "spawn()" method. The hint is in the word you type at the beginning of your command (in this case it is "this.ship.").

If you follow Thargoid's advice, you may consult two pages. As indicated by the word "system." at the beginning of the command, it manipulates the system object. The reference page for that is Oolite JavaScript Reference: System. That is where you find everything about the "addShips()" method. Later you see the word "ship." again, which indicates that "position" is again a property of the ship, so you would search for it on Oolite JavaScript Reference: Ship again. Only that this time you would not find it there. It happens that ship is one of the sub-classes of entity (other sub-classes are for instance sun or planet), and all entities have a position. Therefore you find the "position" property in Oolite_JavaScript_Reference:_Entity.

If you would want to manipulate the player ship, your starting point would be Oolite JavaScript Reference: PlayerShip. However, this covers only all things which are "unique" to a player ship. For all other aspects a player ship is only a sub-class of ship, which is only a sub-class of entity. Therefore you would have to consult one of those pages if you want to manipulate for instance the player ship's "speed" (shared by all ships) or "position" (shared by all entities).

Useful Links

• What "can" be changed without re-compiling? (2010-date) - for what oxp's cannot do see the 2021-2 posts
• Getting Started with Programming by Shamus Young (died June 2022) - a broad introduction to the issues.

Javascript

OpenStep is more manageable for beginners. Javascript less so.

• Oolite Javascript basics - an introductory essay by Massively Locked
• if (player.ship.dockedStation.isMainStation) - major discussion on a single line of code (2012)
• Scripting Oolite with JavaScript - contains a note about what your computer does with the JavaScript, followed by a long essay about Oolite's version of Javascript
• Phkb has a helpful intro to mission.oxp javascript here with a commentary here (2021)

Tools

There are a variety of Tools available - from transmogrifying models into the .dat files needed by Oolite, to model/materials analysers, FrameRate monitors, JSOn compressors, script timers, etc.

• More useful versions of Oolite: Check out the Developer Release of Oolite (bottom of the page) which contains useful tools for developers (but is just a little slower in loading the game).
• List of software
• Guide to Unlisted OXPs - see "Stuff for Programmers" at the bottom of the page
• Library OXP has a couple of useful add-on Tools: Material Finder and DevTools (they seem mostly useful for modelling/texturing)

Reference

• Category:Oolite scripting
• Property list - a good place to start - try tweaking the description.plist in Famous Planets and see if it works when you look at the F7 screen!