[WIP]A beginners guide to modding Oolite game mechanics

[Bugbear]

Hi everyone,
For a while now, I've been working on rewriting my one and only OXP, and documenting the development process as I go.

You can find the document here. It's a LibreOffice Writer file so it should be readable on whatever OS you are using.

The intent of this is to provide a step-by-step guide for developing OXPs that modify the mechanics of Oolite (I'll leave ship building and graphics-centric OXPs to those that are in the know). I hope that any budding OXP developers out there can have a look at it and take their first tentative steps. Each section is designed to build on the work completed in previous sections.

This is a work in progress. I'm only able to devote a few hours a week to development and documentation. I'll try to put an update out every week or so (RL permitting).

Topics covered so far (these section titles will probably change as work progresses):

1. Dev vs Prod installations
2. Setting up a Dev environment
   1. Installing Notepad++
   2. Install 7zip
   3. Install Oolite to a Dev location
   4. 'always-flush-cache'
3. 'Welcome Mat' OXP deconstruction
4. Implementation of the 'Template Script.JS OXP'
5. Rebuilding the 'Unsafe Systems Warning Tool OXP'
   1. Displaying comms messages during witchspace countdown
   2. First test
   3. Troubleshooting issues encountered
      • No connection to debug console
      • Underpowered ship during testing
6. Appendix
   1. Creating a custom Oolite icon for Windows using GIMP

Of course, any feedback will be welcome.

Cheers,
Cmdr Bugbear

[Lone_Wolf]

Glad to see you back, bugbear.
Your name is listed in many great oxps as author or co-author.

The document is interesting, some comments :

Keep the windows specific parts to a minimum and make clear that most of the document is usable for all 3 platforms oolite runs on .

Add a note about case-sensivity (windows filenames are NOT case sensitive, 99% of linux filenames are.)
Easiest way for windows users to ensure their oxps will run on linux/OSx is to use lowercase filenames only.
Folders should start with a Capital letter though.

give alternatives, for example notepad++ is windows-only but kate offers similar functionality on linux.
7zip is multi-platform, and i think available for all 3 platforms.

XML format is rarely used nowadays, most people prefer the NS style (Next Step ?) .
I think there's a python utility somewhere to convert XML to NS format.

Add a chapter about the oxp-verifier ( run oolite -oxp-verify path-to-oxp-folder ) .
It's very handy to detect syntax errors.

please, get rid of Config/script.js .
Use world-scripts.plist instead, and put all scripts in the Scripts folder.
This will allow all scripts to have a unique name and helps to prevent clashes.

[spara]

please, get rid of Config/script.js .
Use world-scripts.plist instead, and put all scripts in the Scripts folder.
This will allow all scripts to have a unique name and helps to prevent clashes.

Really? Why? How does it prevent clashes? If there's only one script file, I find it much nicer to have a simple script.js in the Config folder than using world-scripts.plist and uniquely named script in Scripts folder. I think this is a matter of taste type of thing.

And about the howto. A few lines about the debug console would be nice.Never mind about that, I must be blind or something. Let me just say: Looking good .

[Norby]

Nice work! I think you should ask a login to the wiki from maik and put your pages into due to this is the main source of all OXP developers.

[Diziet Sma]

(windows filenames are NOT case sensitive, 99% of linux filenames are.)

Only 99%? That's news to me..

[Bugbear]

Glad to see you back, bugbear.
Your name is listed in many great oxps as author or co-author.

Umm...I think you may have me confused with LittleBear. As far as OXP authorship is concerned, I'm myself very much inexperienced, which is why I decided to document my learning process as it will hopefully highlight certain pitfalls that are obvious to the more experienced authors out there.

The document is interesting, some comments :

Keep the windows specific parts to a minimum and make clear that most of the document is usable for all 3 platforms oolite runs on .

Add a note about case-sensivity (windows filenames are NOT case sensitive, 99% of linux filenames are.)
Easiest way for windows users to ensure their oxps will run on linux/OSx is to use lowercase filenames only.
Folders should start with a Capital letter though.

Point taken. Time permitting, I'll put a second section in the 'Setting up a Dev environment' chapter that documents how to do it on a Linux OS. For now, I'll put in a blurb about the importance of testing on Linux in order to cover off the case-sensitivity issue. (I'm running Win8.1 and using VirtualBox to get access to Linux VMs - VM performance is pretty poor ).

give alternatives, for example notepad++ is windows-only but kate offers similar functionality on linux.
7zip is multi-platform, and i think available for all 3 platforms.

I'll have to put this in the 'time-permitting' bucket for now. I use Notepad++ alot at work and its familiarity is why I'm using it for my Oolite dev work.

XML format is rarely used nowadays, most people prefer the NS style (Next Step ?) .
I think there's a python utility somewhere to convert XML to NS format.

Handy to know - this is precisely the sort of noob error that I want to document. Again, I trawl through a lot of XML at work, hence my preference for using it in my config files. What reasons are there for preferring NS over XML?

Add a chapter about the oxp-verifier ( run oolite -oxp-verify path-to-oxp-folder ) .
It's very handy to detect syntax errors.

Good idea. I'll add a section for it. (I'll need to learn how to use it first!)

please, get rid of Config/script.js .
Use world-scripts.plist instead, and put all scripts in the Scripts folder.
This will allow all scripts to have a unique name and helps to prevent clashes.

OK, I'll look into it.
EDIT::Having given this more thought, I can totally see the benefit in the ability to arbitrarily name script files. Time for some rewriting...

[Bugbear]

And about the howto. A few lines about the debug console would be nice.Never mind about that, I must be blind or something. Let me just say: Looking good .

Actually, I want to put an section abut how to use the debug console myself, especially with regards to entering commands. I only discovered the other night that the...

Code: Select all

log( this.name, strMsg );

...command will make 'strMsg' appear in the debug console. Saves one from monitoring Latest.log. So there is much that I need to learn about the debug console.
For example, when testing, is it possible to enter a command that will 'magically' teleport your ship from witchspace beacon to an arbitrary location in system (say just outside main station aegis)?

[popsch]

For example, when testing, is it possible to enter a command that will 'magically' teleport your ship from witchspace beacon to an arbitrary location in system (say just outside main station aegis)?

This is what I use in my OXP to test:

Code: Select all

this.debug = 0;
/** launch from station for testing */
this.shipWillLaunchFromStation = function() {
    if (this.debug != 1) return;
    player.ship.position = system.locationFromCode('OUTER_SYSTEM_OFFPLANE');
    this.$populateSystem(player.ship.position.add([1E4, 1E4, 1E4]));
};

this.$populateSystem = function(pos) {
  // do whatever you want
};

/** have the content appear between the witchpoint and the station */
this.systemWillPopulate = function(station) {
     if (system.scrambledPseudoRandomNumber(clock.seconds) < this.LIKELIHOOD * system.techLevel) {
         system.setPopulator('foo', {
             callback: function(pos) {
                 this.$populateSystem(pos);
             }.bind(this),
             location: 'LANE_WP'
         });
     }
};

[another_commander]

For example, when testing, is it possible to enter a command that will 'magically' teleport your ship from witchspace beacon to an arbitrary location in system (say just outside main station aegis)?

Code: Select all

 PS.position = [x,y,z]

or, for instant teleportation to station aegis,

Code: Select all

PS.position = S.mainStation.position.add([0,0,25000])

where x, y and z are desired position vector coordinates, PS is a console-only shortcut for player.ship and S a console-only shortcut for system.

Edit to add: If you don't feel like typing the above every time, the console allows also macro creation to simplify these things. You can open Basic-debug.oxp/Config/debugConfig.plist, and add the following in the default-macros dictionary:

Code: Select all

"gotoAegis"	= "player.ship.position=system.mainStation.position.add([0,0,25000])";

Now you can type :gotoAegis in the console prompt and teleport to the aegis. Note the : at the start, it is used to denote a macro. Speaking of which, it is really helpful if you are familiar with the rest of the macros in the consolse, they do make life so much easier.

[spara]

And about the howto. A few lines about the debug console would be nice.Never mind about that, I must be blind or something. Let me just say: Looking good .

Actually, I want to put an section abut how to use the debug console myself, especially with regards to entering commands. I only discovered the other night that the...

Code: Select all

log( this.name, strMsg );

...command will make 'strMsg' appear in the debug console. Saves one from monitoring Latest.log. So there is much that I need to learn about the debug console.
For example, when testing, is it possible to enter a command that will 'magically' teleport your ship from witchspace beacon to an arbitrary location in system (say just outside main station aegis)?

First of all, Debug Console is a tool for interactively writing JS commands while the game is running, so I'm not sure how deep into the commands you should go. Maybe just explaining what it is, how it's run, how it works and a couple of examples. Then the reader should take it from there. Log example is a nice and simple one. Then maybe spawning asteroids around you might be nice:

Code: Select all

system.addShips("asteroid", 10)

and maybe teleporting player ship behind the witchpoint:

Code: Select all

PS.position=[0, 0, -10000]

After that, it's up to the reader to work things out.

I would keep it as simple as possible.

[nokko]

Hi! I've uploaded the document to the Internet Archive at this URL.