Well.. now there is. And even better yet, you've found it!
However, first things first. Since this is possibly your first foray into the "Dark Side" of Oolite, as we call it, it won't hurt to get into some good habits right from the start, yes? Believe me, they will save you no end of hassle down the road. If you're an old hand at making OXPs, you can skip down to the next section.
To begin with, you should read the OXP Development Best Practices thread, here on the BB. It has many useful hints and tips, besides other valuable information.
Also, you should be sure to read the posted
![[EliteWiki]](/images/elitewikismall.png){kind=small}
OXP standards Guide, on the Oolite Wiki. This document is updated as each new version of Oolite is released, and describes the current standards, as well as things that may have changed from earlier versions. If you make sure your project is compliant with this, you're off to a good start.At this point, you may, or may not, need to go back and tweak a few things to make your project compliant with the recommendations.
Next, it is very important that you choose a suitable license for your project. This specifies what others may and may not do with your creation. The "CC-BY-NC-SA 3.0" license has been a common choice for OXPs until now, but you may want to consider using the improved, recently released CC-BY-NC-SA 4.0 version for your work. You should read the Licensing OXPs thread for more information.
If you're still in the process of developing and testing your project, I strongly recommend that you make use of cim's build scripts. They make testing and trouble-shooting a breeze! See the notes at the end of this Guide for details.
Having gotten all that out of the way, you're most likely already sitting there with your project in a
myoxpproject.oxp folder, ready for conversion to an OXZ, to be followed by making it publicly available. Here are the steps you'll need to take, in recommended order:- 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.
- 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)
- 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.plistfor 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 filenamemanifest.plistand place it inside yourmyoxpproject.oxpfolder. 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"; } - Open your
myoxpproject.oxpfolder, so that you are viewing the contents of that folder. It is very important that you are not viewing themyoxpproject.oxpfolder itself. Now select all the contents, including themanifest.plistyou just made, and zip them up, so that you have a file namedmyoxpproject.zip. - Rename this file, changing the
.zipextension to.oxz, so that you have:myoxpproject.oxz - Test that the OXZ you just made actually works. Remove the
myoxpproject.oxpfolder from AddOns, and replace it with themyoxpproject.oxz. Start Oolite up and confirm that everything is working as intended. If it's not loading, you most likely made a mistake with themanifest.plistor the zipping process. - 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.
- 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.
- 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:
- 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.plistentry that Oolite downloads whenever someone updates their OXZ list. - 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 yourmanifest.plistdisplayed 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. - 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.plistto suit, create and upload the new version of the OXZ, and edit themanifest.plistentry you created at oolite.org, to match. - 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.
And that's basically all there is to it..
Some notes:
If you're still developing and testing your project, cim's build scripts can be a big help. Just edit your OXP files, run the build-script, start Oolite and test, repeat until everything works the way it should.
Features include:
- 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.
You can, of course, host your OXZ somewhere other than the wiki if you prefer, but you need to be sure that you can link directly to the file. If the link merely opens a webpage from where you can then download the file, it will not work with the Expansion Pack Manager. Thus, sites like box.com and mediafire are not suitable for this purpose. Also, of course, you will have to work out for yourself how to track the number of downloads your file gets, should you wish to do so.
One advantage to using the wiki to host your OXZ is that, if you make a wiki-page for your project, as well as a direct download link (useful for those who may prefer to manually manage all their Expansion Packs), you can include a download counter right there on the page, for everyone to see. To do this, you will need the Title from the page where your OXZ is uploaded to. In the example pictured above, this is
File:Q-Bomb Detector 1.4.oxz. The word "File" has to be replaced with "Media", so that you would have, using our example, Media:Q-Bomb Detector 1.4.oxz, and then insert this into wiki markup code similar to the following:
Code: Select all
[[Media:myoxpproject.oxz|My OXP in OXZ format]] For Oolite 1.80+ only ({{#downloads:myoxpproject.oxz}} downloads)
