OXP Development Best Practices

[Smivs]

Ah, yes.
But yours is XML and mine's openstep so it's easier to read

[PhantorGorth]

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

[JensAyton]

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

[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;};
  };

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

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

[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?

[cim]

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.

[spara]

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.

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.

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 .

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

[cim]

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.

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

[Pleb]

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

[Keeper]

Ah, nifty. I can extrapolate what the second screen would look like from there. Cool. Now I can tidy up the HUD. Thanks!

[cim]

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?