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.
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 (the conversion instructions depend on your platform and how you will compress your plug-in, so they will be given later in this document; for now, leave a section in your ReadMe to place them).
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, or if you don’t wish to make your email address public, your Ambrosia board information, where an email contact form can be found). 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, so you tested it entirely yourself (a bigger plug-in should have had an even small beta testing, on both platforms), 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 so that people do not waste download time), 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.
Finally, 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).
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 two long discussions 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 and read by both TextEdit on MacOSX and WordPad on Windows; on OS9 one needs AppleWorks, MS Word or a similar program to create and read them, but it appears that almost all OS9 Nova users have such a program. A ReadMe in RTF must have the .rtf extension, for Windows users to identify the file. Notice you shouldn’t try and add an attachment (image) to a RTF ReadMe as the ReadMe won’t work any more for some users.
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) is forbidden. The reason for this is the character that marks the end-of-line is different on Mac, Windows, and UNIX (with TextEdit on OSX following the UNIX convention) making txt files created somewhere have no line returns and/or illegal chars when opened elsewhere, not to mention the default encoding is different too.
Any other text format is forbidden too. 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. In the meantime, don’t use it.
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 preambles, like the ones that come with Nova. For such things, Adobe’s PDF is indeed a nice format, that we recommand for such things: it is really cross-platform and has nice features, and .pdf files are not (that) big. There are only two drawbacks: first, PDF-creation software is usually not free (in fact rather costly). Second, it is our experience that not everyone (especially PC folks) has Adobe 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 Adobe Reader at http://www.adobe.com/products/acrobat/readstep2.html. It’s also the reason why the ReadMe cannot be in PDF: if the user does not have Adobe 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. Oh, and 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.
You now have a bunch of (or at least two) files. Put them in a folder, to begin with. This folder will be the distribution folder, this is what everyone interested in your plug is to be able to obtain. 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 distribution 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). Most archiving formats also compress, and the converse is true as well: most compression formats are also able to archive. Therefore, the process of archiving and compression will simply be referred to as compression, as the format will take care of both at once.
There is only one compression format which is actually usable for Nova plug-ins, since both Mac and PC users are to be able to download and use it: zip. Any other format is completely prohibited. Especially, Panther’s (and later) built-in zip feature (“archive” menu command in the Finder) is prohibited, since it makes zip files with an odd scheme that is not compatible; sitx used to be recommended, but fell out of favor (and is now forbidden) for numerous reasons, chief among them the fact that Stuffit Expander is no longer bundled on Macs and Nova itself no longer requires Stuffit Expander for install since version 1.1.0; .sit, .cpt, .rar, .rpm, .pkg, .dmg/.img, .gzip, .7z, or any other odd format you may know, is prohibited. If you find a compression/archiving format you think is usable and cross-platform, tell us about it in the EVDC, and we’ll investigate it. In the meantime, don’t use it.
Depending on your platform, jump to the relevant sub-section: first, sub-section b, is for PC plug-in designers; second, sub-section c is for Mac plug-in designers.
You may already know that the .rez format (that the plug-in you made 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, so the issue was only to convert plug-ins in Mac format to PC format for the PC users to use these. Therefore, only a Mac-to-.rez converter has been made 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 (Escape Velocity Nova Editor for Windows), 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. EVNEW (and the other PC editors that may come afterwards) creates and edits .rez files which PC plug-in developers can directly test, and that other PC users can use directly; but Mac users cannot use them directly.
Fortunately, .rez-to-Mac converters have been developed on the Mac by third-party people. This means that Mac Nova users CAN use plug-ins in .rez format, including your plug-in, but also that (having been made by third parties and not Ambrosia) none of these two converters come with MacNova, so they have to be known about, found, downloaded, and used by Mac people willing to use your plug-in. This means YOU will have to give them this information (“this plug can be used on Macs, you just need to use this that can be downloaded from there”) in the ReadMe that will come with your plug.
Otherwise, there are very few problems. .zip compression is pretty featureless, in the extent that you should not have any problem creating a .zip archive from your distribution folder. Most, if not all, of your users, will be able to expand the zip archive automatically: Mac users use Stuffit Expander (that will automatically recognise .zip files, and is bundled on all Macs for quite some time) or Mac OS X’s built-in zip expander, and most PC users have a zip decompression utility (WinRar, WinZip, PowerArchiver, or Stuffit Standard) that will take care of decompressing the zip, and they will obtain exactly the distribution folder you compressed; even if they don’t have a zip utility, the most simple search (computer friend, Google search, computer teacher) will point them to a way to unzip it. There’s little way you can help them: they will only be able to read your ReadMe once they’ve already unzipped your distribution folder.
The only problem is to pick the utility with which you will make the .zip archive. I’m not really a specialist for zip compression on the PC side, but I know that WinZip is the most famous of them; other names are PowerArchiver, PKZip, etc... By doing a search, you can find free and Free (open source) ones, and command-line ones if you like. Stuffit Standard also can compress in .zip. I can’t really recommand any of them, for not having actually used any; your choice. Especially, there is no compatibility problem, all of them will produce a .zip archive, usable by everyone, with the same contents.
Enough theory, let’s go to practice.
Firstly, add this in the relevant section of your ReadMe:
“For Mac users to be able to use the .rez plug-in file(s), they need to convert it (them) first with “Mac Plug-in Convertor”, that can be downloaded at http://www.ambrosiasw.com/assets/modules/addonfiles/download.php?addon=2213 (direct download link). Conversion is done by dragging and dropping the .rez file(s) to the converter you downloaded and installed. It should output (a) plug-in file(s) that Nova should recognise.”
(or something similar, don’t hesitate to rephrase if you prefer, English is not my first language)
Do NOT tell (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. Always assume your plug-in will be the first someone will download, so be clear about what the Mac users have to do and where they can find the converters.
Otherwise, plug-in usage is the same on the Mac: the user has to move it to the plug-in folder and launch Nova. Put the plug-in usage in your ReadMe, as always it’s possible it’s the first plug-in the reader has ever downloaded.
Second, assemble the files in your distribution folder, and compress this folder in .zip using the utility you choose. The exact way you do it varies with the utility, it’s either drag-and-drop, or create a new archive/ add folder to archive/ save archive, or the name of the folder is taken at the command-line. It’s best to do a last safety check: once the utility has outputted the .zip file, try double-clicking it (or get it expanded by your favorite method) and check that you can reobtain your distribution folder this way. Once this check is made, the .zip file is suitable for uploading, go to the Uploading section.
You may know by now that your plug-in contains all its data 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 (email, ftp, http, etc...) 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 data is in the resource fork. .zip by default doesn’t maintain the resource fork: to get your plug-in data maintained in the zip compression, each plug-in file has to be encoded before zipping.
The problem is for PC users: how do they get the resource fork of your plug-in, when it cannot actually exist on their machine? It’s the very reason Contraband developed the .rez file format, which is the format of PC plug-ins. It’s a format similar is essence to the resource format, and it is stored in the data fork. A converter to convert Mac plug-ins to the .rez format has been made, and included with Nova on PC. Since bare Mac plug-ins cannot exist as is on PC, this converter takes MacBinary encoded Mac plug-ins for its imput. What is MacBinary? MacBinary is an encoding format, that usually comes with the extension .bin, that has been devised long ago (I mean, 1986) to transfer Mac files and their resource fork across networks (CompuServe at the time) that didn’t support the resource fork, by merging the resource fork and data fork, with a header, in the data fork. It’s still used to transfer Mac files across foreign means (server running UNIX, PC-formatted floppy, email attachment, or inside a zip archive) that do not support the resource fork. Since the converter takes MacBinary encoded plugs for its input (as bare Mac plug-ins cannot exist on a PC drive), PC guys need to be able to obtain MacBinary-encoded versions of your plug-in files.
By encoding each plug-in file in MacBinary, then compressing your distribution folder in .zip, Windows users will be able to obtain them simply by using just about any .zip decompression utility (WinRar, WinZip, PowerArchiver, or Stuffit Standard as well, for instance), and they will obtain exactly the distribution folder you compressed (with the plug-in files still MacBinary-encoded, since they need it); even if they don’t have a zip utility, the most simple search (computer friend, Google search, computer teacher) will point them to a way to unzip it. As for Mac users, Stuffit Expander, bundled on all Macs for quite some time, will take care of expanding the .zip and will recursively expand the MacBinary files inside the archive, that Mac users won’t even see, so they will obtain exactly the distribution folder you compressed (with the plug-in files, in the state they were before they were MacBinary encoded); for more recent Macs where Stuffit Expander was not bundled and thus may not be present, Mac OS X’s built-in archive expander will do the job.
Since your plug-in may be the first the user downloads, you need to tell how to use it in your ReadMe. This includes conversion instructions for PC guys; since you probably don’t know them, I will give them later, in the practice subsection. Also, while using Guy’s Plug-in Archiver is the One Recommended Way, there are two other ways to do a .zip archive as I described: use DropZip, or do it manually. The way you do it will change one or two things, I will tell you when we’ll come to them.
Enough theory, let’s go to practice.
Firstly, add this in the relevant section of your ReadMe:
“PC users should trash any .DS_Store or Icon_ file, and drag and drop the plug-in files (<give here a list of file names, they will have the extension .bin appended to the plug-in names if you used DropZip or Guy’s Plug-in Archiver, or they will have the name of the MacBinary archives when you compressed them if you did it manually>) to the converter supplied with Nova. Then delete any resource.map that may have appeared, and move the .rez files produced by the converter to the “Nova plug-ins” directory.”
(or something to that effect, don’t hesitate to rephrase if you prefer, English is not my first language)
Then, assemble your distribution folder. To do a .zip archive as I described, there are three main ways. Remember that use of Panther’s built-in zipping feature (“Create an archive of...” menu item in the Finder) is completely prohibited. If you need to know the reason for this, it’s because, though the .zip archive thus produced will work well for you and other Panther, Tiger and Leopard users, it won’t work for other OSX users, pre-OSX users, nor Windows users.
The best way is to use the awesome Plugin Archiver, by Guy, which you can get from the Ambrosia Evn add-ons (direct download link). To use it, just drag and drop your distribution folder to the app, and poof, the archive will be created. It’s that simple. On top of that, it ensures custom folder icons will be preserved when expanding; the other methods won’t do that as it requires a pretty clever scheme to have them preserved.
The second way is to use DropZip, found in the Stuffit Standard package from Allume (probably bundled on your Mac, otherwise download it at www.stuffit.com).
Firstly, launch DropZip, and make sure that in the prefs, the MacBinary setting is set to “smart” (no more, no less). Then, drag and drop you distribution folder to the drag and drop target (or file menu->zip and select the folder, or drag and drop it to the DropZip app in the Finder). After compression, you should obtain a .zip file.
Unfortunately, Allume removed this feature starting from Stuffit 9, and replaced it with a new .zip scheme that preserves the resource fork for Mac users, but intentionally only makes the data fork available to the PC users, which obviously isn’t what we want. Try to get version 8 if you can - it may still be available for download since Stuffit 9 and 10 don’t run on OSX 10.2, even if you don’t have 10.2 yourself. If you can’t get 8, then you can’t do it that way, look at the other ways.
The third way is to do it manually, using for instance the free tools found in this package (direct download link). There are four tools, two for encoding in MacBinary (binning), and two for zipping, one of each for pre-OSX and one of each for OSX.
First, take all plug-in files (the files that are to be moved to the plug-in folder, or the Nova Files folder if you’re doing a TC, except in-game movies and the Nova music file if any, that shouldn’t be encoded), and encode them in MacBinary one by one using the binning tool for your system. For each, it should create a file, with the extension .bin, having almost the same size as the original file. You may rename the file if you wish, just don’t forget PC users will see the file with this name. Then, reassemble your distribution folder, replacing the plug-in files by the MacBinary archives you just created, and use the zipping tool for your system to compress this new distribution folder. After compression, you should obtain a .zip file.
It’s best to do a last safety check: try double-clicking the archive you created and check that you can reobtain your distribution folder this way; especially, check that you don’t obtain any 0kb file, which would mean you forgot to encode this particular file in MacBinary before zipping. Notice Stuffit Expander will automatically take care of deencoding the MacBinary files that it found when expanding the zip archive, so you (and all other Mac users) will obtain the distribution folder as it was before MacBinary encoding. Once this check is made, the .zip file is suitable for uploading, go to the Uploading section.
After the checks have been made, you now have a .zip 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 archive of your plug), and write a description for people to decide if they should download your plug-in (just ignore the compression/encoding instructions found there, however, they are global to all the Ambrosia add-on files and were not meant for Nova). Be advised that an archive of more than a dozen of megabytes won’t be accepted. If your plug is really big and doesn’t fit in 12 Mb when archived, then you need to separate your distribution folder into smaller parts, archive these separately, and upload them separately. It’s not a good idea at all to use segmented compression, as segmented archives are quite harder to uncompress, especially for PC users.
Be aware that at the time of this writing (and probably for some time from this time), the awesome Canadian duo (Cleindori and David Arthur) is in charge of the Nova add-on files and, in continuity with the previous one in charge (pipeline, one of the ATMOS guys), 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 they need to contact you about something with your submission; they’ll remove your address from the description before posting the file), and observation of this very guide being another. Files that don’t meet these rules will be deleted and not put in the Nova add-on files. So, be sure you abide by their rules 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 archive should be available in the Nova add-on files. To make sure there has been no problem, download your plug archive, 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 announcement, 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.