OXP Development Best Practices

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

Moderators: winston, another_commander

User avatar
Smivs
Retired Assassin
Retired Assassin
Posts: 8408
Joined: Tue Feb 09, 2010 11:31 am
Location: Lost in space
Contact:

Re: OXP Development Best Practices

Post by Smivs »

Ah, yes.
But yours is XML and mine's openstep so it's easier to read :P
Commander Smivs, the friendliest Gourd this side of Riedquat.
User avatar
PhantorGorth
---- E L I T E ----
---- E L I T E ----
Posts: 647
Joined: Wed May 20, 2009 6:48 pm
Location: Somewhere off the top left of Galaxy 1 map

Re: OXP Development Best Practices

Post by PhantorGorth »

El Viejo wrote:
PhantorGorth wrote:
... surely that having a folder Name is redundant?
That's how I find many OXPs packaged already - it makes sense to me, but that means zilch!
I have seen that too and thought it odd. With Smivs (my first example) version the Name.oxp folder is there at the top so you can just grab it and drop into the Addons folder on your PC. With the version you mentioned you have to go one level deeper first before dragging and dropping.
Chat and relax with other commanders in the [url=irc://irc.oftc.net/oolite]DS's Seedy Space Bar[/url]. The Coolest Bar in the Eight.

Phantor's OXPs: [EliteWiki] GalCop Rewards and [EliteWiki] Safe Docking
User avatar
JensAyton
Grand Admiral Emeritus
Grand Admiral Emeritus
Posts: 6657
Joined: Sat Apr 02, 2005 2:43 pm
Location: Sweden
Contact:

Re: OXP Development Best Practices

Post by JensAyton »

Ahruman wrote:
  • There are a great deal of custom functions which are not differentiated from callbacks used by the game. Our recommendation is that internal script functions have names beginning with _ or $.
I’d like to clarify this a bit.

Any property Oolite adds to an object, other than the global object and arrays, will have a name beginning with a lowercase letter. Therefore, if you add your own property to any object that Oolite has a direct interest in, it should not start with a lowercase letter. The symbols _ and $ are permitted characters at the start of an identifier which are very obviously not lowercase letters. (A convention I now use, but which isn’t used in the Oolite built-in scripts, is to use $ for custom properties and _ for variables used to hide state in closures, a pattern I’m not going to go into here.)

You could also start your property names with other characters and access them with [] syntax, like this["& what a clever name!"] = 3;. But that would be silly.

There are two other things that can appear in identifiers, digits and uppercase letters. An identifier can’t start with a digit, so that’s out. By convention, identifiers starting with uppercase letters are constructors, functions whose purpose is to set up an object in conjunction with the new operator. The constructors you’re most likely to see in Oolite scripts are Vector3D and Quaternion, as in let v = new Vector3D(1, 0, 0);. These very roughly correspond to classes in other object-oriented languages.

All of Oolite’s constructors are globals, and there’s no reason to expect that to change, so it’s OK for a script to have constructors as properties whose names don’t begin with a _ or $. This isn’t very interesting for most scripts, but could be useful for libraries. For example, a library might export a constructor Frob like so:

Code: Select all

this.name = "ahruman_frobLibrary";

this.Frob = function Frob(x)
{
    // Set up this as a Frob object here.
    Object.defineProperty(this, "x", { get: function () { return x; } });
}

Frob.prototype.plusOne = function plusOne()
{
    return this.x + 1;
}
Which can be used like this:

Code: Select all

this.startUp = function ()
{
    let frobLib = worldScripts["ahruman_frobLibrary"];
    let myFrob = new frobLib.Frob(3);
    log("frobLib.test", myFrob.plusOne());  // Logs 4.
}
User avatar
Lone_Wolf
---- E L I T E ----
---- E L I T E ----
Posts: 546
Joined: Wed Aug 08, 2007 10:59 pm
Location: Netherlands

Re: OXP Development Best Practices

Post by Lone_Wolf »

About the use of _ or $ for internal stuff : is this needed for both properties and functions ?
some examples below, if i understand the convention correctly example #3 is the right one ?

example #1

Code: Select all

this.sc_configuration_both = 0;
this.sc_string2bool = function(setting)
  {
    if ( setting === "true" )
      { return true;}
    else
      { return false;};
  };
code example #2

Code: Select all

this.sc_configuration_both = 0;
this._sc_string2bool = function(setting)
  {
    if ( setting === "true" )
      { return true;}
    else
      { return false;};
  };
code example #3

Code: Select all

this._sc_configuration_both = 0;
this._sc_string2bool = function(setting)
  {
    if ( setting === "true" )
      { return true;}
    else
      { return false;};
  };
OS : Arch Linux 64-bit - rolling release

OXPs : My user page

Retired, reachable at [email protected]
User avatar
cim
Quite Grand Sub-Admiral
Quite Grand Sub-Admiral
Posts: 4072
Joined: Fri Nov 11, 2011 6:19 pm

Re: OXP Development Best Practices

Post by cim »

There's no distinction for these purposes between "a property which holds a function" and "a property which holds a string/number/etc". So, yes, #3 is best.

It's "property which holds a function" which generally needs it more. If we add a new event handler, named the same as one of your non-function properties, then you might get a few Latest.log errors, but that's probably it. If it's named the same as a function property, then it'll call that function at unexpected moments.
User avatar
cim
Quite Grand Sub-Admiral
Quite Grand Sub-Admiral
Posts: 4072
Joined: Fri Nov 11, 2011 6:19 pm

Re: OXP Development Best Practices

Post by cim »

It's not quite the same as development best practice, but this seems a reasonable place to post it: we've put together an [wiki]OXP standards[/wiki] document, which sets out the various changes to the recommended way to do things that have occurred since earlier stable Oolite releases (back to 1.65 in some cases), including a draft standard for the future 1.80 release.

This should hopefully make clearer exactly which bits of Oolite are being kept around solely to avoid breaking old OXPs and should be avoided for new code, and which bits will be receiving future support and enhancement, as well as perhaps giving another chance for veteran OXPers to notice new(ish) features and new OXPers to know which bits they shouldn't be learning out of old OXPs.

Comments are welcome, of course.
User avatar
spara
---- E L I T E ----
---- E L I T E ----
Posts: 2691
Joined: Wed Aug 15, 2012 4:19 am
Location: Finland

Re: OXP Development Best Practices

Post by spara »

Great idea to put some guidelines to the wiki. One question though.

It says:
The use of mission screens in flight is considered obsolete.
I'm using a mission screen in my oxp to show market data of some secondary stations just like the main station market data can be viewed in flight by pressing f8. If the use of mission screen in flight is not preferred, what is the preferred way of doing this?
User avatar
cim
Quite Grand Sub-Admiral
Quite Grand Sub-Admiral
Posts: 4072
Joined: Fri Nov 11, 2011 6:19 pm

Re: OXP Development Best Practices

Post by cim »

spara wrote:
If the use of mission screen in flight is not preferred, what is the preferred way of doing this?
In 1.77.1? Wait until the player docks, then show them. The problem is that there are some fairly irritating bugs with mission screens in flight - try displaying a mission screen while the player is using the docking computer, for an obvious one that's still unfixed (and I think may have been even more serious in earlier versions). On a conceptual level, locking the player out of their flight controls is a potentially serious problem.

(Had we written this document back in the 1.76 days, "zero-polygon" entities for 'floating flashers' would similarly have been marked as unsupported without any supported alternative)

1.79 introduces multi-function displays: between those and primable equipment controls you should be able to display a fair amount of text and give some choice controls. Have a look at the tutorial for an example.
User avatar
spara
---- E L I T E ----
---- E L I T E ----
Posts: 2691
Joined: Wed Aug 15, 2012 4:19 am
Location: Finland

Re: OXP Development Best Practices

Post by spara »

cim wrote:
The problem is that there are some fairly irritating bugs with mission screens in flight...
Thanks, that clarifies it. I suggest mentioning that on the wiki page too.
cim wrote:
On a conceptual level, locking the player out of their flight controls is a potentially serious problem.
On a conceptual level, I would like to be able to extend the in-built f5, f6, f7 and f8 screens so that for example pressing multiple times f8 would rotate through other selected local markets. Just like f5 currently two rotates displays. At the moment the only way I have been able to do anything like that is through a mission screen.
cim wrote:
1.79 introduces multi-function displays: between those and primable equipment controls you should be able to display a fair amount of text and give some choice controls. Have a look at the tutorial for an example.
Oh, there are a lot of goodies waiting in 1.79, haven't been able to make the switch yet. I still constantly find new oxp-wise usable things in 1.77.1 :lol: .
User avatar
Keeper
---- E L I T E ----
---- E L I T E ----
Posts: 273
Joined: Fri Feb 01, 2013 7:44 am
Location: Indian Hills, Nevada, USA

Re: OXP Development Best Practices

Post by Keeper »

Are the new HUD entries working? I'll have to add them to my HUD and work on their sizes/positions if so (assuming there is a way to make them show up already).
User avatar
cim
Quite Grand Sub-Admiral
Quite Grand Sub-Admiral
Posts: 4072
Joined: Fri Nov 11, 2011 6:19 pm

Re: OXP Development Best Practices

Post by cim »

Keeper wrote:
Are the new HUD entries working? I'll have to add them to my HUD and work on their sizes/positions if so (assuming there is a way to make them show up already).
Yes, they're in the nightly builds.
User avatar
Keeper
---- E L I T E ----
---- E L I T E ----
Posts: 273
Joined: Fri Feb 01, 2013 7:44 am
Location: Indian Hills, Nevada, USA

Re: OXP Development Best Practices

Post by Keeper »

Cool. Got the drawPrimedEquipment and drawASCTarget positioned and working in my HUD now. But how can I see the multi-function displays in action? Is there any core element or OXP that uses them yet?

Bug in drawPrimedEquipment: When using n_bars=3, after switching from "None", the top line reads the same as the new primed line, instead of reading "None". Also, n_bars=2 is the same as n_bars=3. Anticipated function was to show primed equipment on upper line and the next queued equipment on a lower line (i.e., like n_bars=3 but without the top "previously selected" line).
User avatar
Pleb
---- E L I T E ----
---- E L I T E ----
Posts: 908
Joined: Sun Apr 29, 2012 2:23 pm
Location: United Kingdom

Re: OXP Development Best Practices

Post by Pleb »

Keeper wrote:
But how can I see the multi-function displays in action? Is there any core element or OXP that uses them yet?
Check out the tutorial scenario :wink:
Desktop PC: CPU: Intel i7-4790K Quad Core 4.4GHz (Turbo-Charged) GPU: Nvidia GeForce GTX 1080Ti RAM: 32GB DDR3

Laptop PC: CPU: Intel i5-10300H Quad Core 4.5GHz (Turbo-Charged) GPU: Nvidia GeForce GTX 1650 RAM: 32GB DDR4
User avatar
Keeper
---- E L I T E ----
---- E L I T E ----
Posts: 273
Joined: Fri Feb 01, 2013 7:44 am
Location: Indian Hills, Nevada, USA

Re: OXP Development Best Practices

Post by Keeper »

Ah, nifty. I can extrapolate what the second screen would look like from there. Cool. Now I can tidy up the HUD. Thanks!
User avatar
cim
Quite Grand Sub-Admiral
Quite Grand Sub-Admiral
Posts: 4072
Joined: Fri Nov 11, 2011 6:19 pm

Re: OXP Development Best Practices

Post by cim »

Keeper wrote:
Bug in drawPrimedEquipment: When using n_bars=3, after switching from "None", the top line reads the same as the new primed line, instead of reading "None". Also, n_bars=2 is the same as n_bars=3. Anticipated function was to show primed equipment on upper line and the next queued equipment on a lower line (i.e., like n_bars=3 but without the top "previously selected" line).
Odd - worked when I last tried it out. How many items of primable equipment do you have installed?
Post Reply