Stock Missions Scripting Layout

[Pleb]

After looking at the script files for the stock missions that come with Oolite, and comparing it to other OXP mission scripts, they appear to be in a very different format. Most OXP missions follow the same style of scripting all following the same sort of template (Galactic Navy, Taxi Galactica, hOoPy Casino, Xeptatl's Sword, etc...). But the stock missions do not follow this style. Is there a reason for this, or should they be perhaps updated to reflect the same style that the rest of us are using for our OXPs?

[Smivs]

I'm not sure what you mean by 'a different format' to be honest.
The core game scripting is fairly basic because the native missions are all short and fairly un-complicated. OXP scripting is (presumably) designed by the author/s to best accomplish the needs of the OXP.
They all use javascript, so the syntax etc will be the same, as will the distinction between eg worldscripts and shipscripts.

[Pleb]

Well in the UPS OXP there is a template/example javascript file that everyone seems to follow when laying out their scripts. Even if sometimes certain functions are renamed they all follow the example provided in this OXP. However, when you compare the stock scripts to this example they are very different, especially in how the mission briefings are offered. I just wondered if there was a reason for this, such as maybe they were written before this exmaple was produced, and perhaps maybe they should be re-written to be layed out in this format? Just seems odd that they are not layed out the same as every other script...

[JensAyton]

After browsing through those examples, I don’t see anything they’re consistently doing differently from the built-in scripts other than bad habits:

• Most of them aren’t using strict mode ("use strict"; at the top of the file). This means slower code and less bug checking.
• Many scripts fail to make use of spacing, comments and consistent indentation to keep the code readable.
• 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 $.

So my preliminary answer is that on the contrary, OXPers should be getting less inspiration from each other and more from the built-in scripts. Are there any particular good habits you’d like to highlight?

[JensAyton]

As for mission screens: the approach used by Hoopy, galnavymain.js and Taxi Galactica is terrible. Hoopy and Galactic Navy do it that way because it used to be necessary. The built-in trumble mission and hofd.js in Galactic Navy do it right. (Galactic Navy also loses points for badly-uniqued file names.)

[Pleb]

• Most of them aren’t using strict mode ("use strict"; at the top of the file). This means slower code and less bug checking.

This is true, but I have obviously misunderstood this command (and perhaps others have also) to mean that this script would still execute if the game is in Script Mode, and I thought that most/all OXPs are disable in Strict Mode? Although to be honest I've never played the game in this way and couldn't honestly say.

• Many scripts fail to make use of spacing, comments and consistent indentation to keep the code readable.

I agree with this, I myself have tried to keep indentation conisitent with my own scripts but admitedly do not comment each line to say what each part of my code does. A bad habit I have picked up from others, for as you said not many people do annote their scripts. However, and this may be because they are the more popular style, I find that the OXP scripts are much more readable and straight forward than the stock ones, but this may be down to getting familiar with the way OXP scripts are laid out.

• 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 was never aware this was a requirement/wish of the Development Team, as again when looking at most (but not all) OXPs, they are not used.

As for mission screens: the approach used by Hoopy, galnavymain.js and Taxi Galactica is terrible. Hoopy and Galactic Navy do it that way because it used to be necessary. The built-in trumble mission and hofd.js in Galactic Navy do it right. (Galactic Navy also loses points for badly-uniqued file names.)

This reaches me to kind of my point - the main reason I didn't originally script Taxi Galactica in Javascript was because when looking at the wiki and the stock missions they did not make a great deal of sense at the time. Later, when coming back to making OXPs, I discovered the example script in UPS and compared it to the majority of other OXP scripts, they all followed this way of scripting and it all started to fit together nicely. The issue would then seem to be the complete opposite of what I originally suggested, and in fact perhaps there should be a standard of which OXP scripts should be written to, perhaps even the same as the way the stock missions are laid out, as opposed to my original suggestion of the stock missions being the scripts that needed changing. The wiki does give an enormous amount of information concerning the commands/functions in Javascript, but does not specify exactly how to lay out scripts. Therefore, as I and many before me have done, people look to the existing OXP scripts for help on how they should lay out their scripts.

[Pleb]

Are there any particular good habits you’d like to highlight?

Lol actually the only good habit is that the majority of OXPs are using this format and therefore make them more readable to those unused to scripting in Javascript, as opposed to the stock ones which as stated before do not follow this style. That isn't necesarilly a good habit, just an observation...

[Eric Walch]

Most of them aren’t using strict mode ("use strict"; at the top of the file). This means slower code and less bug checking.

This is true, but I have obviously misunderstood this command (and perhaps others have also) to mean that this script would still execute if the game is in Script Mode, and I thought that most/all OXPs are disable in Strict Mode? Although to be honest I've never played the game in this way and couldn't honestly say.

The only thing those 'strict' modes have in common is that they have the same name. But, strict in Oolite has nothing to do with strict in JS.

In strict mode you get sooner a warning of a warning of a syntax error by the pre-compiler. From the ecma 5 definitions:

4.2.2 The Strict Variant of ECMAScript
The ECMAScript Language recognizes the possibility that some users of the language may wish to restrict their usage of some features available in the language. They might do so in the interests of security, to avoid what they consider to be error-prone features, to get enhanced error checking, or for other reasons of their choosing. In support of this possibility, ECMAScript defines a strict variant of the language. The strict variant of the language excludes some specific syntactic and semantic features of the regular ECMAScript language and modifies the detailed semantics of some features. The strict variant also specifies additional error conditions that must be reported by throwing error exceptions in situations that are not specified as errors by the non-strict form of the language.

[Smivs]

As a relative newcomer to scripting, I have to agree with much of this.
Some sort of 'good practice' guidlines would be very useful. Even more useful would be some 'example' scripts for common functions. For instance it took me ages to work out the simplest things like how to spawn ships where and how I wanted them! Now, I'm in the situation where I'm starting to be able to help others, but half the time I don't know if I'm giving them good advice or not...just that it works.
I do know enough to realise that producing a set of example/template scripts would be a mammoth task, and is certainly something that would largely be beyond me, so it's an aspirational suggestion rather than a request.
However without such a resource, all we can do is study the existing scripting and draw from it, bad points and all.

[Commander McLane]

Well in the UPS OXP there is a template/example javascript file that everyone seems to follow when laying out their scripts.

Where do you get this idea from? I have never heard of a "template/example" JS file. (I also don't have UPS installed.)

Also, you should perhaps examine some of my OXPs.

Lastly, if you want a "template" to build your own scripts upon, it would be advisable to use an up-to-date OXP (or OXP version), not a script that still contains a lot of ballast from previous incarnations of the Oolite JS scripting engine.

[Pleb]

Where do you get this idea from? I have never heard of a "template/example" JS file. (I also don't have UPS installed.)

I'm currently at work and therefore unable to supply you with the exact the name of the file, but if you download the UPS OXP and look in its script folder there is an example Javascript file in there. I didn't just invent this idea, I know for a fact this is the template I used, along with other OXP scripts, to make my own scripts.

As a relative newcomer to scripting, I have to agree with much of this.
Some sort of 'good practice' guidlines would be very useful. Even more useful would be some 'example' scripts for common functions. For instance it took me ages to work out the simplest things like how to spawn ships where and how I wanted them! Now, I'm in the situation where I'm starting to be able to help others, but half the time I don't know if I'm giving them good advice or not...just that it works.
I do know enough to realise that producing a set of example/template scripts would be a mammoth task, and is certainly something that would largely be beyond me, so it's an aspirational suggestion rather than a request.
However without such a resource, all we can do is study the existing scripting and draw from it, bad points and all.

Agreed, it would be a huge task to do, but without it I feel that people are destined to follow in this pattern as there is not much else to go on. It is all very well for people to state that the OXP scripts are mostly flawed in their layouts, but as a whole they do all follow a certain pattern and without a general example/template to follow they will continue along this trend. I know I'm just as guilty as my own scripts are very flawed and need tweaking/reworking, but I have only taken lead from the majority of other scripts as there is nothing/not much else to reference. Except the stock scripts, which look different to all the other scripts and therefore are much harder to comprehend in my opinion.

[cim]

I was never aware this was a requirement/wish of the Development Team, as again when looking at most (but not all) OXPs, they are not used.

As someone who has a bunch of old OXP code which really needs adapting to this convention before someone tries to learn from it, that particular one is really underdocumented. I'll fix that on the Wiki now.

(Summary reason: what happens if you have this.foo in a script written for 1.76, and Oolite 1.78 defines this.foo as a script event?)

[another_commander]

I would fully recommend that the coding style of the core game scripts be used as reference for OXPs and gets adopted by OXP creators. This is just a matter of personal taste of course, but the core scripts are generally more readable than many of the OXP scripts in circulation and if there has to be one reference, it just makes sense for that reference to be the core game itself.

[Commander McLane]

Where do you get this idea from? I have never heard of a "template/example" JS file. (I also don't have UPS installed.)

I'm currently at work and therefore unable to supply you with the exact the name of the file, but if you download the UPS OXP and look in its script folder there is an example Javascript file in there.

Misunderstanding. I'm not doubting the existence of demoScript.js (I've looked it up in the meantime) in UPS-courier.oxp. I just find your assumption that "everyone seems to follow" this JS-file when laying out their scripts a little bold.

And that's because I never ever even once followed its layout, or used it as a template when writing my own scripts, of which I have written a fair number so far.

If you take the time to study a script of mine—for instance anarchies.js as an example for a rather long script—you will see that if it follows a template, it's that of Oolite's own scripts, which I thought to be the sensible thing to follow when I wrote the OXP (or more precisely, when I converted the script from legacy style into JS).

And I have stuck to that ever since. You can for instance see in the change notes for my OXPs (at the bottom of their readMe's), at which point I have prefixed my custom functions with "$" and begun to add "use strict" (in case of Anarchies.oxp this happened in version 2.5 in March 2011).

[Smivs]

I've never used a template of any kind, and was also unaware of the script in UPS which I have never used or even downloaded.
Pleb, you metioned Xeptatl' Sword amongst others in your first post. All the scripting in that OXP is original, mostly written by Okti, but with much by me. It was written the way it is because that's the way we wrote it, not because of any 'template'.
I wonder if what we are seeing here is the simple fact that scripts tend to have the same 'look' to them simply because they are scripts, the same way the HTML/CSS of a web-page will look very similar to the HTML/CSS of a totally different web-page.
Out of interest, I had a quick scan through some of the 'core' scripts to refresh my memory, and I have to be honest and say I can't see much diffrence in the 'layout' of them to most of the OXP scripts I'm familiar with. Yes, they are well laid out and commented, but I like to think my more recent scripting efforts are as well, and I'm just an amateur who's still learning.
I still need to start using $ for custom functions, and 'use strict' I was unaware of, but I'm trying.