OXP Development Best Practices

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

Moderators: winston, another_commander

User avatar
PhantorGorth
---- E L I T E ----
---- E L I T E ----
Posts: 603
Joined: Wed May 20, 2009 6:48 pm
Location: Somewhere off the top left of Galaxy 1 map

OXP Development Best Practices

Post by PhantorGorth » Sat Jul 14, 2012 11:54 am

This thread is for discussing best practice in scripting and OXP development in general. The aim is that the results of this discussion get migrated to the [EliteWiki] wiki in a clear and central location so that OXP developers have a single resource for:
  • How to layout scripts and plists for easier reading and debugging.
  • Basic dos and don't.
  • Efficient programming techniques.
  • Applying Oolite specific methods that improve OXPs.
  • Creating compatibility between OXPs.
  • Reusing other OXP resources to prevent remaking the wheel.
Hopefully this thread will be made sticky.

Edit: 21/7/12 added from this post:

Additional topics:
  • Correct packing of the OXP. Including documentation and Change Logs files.
  • Version numbering.
  • Licensing & copyrights.
  • Documentation writing.
  • Wiki entries for OXP.
Last edited by PhantorGorth on Sat Jul 21, 2012 12:40 pm, edited 1 time in total.
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
PhantorGorth
---- E L I T E ----
---- E L I T E ----
Posts: 603
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 » Sat Jul 14, 2012 12:01 pm

Well the first thing we have is from this post from Ahruman:
Ahruman wrote: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 $.
Moderator: added documentation link for strict mode
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
SandJ
---- E L I T E ----
---- E L I T E ----
Posts: 1045
Joined: Fri Nov 26, 2010 9:08 pm
Location: Help! I'm stranded down here on Earth!

OXP Development Best Practices – meta

Post by SandJ » Mon Jul 16, 2012 3:48 am

.....
Last edited by SandJ on Mon Jul 16, 2012 7:11 pm, edited 1 time in total.

User avatar
Wildeblood
---- E L I T E ----
---- E L I T E ----
Posts: 2161
Joined: Sat Jun 11, 2011 6:07 am
Location: Western Australia
Contact:

Re: OXP Development Best Practices

Post by Wildeblood » Mon Jul 16, 2012 4:05 am

SandJ wrote:- the don't-use-Notepad issue (which I cannot replicate for some reason)
Probably because it's just a myth. Microsoft adopted unicode with Windows XP - if you're still using Windows 98, go away.
SandJ wrote:- case sensitivity in file names in Linux;
- the fussiness of Macs around ";" usage;
Inferior file-name parsing in non-unix-derived OSes.
Inferior property list parsing in non-Mac OSes.

User avatar
SandJ
---- E L I T E ----
---- E L I T E ----
Posts: 1045
Joined: Fri Nov 26, 2010 9:08 pm
Location: Help! I'm stranded down here on Earth!

Re: OXP Development Best Practices

Post by SandJ » Mon Jul 16, 2012 4:16 am

.....
Last edited by SandJ on Mon Jul 16, 2012 7:07 pm, edited 1 time in total.

User avatar
Wildeblood
---- E L I T E ----
---- E L I T E ----
Posts: 2161
Joined: Sat Jun 11, 2011 6:07 am
Location: Western Australia
Contact:

Re: OXP Development Best Practices

Post by Wildeblood » Mon Jul 16, 2012 4:40 am

SandJ wrote:
Wildeblood wrote:
SandJ wrote:- the don't-use-Notepad issue (which I cannot replicate for some reason)
Probably because it's just a myth. Microsoft adopted unicode with Windows XP - if you're still using Windows 98, go away.
I'm writing this on a PC running Windows ME. Do I have to go away?
No. ME would have been the best OS Microsoft ever made (if not for the glaring omission of unicode). It's bad reputation is very much undeserved, and caused by people who didn't configure it well. Apart from the adoption of unicode it's been downhill ever since.

The Notepad thing really is a myth, based I guess on previous versions of notepad defaulting to using some Microsoft code-page that causes apps expecting UTF-8 to choke.
SandJ wrote:
Wildeblood wrote:
SandJ wrote:- case sensitivity in file names in Linux;
- the fussiness of Macs around ";" usage;
Inferior file-name parsing in non-unix-derived OSes.
Inferior property list parsing in non-Mac OSes.
:lol: If we're going to have a Holy OpSys War, shouldn't we start a new thread forum? :D
I'm not interested in OSes; my point is merely that just because you're in the minority, doesn't mean you're wrong.

Addendum: two of these issues are related - the UTF-8 thing and the MAC parsing of property lists both stem from property lists originally being an XML format, so a .plist file is still supposed to follow the rules of XML even if it's not.

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 » Mon Jul 16, 2012 10:48 am

Can we please not have discussions of operating system and what the Right Thing is here? They contribute nothing.
Wildeblood wrote:Addendum: two of these issues are related - the UTF-8 thing and the MAC parsing of property lists both stem from property lists originally being an XML format, so a .plist file is still supposed to follow the rules of XML even if it's not.
This isn’t true; the OpenStep format, which is based (loosely) on C syntax, predates both XML and Unicode.

The details of what will be accepted in OpenStep format plists varies between GNUstep and different versions of Mac OS X but correct syntax, which works in all cases, is:
  • Arrays are enclosed in parentheses – ( ) – and have commas between items, so there is no comma after the last one.
  • Dictionaries are enclosed in braces – { } – and have semicolons after each pair, including the last one.
This is correctly documented on [EliteWiki] the wiki, although the structure of the article isn’t really very helpful. It would probably be better to split off sections for OpenStep and XML syntax.

