[WIP]A beginners guide to modding Oolite game mechanics

Discussion and information relevant to creating special missions, new ships, skins etc.

Moderators: winston, another_commander

Post Reply
User avatar
Bugbear
---- E L I T E ----
---- E L I T E ----
Posts: 408
Joined: Sun Sep 17, 2006 1:30 am

[WIP]A beginners guide to modding Oolite game mechanics

Post by Bugbear » Sat Sep 12, 2015 12:02 pm

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
Commander Bugbear
Cruising chart 5 in a Boa Class Criuser: Quantum Pelican I
Vigilante, trader, gems and precious metals hoarder.
Black Monks bothering performed at no extra charge.

User avatar
Lone_Wolf
---- E L I T E ----
---- E L I T E ----
Posts: 545
Joined: Wed Aug 08, 2007 10:59 pm
Location: Netherlands

Re: [WIP]A beginners guide to modding Oolite game mechanics

Post by Lone_Wolf » Sat Sep 12, 2015 1:21 pm

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.
OS : Arch Linux 64-bit - rolling release

OXPs : My user page

I am subscribed to the threads for my oxps, if you need my attention just post in them or send a pm.

User avatar
spara
---- E L I T E ----
---- E L I T E ----
Posts: 2553
Joined: Wed Aug 15, 2012 4:19 am
Location: Finland

Re: [WIP]A beginners guide to modding Oolite game mechanics

Post by spara » Sat Sep 12, 2015 1:56 pm

Lone_Wolf wrote: 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. :oops: Let me just say: Looking good 8) .
Last edited by spara on Sat Sep 12, 2015 6:08 pm, edited 1 time in total.

User avatar
Norby
---- E L I T E ----
---- E L I T E ----
Posts: 2543
Joined: Mon May 20, 2013 9:53 pm
Location: Budapest, Hungary (Mainly Agricultural Democracy, TL10)
Contact:

Re: [WIP]A beginners guide to modding Oolite game mechanics

Post by Norby » Sat Sep 12, 2015 2:00 pm

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.

User avatar
Diziet Sma
---- E L I T E ----
---- E L I T E ----
Posts: 6310
Joined: Mon Apr 06, 2009 12:20 pm
Location: Aboard the Pitviper S.E. "Blackwidow"

Re: [WIP]A beginners guide to modding Oolite game mechanics

Post by Diziet Sma » Sat Sep 12, 2015 4:32 pm

Lone_Wolf wrote:(windows filenames are NOT case sensitive, 99% of linux filenames are.)
Only 99%? That's news to me..
Most games have some sort of paddling-pool-and-water-wings beginning to ease you in: Oolite takes the rather more Darwinian approach of heaving you straight into the ocean, often with a brick or two in your pockets for luck. ~ Disembodied

User avatar
Bugbear
---- E L I T E ----
---- E L I T E ----
Posts: 408
Joined: Sun Sep 17, 2006 1:30 am

Re: [WIP]A beginners guide to modding Oolite game mechanics

Post by Bugbear » Sun Sep 13, 2015 3:14 am

Lone_Wolf wrote: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.
Lone_Wolf wrote: 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 :-( ).
Lone_Wolf wrote: 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.
Lone_Wolf wrote: 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? :?:
Lone_Wolf wrote: 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!)
Lone_Wolf wrote: 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... :-)
Last edited by Bugbear on Sun Sep 13, 2015 3:50 am, edited 1 time in total.
Commander Bugbear
Cruising chart 5 in a Boa Class Criuser: Quantum Pelican I
Vigilante, trader, gems and precious metals hoarder.
Black Monks bothering performed at no extra charge.

User avatar
Bugbear
---- E L I T E ----
---- E L I T E ----
Posts: 408
Joined: Sun Sep 17, 2006 1:30 am

Re: [WIP]A beginners guide to modding Oolite game mechanics

Post by Bugbear » Sun Sep 13, 2015 3:20 am

spara wrote: And about the howto. A few lines about the debug console would be nice.Never mind about that, I must be blind or something. :oops: Let me just say: Looking good 8) .
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)?
Commander Bugbear
Cruising chart 5 in a Boa Class Criuser: Quantum Pelican I
Vigilante, trader, gems and precious metals hoarder.
Black Monks bothering performed at no extra charge.

popsch
Above Average
Above Average
Posts: 27
Joined: Sun Jan 01, 2006 3:50 pm

Re: [WIP]A beginners guide to modding Oolite game mechanics

Post by popsch » Sun Sep 13, 2015 8:06 am

Bugbear wrote: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
Quite Grand Sub-Admiral
Quite Grand Sub-Admiral
Posts: 5397
Joined: Wed Feb 28, 2007 7:54 am

Re: [WIP]A beginners guide to modding Oolite game mechanics

Post by another_commander » Sun Sep 13, 2015 8:10 am

Bugbear wrote: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.

User avatar
spara
---- E L I T E ----
---- E L I T E ----
Posts: 2553
Joined: Wed Aug 15, 2012 4:19 am
Location: Finland

Re: [WIP]A beginners guide to modding Oolite game mechanics

Post by spara » Sun Sep 13, 2015 8:14 am

Bugbear wrote:
spara wrote: And about the howto. A few lines about the debug console would be nice.Never mind about that, I must be blind or something. :oops: Let me just say: Looking good 8) .
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
Harmless
Harmless
Posts: 1
Joined: Tue May 21, 2019 3:42 am

Re: [WIP]A beginners guide to modding Oolite game mechanics

Post by nokko » Tue May 21, 2019 3:45 am

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

Post Reply