Oolite Bulletins

 OXP standards Guide

 Oolite Wiki

1. Send a PM to cim, requesting a username and password for administering your OXZs at the oolite.org website. On the Oolite Expansion Packs page, there is a link titled "upload your manifest files", which you use to log in.
2. Send a PM to maik, requesting a username and password for the Oolite Wiki. You will need this for uploading your finished OXZ to the wiki, and (if you wish) creating a wiki-page with information about your Expansion Pack.
   
   • (It's best to get these two steps taken care of early, so that while you're waiting for your logins to arrive, you can continue with repackaging your OXP)
3. Create a  manifest.plist for your OXZ. Once you have a login from cim, there will be a "New Manifest" tool available to you at oolite.org. Not only do you use it to submit manifests, you can use it to generate a draft manifest.plist for your project. However, while you're waiting for your login details, you can use the following code as a template to create the internal copy of the manifest. Once done, save it with the filename manifest.plist and place it inside your myoxpproject.oxp folder. Note that "identifier" is a "set once" item. In other words, the oxp-name you put here should be generic, and not include a version number. Putting anything version-specific in the identifier will only lead to problems and confusion later.
   

   Code: Select all

   {
   	"identifier" = "oolite.oxp.author-name.oxp-name";
   	"required_oolite_version" = "1.80";
   	"title" = "My OXP";
   	"version" = "1.0";
   	"category" = "Choose one of the following - Activities Ambience Dockables Equipment HUDs Mechanics Missions Retextures Ships Systems Weapons Misc";
   	"description" = "A short description of your OXP goes here. This is also a good place to put a note about any dependencies or conflicts, since while the Expansion Manager will tell the user there are dependencies or conflicts, it won't specify exactly what they are.";
   	"author" = "Your Name";
   	"file_size" = "xxxxxxx (not needed for INTERNAL version. Size is in BYTES, with NO COMMAS)";
   	"information_url" = "Link to wiki page or Oolite BB thread goes here";
   	"license" = "CC-BY-NC-SA 4.0";
   }

4. Open your myoxpproject.oxp folder, so that you are viewing the contents of that folder. It is very important that you are not viewing the myoxpproject.oxp folder itself. Now select all the contents, including the manifest.plist you just made, and zip them up, so that you have a file named myoxpproject.zip.
5. Rename this file, changing the .zip extension to .oxz, so that you have: myoxpproject.oxz
6. Test that the OXZ you just made actually works. Remove the myoxpproject.oxp folder from AddOns, and replace it with the myoxpproject.oxz. Start Oolite up and confirm that everything is working as intended. If it's not loading, you most likely made a mistake with the manifest.plist or the zipping process.
7. Now you need to upload your OXZ to the Wiki. Before you do so, though, you should give some thought as to how you name the uploaded file. Essentially, it comes down to deciding whether or not to include the version number as part of the filename. If you include a version number, you'll be able to track the number of downloads of each version separately, whereas if you don't include a version number, and use a more general name instead, download totals can be tracked cumulatively. (See the notes at the end of this Guide for details about tracking download counts.) It really comes down to your personal preference, but is worth giving some consideration to, since, if you have a lot of OXZs uploaded and then change your mind, switching everything over to the other system will be quite a bit of work. There is a thread discussing these points here, which you may wish to read as well.
8. To upload your OXZ, you'll need the Wiki login details you got from maik. After logging in, you'll see an extra option in the 'Toolbox' on the left-hand side of the wiki, named "Upload file". Click on it, and you'll be taken to a page where you can browse to your OXZ, set a different filename for it if you wish to do so (optional), and add a comment that, later on, will make it easier to remember what you did with that particular version. (also optional). If you've decided to go with a general filename, rather than versioned filenames, the comments are probably the best place to note the version number of individual updates. When you're satisfied, click on the "Upload file" button at the bottom of the page. The page will not update until the file has fully uploaded, so if you have a large OXZ, it may take a while, but don't worry, your browser hasn't crashed.
9. When your OXZ has finished uploading, you'll see something similar to this. Of course, the actual details will pertain to your OXZ, not the one in this example:
   
   
   
   The most important thing of note here, is the actual link to where the OXZ is stored on the Wiki. In the above screenshot, it's been circled in red. You need to right-click this link and copy the link location. Paste it into a text file to ensure you have a copy of this link. It's a good idea to bookmark this page in your browser for later access, as well. You'll notice that you can also upload a new version, or revert to an older version, from here, and if you later create a wiki page for your OXZ, this page will also show what wiki pages link to your file.
   
   Note that the example above shows a versioned filename, so when version 1.5 gets uploaded, it will have a different link than the 1.4 version, and downloads for each will be counted separately. Below is an example of a file with a more general name (i.e. - no version number), which will allow cumulative download totals to be tracked, simply by using the "Upload a new version of this file" link.
   
   If you choose the generic naming system, the download link that the wiki generates always remains the same, i.e. the link will always point to the most current version of the OXZ, and you won't ever again need to edit this detail once entered into the manifest at oolite.org (which will be covered next). Note also that although maik hasn't included version numbers in his comments, he has since concluded that doing so would be a better way to handle things:
   
   
10. Go to http://www.oolite.org/oxps/ and click on the "upload your manifest files" link to log in, using the login you should have received from cim. Once logged in, click on the "New manifest" link. This will open a page where you can create and/or edit the manifest.plist entry that Oolite downloads whenever someone updates their OXZ list.
11. Fill out the information in the form, copy and pasting from your internal version where possible, to avoid mistakes, and adding the additional details as required. The file link you copied (and should have saved) from the wiki goes in the "Download URL" field. For the moment, leave the "Status" set to "Draft". Although it's listed in the "Optional fields" section, providing a file size is considered good manners, as it enables players to know how big your OXZ is, before they start downloading it. Note: The file size must be specified in bytes, not Kb, or Mb, or anything else. Also, there must be no commas in the number.
    
    When done, click the "Update manifest" button at the bottom of the page, after which you will have a copy-and-pasteable version of your manifest.plist displayed at the bottom of the page. The "draft" setting saves a copy on the website for you, but won't publish it to the "official" list of OXZs yet.
12. When you're satisfied that all the details are correct, and you're happy with the descriptions you've entered, change the "Draft" setting to "Active" and click on "Update manifest" once more. Congratulations! Your OXZ is now "live"; if you go to the Expansion Packs page, you'll see that your OXZ is now at the head of the list. If/when you later update your OXZ, you simply have to edit the internal manifest.plist to suit, create and upload the new version of the OXZ, and edit the manifest.plist entry you created at oolite.org, to match.
13. Remove the copy of your OXZ from the AddOns folder, and start Oolite. Now update the OXZ list in Oolite, and you'll see that your new OXZ is available for download. Download your OXZ as a final test that everything is working as expected. If there are any errors, write down the details, and check the Latest.log as well for more information. If you are unable to correct the problem using that information, post the details here at the BB, and someone will be able to help you figure things out.

• No need to shift-restart during development, so you can get quicker from-cache startup the rest of the time.
• Update the version in one place, have it propagate everywhere else.
• Provides a common JS script header.
• Automatically builds well-packaged OXPs and OXZs.

[[Media:myoxpproject.oxz|My OXP in OXZ format]] For Oolite 1.80+ only ({{#downloads:myoxpproject.oxz}} downloads)

Smivs wrote:

(wish this had been around a few weeks ago)

Norby wrote:

A minor thing: I think the 4.0 license is better than 3.0.

Diziet Sma wrote:

what is it that makes 4.0 superior?