User avatar
Pleb
---- E L I T E ----
---- E L I T E ----
Posts: 884
Joined: Sun Apr 29, 2012 2:23 pm
Location: United Kingdom

Re: OXP Development Best Practices – meta

Post by Pleb » Mon Jul 16, 2012 11:11 am

Am I right in thinking that OpenStep is the prefered way of laying out plist files? I have noticed that most OXPs seem to use this "style" of laying out the contents of the file as opposed to the XML "style". I myself have just converted the remaining files in my Taxi Galactica OXP to OpenStep, as well as fixing flaws in the script that were previously pointed out so that it conforms to the stock scripts layout.

User avatar
Smivs
Retired Assassin
Retired Assassin
Posts: 8408
Joined: Tue Feb 09, 2010 11:31 am
Location: Disunited Kingdom
Contact:

Re: OXP Development Best Practices – meta

Post by Smivs » Mon Jul 16, 2012 11:19 am

I believe it is, although I couldn't find mention of this on the wiki when I looked, although it is there somewhere.
Certainly the core plists were all converted to openstep some time ago and I for one much prefer it to XML for many reasons, not least of which are that it's easy to read and therefore to debug, and it's a lot shorter - an openstep plist is half the length of an XML one.
Indeed I feel this thread (and eventual wiki page) should urge those using other OXPs as templates to choose a modern one using openstep over an old XML one. Indeed I even know of at least one ship OXP which uses a mix of both formats - how confusing is that!
Commander Smivs, the friendliest Gourd this side of Riedquat.

User avatar
Eric Walch
Slightly Grand Rear Admiral
Slightly Grand Rear Admiral
Posts: 5536
Joined: Sat Jun 16, 2007 3:48 pm
Location: Netherlands

Re: OXP Development Best Practices – meta

Post by Eric Walch » Mon Jul 16, 2012 11:22 am

Pleb wrote:Am I right in thinking that OpenStep is the prefered way of laying out plist files?
When you have to edit plist with a text editor, it is easier when using openStep. So, I would think that it will be preferable for most users. For Oolite itself it does not matter which type you use. In the past I already removed several XML versions of code from the wiki and I think they should all be converted there, except for the page that deals with the difference between those two.
Only mac users have easy access to plist editors and when using that editor, it really does not matter what you use because, when viewed in the plist-editor, both versions look the same. Advantage of using the plist editor is that you can't make syntax errors :D But, for the sake of window and linux users, save it in openstep format. (save as: 'Text Property List')
Last edited by Eric Walch on Mon Jul 16, 2012 11:27 am, edited 1 time in total.

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 – meta

Post by JensAyton » Mon Jul 16, 2012 11:26 am

I recommend OpenStep format for legibility. However, as a special recommendation, if you do use Property List Editor (or Xcode 4) on Mac OS X, use XML format, because they write invalid OpenStep plists.

User avatar
Eric Walch
Slightly Grand Rear Admiral
Slightly Grand Rear Admiral
Posts: 5536
Joined: Sat Jun 16, 2007 3:48 pm
Location: Netherlands

Re: OXP Development Best Practices – meta

Post by Eric Walch » Mon Jul 16, 2012 11:34 am

Ahruman wrote:However, as a special recommendation, if you do use Property List Editor (or Xcode 4) on Mac OS X, use XML format, because they write invalid OpenStep plists.
That should only affect Mac tiger systems. And I wonder how many there are currently around. Look in Oolites own descriptions.plist at the end of the planet descriptions strings at current trunk line 403. I looked back, that error is there since is was converted from XML. No user complained. Probably they assumed Oolite would not run on tiger.

User avatar
Pleb
---- E L I T E ----
---- E L I T E ----
Posts: 884
Joined: Sun Apr 29, 2012 2:23 pm
Location: United Kingdom

Re: OXP Development Best Practices – meta

Post by Pleb » Mon Jul 16, 2012 11:43 am

Okay thanks people, I assumed this was the case. And as a Windows XP user, I just use notepad++ for all my Oolite scripting, as I find its one of the best text editors available on the platform. Are there any tutorials or guidelines when converting XML to OpenStep? I have successfully converted all of the files in my OXP now, but I had to exclude the Frigate from the Galactic Navy OXP as this was written in XML and I have not been able to convert the flashers into OpenStep format, and without them the ship does not look complete... :(

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 – meta

Post by JensAyton » Mon Jul 16, 2012 11:46 am

Eric Walch wrote:
Ahruman wrote:However, as a special recommendation, if you do use Property List Editor (or Xcode 4) on Mac OS X, use XML format, because they write invalid OpenStep plists.
That should only affect Mac tiger systems. And I wonder how many there are currently around. Look in Oolites own descriptions.plist at the end of the planet descriptions strings at current trunk line 403. I looked back, that error is there since is was converted from XML. No user complained. Probably they assumed Oolite would not run on tiger.
Hah. Well, it doesn’t in trunk. I seem to recall there were complaints. :-) Still, correct syntax is the place to be.

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 – meta

Post by JensAyton » Mon Jul 16, 2012 11:49 am

Pleb wrote:I have successfully converted all of the files in my OXP now, but I had to exclude the Frigate from the Galactic Navy OXP as this was written in XML and I have not been able to convert the flashers into OpenStep format, and without them the ship does not look complete... :(
Unless you’re using modernized subentity declarations, that would look something like <key>subentities</key><array><string>*FLASHER* bla bla</string><string>*FLASHER* bla bla</string></array>. In OpenStepese, that’s subentities = ("*FLASHER* bla bla", "*FLASHER* bla bla");.

Post Reply