EDIT: This version is outdated. Please go to the latest version, that can hopefully be found here. Thank you.
Plug-in Distribution Guide
What you should do to make your plug available for ALL Nova users
Introduction
So, you've proudly made a plug-in you think is worthy enough for the world to see. You may be tempted to just upload the plug-in file to the Net and that's all. Except it won't work. And even if it does, there are things you must include with your plug-in, such as a ReadMe, and maybe you'd like to put more, such as a manual with pictures, screenshots, etc... And in order for all Nova users, Windows as well as Mac users, to easily obtain your plug-in and the accompanying files, you have to respect some rules, especially regarding file formats.
The ReadMe
All plug-ins should come with a ReadMe. Indeed, by just putting a little text file along, you can answer the questions the user may otherwise mail you if there is no ReadMe, and even that is only one of the purposes of a ReadMe.
First of all, the ReadMe should contain the installation instructions (i.e. move the plug-in to the Nova Plug-ins folder). Indeed, your plug-in will be downloaded by people for which it is the first plug-in. For this reason, always assume you're writing for such a guy. This includes converting instructions for people using the opposite platform, don't forget you're writing for people on both platforms.
It should also state what your plug-in does do (add a new planet, modify one weapon, make a new storyline available), and when it is available (immediately, after a mission has been completed, etc...). This will allow to cut mails telling your plug-in doesn't work, when in fact it works but the user expected stuff there isn't or isn't available where the user expected it.
Very important in a the ReadMe is the contact info: how the user can contact you (you'd usually put your email). This is important as bugs and questions about a plug-in should be brought to the plug-in author. Some people already have a tendancy to contact Ambrosia's tech support about plug-ins, don't make it worse by preventing the user to contact you.
If you know or suspect the user will have unanswered questions when reading the ReadMe or using your plug, don't leave them unsanswered (unless it's on purpose, for instance the culprit is known at the end of the storyline) and put a little list of FAQs in the ReadMe. This way, people won't mail you these questions.
You should also write in the ReadMe if the plug-in is compatible (or not) with other plug-ins. Your plug-in is likely to be compatible with others if it contains very few resources; not likely if there are many. Regardless, you cannot guarantee anything, so that's what you'll have to tell here.
If your plug-in comes with a new intro music, you should know that this file needs to be named "Nova Music" on Mac, and "Nova Music.mp3" on PC. Therefore, your ReadMe will need to tell to add the .mp3 extension if the user is on a PC, or if it's already put, to remove it before installing if the user is on a Mac.
Also, you should state on which platforms your plug-in has been tested (or rather, on which one it hasn't been tested, if any). If your plug-in is small and you tested it entirely yourself, you should tell that "this plug-in has not been tested on <opposite platform>". This is necessary as some features are still non-functional in WinNova while they work on MacNova, and some seemingly minor things have been known to make Nova choke on one platform while it behaves well on the other. Don't tell that it won't work on the opposite platform just because the plug-in has not been tested there (unless you're sure about it, then you should state it in the file description in the add-on files), it would unnecessarily scare people when it usually works without problem.
I know this sounds stupid, but remind the user that his copy of Nova has to be registered in order for him to use plug-ins. Otherwise, you'll probably have to handle people telling your plug-in doesn't work (actually, when finding a plug-in in the plug-ins folder, unregistered Nova gives the user a warning that he cannot use plug-ins, but the user may blame it on you...)
Also, put a list of the files in your plug distribution: this will allow the user to know if files are missing or not, and to know which files are to be moved to the plug-ins folder.
The ReadMe can also contain copyright notices, acknowledgements, some background info, who you are, etc...: any textual info you care to give.
The ReadMe should be as simple as possible. If you wish to put some more complicated things such as a full manual, with images for instance, you should put the manual as a separate file and the ReadMe tell how to open the manual (more on this later).
Then, the ReadMe cannot be put in any text format, for reasons of compatibility. Indeed, some text formats can easily be obtained by one platform but not by the other, and some formats vary with the platform. We determined in a long discussion in the Escape Velocity Developer's Corner that there are only two really cross-platform (i.e. readable as well on Macs and PCs) formats, safely usable for ReadMes: RTF (Rich Text File) and HTML (like the web pages). Notice both allow formatting, but only HTML allows images (and even then, in separate files).
RTF files can easily be created by both TextEdit on MacOSX and WordPad on Windows, and read by SimpleText on MacOS<X (and read by those two above as well, obviously). A ReadMe in RTF must have the .rtf extension, for Windows users to identify the file.
HTML files can be coded yourself (HTML isn't really hard, especially the basic functions, the only ones needed for a ReadMe), or created by some applications, and read by just about any web browser. A ReadMe in HTML must have the .html extension.
Raw text (that usually comes with extension .txt) really shouldn't be used. The reason for this is the character that marks the end-of-line is different on Mac and Windows, making txt files created on Mac have no line returns when opened on Windows, and txt files created on Windows have illegal chars when opened on a Mac. If for any reason you have to make your ReadMe in txt (for instance you cannot do a RTF nor an HTML ReadMe), be warned of this, don't forget the extension .txt, and if you're doing it on a Mac, put at the top of your ReadMe.txt "(Better opened with WordPad on Windows)" (WordPad will go to the next line when there is a Mac end-of-line char, contrary to NotePad, which is the Windows application that will open txt files by default).
Any other text format is strongly discouraged (I'd like to say forbidden, but I don't have any mean of pressure on you, bar from saying you should be ashamed of yourself if you don't abide by these recommandations). If you find a text format you think is usable and cross-platform, tell us about it in the EVDC, and we'll investigate it.
Other files
There are other files you may wish to include with your plug-in to be distributed along with it. But then again cross-platform file formats must be used to ensure compatibility.
You may wish to include a manual, some documentation, or some preambles, like the ones that come with Nova. For such things, Adobe's PDF is indeed a nice format. There are only two drawbacks: first, PDF-creation software is usually not free. Second, it is our experience that not everyone has Acrobat Reader installed, so you should tell in your ReadMe that, in order to obtain the manual/preambles/other-stuff-included-in-PDF, the user has to dowload Acrobat Reader at http://www.adobe.com.../readstep2.html. It's also the reason why the ReadMe cannot be in PDF: if the user does not have Acrobat Reader, he won't be able to know he needs it since he cannot even read the ReadMe, so it's as if there was no ReadMe. But other than these caveats, PDF is cross-platform and does not give any problem. Just don't forget the .pdf extension.
Other stuff that you may wish to include are pictures, screenshots, desktop images, etc..., in short, images. Here, the best formats to use, as we are sure any user can read them, are the web image formats: JPEG, GIF, and PNG, that can be read by any web browser. GIF and PNG are better suited (i.e. make smaller file sizes) for small images with few colors, while JPEG is better for big screenshots with many colors: if you have the choice between them, favor for each image which makes the smallest file size. Put the extension .gif for GIF, .png for PNG, .jpg for JPEG.
If you wish to include short (inferior to 10 seconds) sounds with your plug-in, the best format to use is AIFF: iTunes, QuickTime Player and Windows Media Player (which is saying something as it's a format devised by Apple) can play it, and iTunes can convert sounds to this format. The extension to be given is .aiff. Longer sounds (music, etc...) should rather be in MP3 format, that iTunes can encode in, and just about any self-respecting media player can play MP3s ;). Give them the extension .mp3 obviously.
If you really wish to include movies (indeed, movies can easily be big and push the size of the package that will have to be downloaded), put them in a format QuickTime understands: QuickTime needs to be installed for Nova to run, so everyone downloading your plug will have QuickTime installed. The extension to give is .mov.
Archive/Compress
You now have a bunch of (or at least two) files. Put them in a folder, to begin with. Then, you would like to upload this folder to the Nova add-on files in the Ambrosia web site. But it will only accept a single file, not a group of files nor a folder. How does one solve this? By packaging the whole folder in a single file using an archiving and compression format.
Archiving means you can get one file to contain many files, and even a whole directory structure; this will allow you to keep your plug and the files that are to be distributed along with it together, since people will only be able to download the package, not the individual contents. Compression means the resulting file is smaller (to an extent that depends on the compressed files) than the files it contains; it reduces download times, which is quite important when distributing plugs (the Internet is almost the only way your plug-in will be distributed).
There are a number of archiving and compression formats that exist, but only two are really usable for plug-ins: zip and sit. There is no other compression format reliably cross-platform: Compact pro (.cpt) is long dead, .sitx isn't reliable at all when it hits a PC, and other formats are completely marginal. However, .zip and .sit can be uncompressed by Stuffit Expander (bundled on all Macs for quite some time) on Mac, by Stuffit Expander for Windows, and .zip by any zip utility on Windows. However, some things should be taken care of when zipping/stuffing (compressing in zip/sit, respectively).
If you're on a Mac (if you're not, you can skip the following paragraphs), you may know by now that your plug-in contains all its information in resources. The resources are stored in a part of the file, named the resource fork. The other part of Mac files, empty for plug-ins, is called the data fork. The problem is, the resource fork can only exist in a Mac filesystem: on PCs and other platforms (workstations running UNIX, for instance), files can only have one fork, the data fork. As a consequence, transfer protocols and most compression formats only support the data fork, as it usually contains the relevant data: text, picture, etc... But not for plug-ins, where the data fork is empty and the actual information is in the resource fork. If you attempt to directly zip your plug-in, as the zip compression format does not support the resource fork, it will be trashed, and your plug-in will be an unusable 0 kb file when unzipping the archive (notice this doesn't apply to the .sit compression, that supports resource forks, thus the reason it's so popular on Mac, one just has to stuff and everything Just Works™).
The solution to this is to first MacBinary encode the files containing resource forks (i.e. the plug-in files you edit with your plug editor), then zip everything. MacBinary (that usually comes with the .bin extension) has been invented long ago to transfer Mac files across networks (CompuServe at the time) that didn't support resource forks either. The situation has not changed ever since, and MacBinary is still used to transfer Mac files across foreign means (server running UNIX, PC-formatted floppy, email attachment, or inside a zip archive). Especially, WinNova comes with a converter: this converter will take a plug-in encoded in MacBinary format (as bare plug-ins indeed cannot survive in a PC drive, since files in one cannot contain a resource fork) and turn it to the .rez format which is the PC plug-in format that WinNova can use. If the plug-in has been compressed with .sit, Stuffit Expander for Windows has the means to output the files with a resource fork as a MacBinary encoded file, though this feature is broken in the latest version (at the time of this writing), 8, of Stuffit for Windows. The 7.5 version is the last usable, and Allume is working on restoring this feature. The ReadMe should include converting instructions for PC users (stuff in parentheses is just for you, not to be put in the instructions):
IMPORTANT NOTE: the following instructions are HEAVILY subject to change with the evolution of the situation with Allume. As soon as the mean Allume eventually elects to allow PC people to expand .sit(x) files, while outputting plug-ins as MacBinary encoded files, is known (whether it will be in the next version of WinStuffit, a separate tool, or something else), I will update this, so watch this space. Also, this will allow to use .sitx, since Stuffit 7.5 cannot expand sitx, which makes plug encoded in sitx completely unusable by PC people right now.
"(the following is only to be put if you compressed in .sit) If the plug-in files (whatever happens, they won't have any extension for the PC guy, contrary to the case of binning then zipping where they will have the .bin one) are expanded as 0kb files, reexpand the downloaded < your archive name>.sit with Suffit 7.5, that can be downloaded from any link at http://www.ambrosiasw.com/forums/index.php...opic=86891&st;=0(this is a regularly updated topic with the latest Stuffit 7.5 download links) **, making sure the option to expand files in MacBinary format files is set to "When a file contains a resource fork"
-trash any ".DS_Store" file **(these are hidden Mac files, that become visible on a PC) **
-drag and drop the plug-in file(s), (those with extension .bin/the files (name(s) of your plug-in file(s), as you compressed them, without Nova Music nor any movie though) without extension) **(these are the MacBinary encoded plugs; put the first part if you used .zip, as they will have in this case the extension .bin for a PC user, and the second if you used .sit, as they won't have any extension for PC users in this case) **to the converter supplied with Nova
-delete the resource.map file, and move the outputted .rez file(s) to the Nova Plug-ins directory **(PC users rather speak of directories instead of folders)"
If you need to understand this a little more, check this web page: it's the tutorial that is in the WinNova install, hosted for online viewing; remember this is meant for PC people to use plug-ins that have been meant for Mac people, not everything still applies for your plug if you followed the instructions above (for instance the "4) Open the Read Me file, this is best done in Microsoft Word, or in WordPad - which should display the Macintosh read me file in a more friendly manner than NotePad" does only apply for a .txt ReadMe); also, the resource.map file has been know to crash WinXP, so tell to delete it. Don't forget PC people will only be able to get your ReadMe once they will have uncompressed your archive, it makes very little sense to tell in it "this archive is in .zip format, you need to use a zip utility to uncompress it". However, PC people may expand your .sit archive with the wrong version of Stuffit and get your ReadMe but not the plug-in, it then makes sense to tell to use the 7.5 version of Stuffit.
Therefore, PC users need to obtain plug-ins encoded with MacBinary when unzipping. As for Mac users, Stuffit expander will recursively open archives: when uncompressing a .zip archive and finding a .bin file, it will expand it automatically and the Mac user will obtain your plug, the instructions for Mac users in your ReadMe will just be to move the file(s) to the Plug-ins folder.
So, let's recap. You need to MacBinary encode each plug-in file, then put the MacBinary encoded plugs along with the other files in your plug distribution (ReadMe, manual, etc...), then .zip everything, OR compress the folder in .sit (stuff it). There are two main ways to do the first solution.
The first way is to get DropZip (in the StuffIt Standard package from Allume (formerly Aladdin)), and let it take care of everything for you. Indeed, if in the DropZip preferences, you set the "MacBinary" tab to "Smart" (no more, no less), and dropping your distribution folder to DropZip (hence the name), it will automatically take care of MacBinary encoding the plug-in file(s) for you. Then you can take the zip archive that has been created, and prepare to upload it. However, this comes at a price. Indeed, DropZip is shareware, you can try it for free (it's not crippled in any way), but if you're using it regularly, pay Allume your registration fee.
The second way is to do it by hand using the free binning and zipping tools that have been put together in this package (download will start on click; package is less than one MB). To do this, take each of your plug-in file(s) (except Nova Music and movies, if there are any, these do not rely on resources), and MacBinary encode each of them in turn using the ManBinary encoding tool for your system (Drop MacBinary III if you're on MacOS < X, MacBin Drop if you're using OSX). Then, take the MacBinary-encoded versions of your plug-in file(s), put them in the distribution folder along with the files that are to some with your plug-in (ReadMe, etc...), and drag and drop this folder to the zip compression tool for your system (MacZip Crypt if you're running MacOS < X, Zippist if you're running OSX). Then you can take the created zip archive and prepare it to be uploaded.
It's better to do a last check before uploading your .zip file: whichever way you created it, make a copy and double-click the copy to check that Stuffit expander indeed allows you to have the original package back. if it doesn't, carefully redo the zip archive.
If you elect to compress in .sit, then there is only one way: drag the folder and drop it in DropStuff, found in the StuffIt Standard package. That's all. However, you must take care to set DropStuff to compress in .sit, NOT .sitx (that the latest versions set as default), in the DropStuff preferences. And like DropZip, it's shareware. But this should always work, as there is less a risk of human error than with zipping, just quickly check that the outputted file has the extension .sit and that double-clicking it allows you to get your plug-in distribution folder back.
A few last notes: do not even think of using Panther's (and greater) built-in zip feature to zip your plug-in. If you do this, only OSX users will be able to obtain the plug-in (and even then, Jaguar and below users will have a few problems doing so). This means neither OS9 and below users nor Windows users will be able to obtain your plug-in (the reason for this is Panther uses an odd scheme to keep the resource fork and other such info, and only Panther and the latest version of Stuffit expander, that only runs on OSX, can understand this scheme). Which means it is extremely unfriendly to do so. As for compressing in .sitx, it could have been considered, as there is a Stuffit expander for Windows, and this compression format supports the resource fork (thus the reason it is so popular on Macs, it works everytime without having to worry about anything). But .sitx can be expanded only by the latest versions of Stuffit for Windows, and in these versions the feature that allows files with resource forks (i.e. plug-ins) to be outputted as MacBinary-encoded files (that WinNova users can then feed to the converter) is broken, meaning the resource fork is trashed and plug-ins become unusable 0kb files instead. To use old plug-ins compressed in .sit, WinNova users need to use the 7.5 version of Stuffit, but they can't do it for .sitx files, that Stuffit 7.5 cannot expand, therefore .sitx is prohibited for now (watch this space though, Allume is trying to get the feature back, I'll update this guide as soon as I have news).
If you're on a PC, you may know that the .rez format (your plug-in is in) is specific to WinNova, as MacNova uses another format that cannot exist on PC. Originally at the release of WinNova it was thought plug-in development would be done only on Macs, the issue was only to convert plug-ins in Mac format to PC format, so only a Mac-to-.rez converter has been done, and included with WinNova. But one day, to the complete surprise of everyone, Aprosenf came and said he had been developing a PC plug-in editor for some time in complete secrecy, EVNEW , and was looking for private beta testers. Soon the beta test became public, and now the latest version (at the time of this writing), 1.0.4, is an official release. But EVNEW (and the other PC editors that may come afterwards) creates and edits .rez files, that MacNova users cannot use directly. Fortunately, .rez-to-Mac converters have been developped on the Mac, by third-party people. This means that Mac Nova users can use plug-ins in .rez format, they are not PC-only, but also that none of these two converters come with MacNova, so they have to be known about, found, and downloaded by Mac people willing to use .rez plugs. Therefore, you can .zip your plug package using any of the gazillion of zip compressing utilities out there (first of them all WinZip) without having to fear anything, as even Mac users will be able to obtain your package without problem (Stuffit expander is able to uncompress zip files and has been bundled on all Macs for quite some time). But for Mac users to be able to make any use of the .rez file they will obtain, you NEED to tell in the ReadMe: "for Mac users to be able to use the plug-in, they need to first convert it with "Mac Plug-in Convertor" or "RezConv", that can be downloaded at http://www.ambrosiasw.com/cgi-bin/vftp/sho...onvertor101.sit or http://www.ariossoft...ts/freeware.php, respectively." Do not tell anywhere (as people have been seen doing) "this plug-in is in .rez format, so it is Windows-only": this is completely false. Telling "this plug-in is in .rez format, so Mac people will need to convert it before use" is more friendly, but doesn't help Mac people much...
To recap, you just need to take your distribution folder containing your plug and other files (ReadMe, manual, etc...), and use any zip compression software that exists on PC (first of them WinZip). You could also compress in .sit with Stuffit Standard for Windows, but there is really little point in doing so since .sit simplifies the things for people who compress on a Mac, while there is no real benefit for PC users.
Conversely, if you wished to be really nice to Mac users, you could ask a friend with a Mac (such as one of your testers) to convert your plug using one of these two utilities, then send you back the converted file, first encoded in MacBinary (using one of the tools found in this Mac package; if he sends you back the Mac plug directly, it will have its information trashed and become an unusable 0kb file: remember what I said, the Mac plug-in format cannot exist on PCs), then you put the MacBinary encoded plug-in (that usually has extension .bin) with the files that are to come with it (ReadMe, etc...), and .zip everything. The package you would then make would be exactly the same as a Mac guy (following the zipping instructions regarding Mac guys above) would have done, so the same instructions are to be given in the ReadMe (i.e. "just move plug-in in the plug-in folder if you're on a Mac, and <conversion instructions> if you're on a PC"). To be sure that no one of you two did a mistake, try to obtain your plug from the zip archive, and send it as well to your Mac friend to check he can obtain your plug-in as well.
You may be wondering: there is now even a Mac-to-.rez converter that runs on Macs, doesn't a .rez-to-.bin'ed-Mac-plug (that would make the opposite as the converter included with WinNova) converter that runs on PCs exist, it would save the trouble of asking a Mac guy to convert for me? The sad answer is no, and it is thought to be technically impossible to make such a converter (for reasons that would be too long to develop here).
So to sum it up: either .zip (using any zipping utility) your plug and the files that are to come with it, without forgetting to tell in your ReadMe how Mac users can convert your plug, or ask a Mac user to convert your plug to .bin'ed Mac format, then zip it along with the ReadMe and such, giving in the ReadMe instructions to use (and convert if necessary) the plug for both platforms. At any rate, check that you can obtain your plug from the archive.
Whether you're on a Mac or PC, you may be considering uploading two versions of your plug-in: one for Mac and one for PC. Stop considering it now. Indeed, this would take twice the server space for Ambrosia. Plus, you would have problems with people who downloaded the wrong version, and lastly the two plugs would be ranked separately in popularity and rating, which means a PC user willing to download the most popular plugs may very well find the Mac version but not the PC version, less downloaded.
Uploading
After the checks have been made, you now have a .zip or .sit archive that anyone can use. The place that is still the best to put your plug-in is the Ambrosia add-on files, where you probably downloaded a few plug-ins yourself. At the bottom of the main section, you will find a "submit a file" button. Click it, and you will be able to pick the file to put in the addons files (the .zip/.sit archive of your plug), and write a description for people to decide if they should download your plug-in. However, be aware that at the time of this writing (and probably for some time from this time), pipeline (one of the ATMOS guys) is in charge of the Nova add-on files and enforces a set of rules that you can find in the Nova board, the main one being to put your email address in the description (in case he needs to contact you about something with your submission; you can tell him in the description to delete it before he actually posts it). And files that don't meet these rules are deleted, not put in the Nova add-on files, and a mention (and why it happened) is added to the "files I've deleted log" topic in the Nova board. So, be sure you abide by his rules (at the time of this writing there are still many people who get their file deleted as these rules are new, pipeline having just taken the position from EVula) and reread carefully the description before hitting the "submit file" button, and if your submission gets deleted, check why it has been so and resubmit your file with the problem corrected.
Depending on activity, the turnaround can take a few days. But pretty soon your plug should be available in the Nova add-on files. To make sure there has been no problem, dowload your plug, then try and use it, it should work obviously. Then you can make an announcement of the release of your plug-in in the Nova board, for instance. You can also put your plug archive at some other places, such as your website if you have one. Be on the lookout for people having problems with your plug (they will usually mail them to you or post them on the Nova board): leaving unresolved problems, especially in the wake of an annoucement, can give you bad publicity.
If everything happens well, congratulations, not only you did make a plug you think worthy enough for the world to see, but the world can now see it. Don't forget that you may have to update it as people may find bugs in it, and answer some mail about it, but now you can concentrate on another (maybe bigger) project.
This post has been edited by Zacha Pedro : 20 February 2005 - 01:19 PM