Your browser does not seem to support JavaScript. As a result, your viewing experience will be diminished, and you have been placed in read-only mode.
Please download a browser that supports JavaScript, or enable it if it's disabled (i.e. NoScript).
New and improved!
With the coming of Stuffit 9, and the relocation of my guides, this version is now officially outdated (sorry if you're coming from the even older version for all these redirections!). Please go to the up-to-date versionhere.
Plug-in Distribution Guide What you should do to make your plug-in 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.
I 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.
a) Contents 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 (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. 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).
Format 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 these 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 forbidden. 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.
II 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.
a) Manual/Enriched text in general 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. 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.../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.
Images/Screenshots/Pictures 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.
c) Sound and music 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.
d) Movies 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.
III Archive/Compress 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 abtain. 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 compression, as the format will take care of both at once.
a) Overview of the compression formats Only two compression formats are actually usable for Nova plug-ins, since both Mac and PC users are to be able to download and use them: .zip and .sit. Any other format is completely prohibited. Especially, Panther's 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, .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.
If you're on a PC, you can use .sit, but it would make very little sense as it doesn't give you any real benefit: using .zip is easier for you, and there are a ton of utilities that can compress in .zip, including free ones and Free ones, and it's generally easier for the end user as well. On the other hand, if you're on a Mac, using .zip or .sit is up to you. There are pros and cons for each format, that will be detailed more later:
.sit -pros:
-easy for you. Just drag and drop the folder to DropStuff and that's it (but read down anyway).
-easy for Mac users of your plug-in. Stuffit Expander on their machine will take care of it.
-it's the most Mac-like way (if this has any meaning...). .sit has been THE compression format on Macs for the last ten years.
-cons:
-not easy for PC users of your plug-in. Don't get me started on this.
-oudated. Should be replaced by .sitx, but using it would increase the problems for the PC users, so it cannot be used (yet).
.zip -pros:
-still easy for Mac users of your plug-in, Stuffit Expander will also take care of it.
-definitely easier for PC users of your plug-in.
-most cross-platform way, .zip has been used on all platforms for quite some time, but not really on the Mac for reasons you'll see.
-less easy for you, depending on the method. Some more caution is required.
-one small snag: custom folder icons in your plug-in distribution will disappear for Mac users (PC users won't see any of your custom icons regardless of the method).
Depending on your platform and choice, jump to the relevant subsection: first, , is for PC plug-in designers. Second, c), is for Mac plug-in designers that prefer to use .sit. Lastly, d) is for Mac plug-in designers who prefer to use .zip. Mac plug-in designers who picked one method can always eventually elect the other if they find out they don't like the first after reading the explanations and instructions.
Explanations and compression instructions for PC 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 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 (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), 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.
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, ZipMagic, 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" 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. 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 "IV Uploading" section.
c) Explanations and compression instructions for Mac plug-in designers who would like to compress their plug-in in .sit
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. The .sit compression format supports the resource forks (thus the reason it's so popular on Mac, one just has to stuff and everything Just Worksย); .zip by default doesn't. If a Mac guy gets the .sit archive you produced, no problem, unstuffing it with Stuffit Expander (bundled on all macs for quite some time) will allow him to get your plug with its all-important resource fork.
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? It's 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.
Allume (formerly Aladdin), the company behind Stuffit and .sit, did create a Stuffit Expander for PC, that allows PC folks to expand .sit archives. Contrary to the Mac, it's not bundled on Windows, so first the PC guy has to download it. However, this is here the stuff gets complicated. By default, Stuffit Expander on PC, when it expands a file with a resource fork from a .sit archive, considers the resource fork is an useless piece of data on PC and discards it, only expanding the data fork. For most files, this is the right behavior as the data fork indeed contains the relevant data (text, image, movie, etc...), except in a handful of cases, such as Mac icons, Mac fonts, and Mac Nova plug-ins. For these cases, there is an option in Stuffit Expander to expand files with a resource fork as a MacBinary encoded file, usually for the relevant converter (Mac icon to .ico, Mac font to PC font, and of course Mac plug-in to .rez plug-in) to use. This option is off by default, the PC user has to activate it before (re)expanding the .sit archive.
To make matters worse, while this worked with Stuffit 7.5, Allume did not include this option in Stuffit 8.x. Therefore, we kept on telling PC people to use Stuffit 7.5; and especially as the link to downloading Stuffit 7.5, that was included in the Nova PC documentation, broke not too long after release, we made a topic in the Nova board listing current (as they moved regularly, on top of that) Stuffit 7.5 for PC download links. Since then, other events (such as a beta patch for Stuffit 8 to allow it to have this option back) have yet again changed the situation, and this topic has been updated to reflect it. At the time of this writing (02/19/2005) the situation is expected to change again in the future, especially with the incoming release of Stuffit 9 for PC. This topic, that can be found at http://www.ambrosiasw.com/forums/index.php...opic=86891&st;=0 , is guaranteed to contain the latest status of the issue, while neither this document nor your ReadMe is: I will try to update this document should anything significant happen, but the topic is likely to be more up-to-date at the time you read this, and it will be infinitely more up-to-date than your ReadMe at the time a PC user will read it some time after release. Therefore, you will have to rely at least partly on this topic, since no instruction you can give is insured not to break; especially, the links to Allume stuff you would tell to use are likely to break, as happened in the document "How to use plug-ins" that comes with Nova on PC.
All that stuff mandates two things: first, .sitx cannot be used: even if .sit is outdated, Stuffit 7.5 on PC, which remains the most reliable way right now, does not support .sitx (watch this space, though, I will try to update this to include the most up-to-date information should anything happen). Second, your ReadMe will need to contain specific instructions for the PC user to be able to use your plug-in, including a link for this topic as it will (when the PC user will download your plug and read the ReadMe) contain the most up-to-date instructions, probably more up-to-date than the ones in your ReadMe, especially when your plug-in is downloaded long after you released it. This information can be put in the ReadMe as, if the PC user expanded the .sit archive in a way that destroyed the resource fork, your ReadMe and the other files, however, will still work, and this condition can be seen easily by the user as the plug-in files will be 0kb; so the ReadMe can be used to tell the user what to do instead.
Enough theory, let's go to practice. Firstly, add this in the relevant section of your ReadMe: "For PC users, if the plug file(s) <put here a list of the actual plug-in files> are expanded as 0kb files, reexpand the downloaded <your archive name>.sit according to the instructions found in the topic at http://www.ambrosiasw.com/forums/index.php...opic=86891&st;=0 . Once you obtain non-empty files, trash any .DS_Store or _icon file, and drag and drop the plug-in files 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) You may wish (for instance if you think the user will read your ReadMe while not connected to the Net) to give some other instruction in case the plug-ins come as 0kb files (such as, "if you expanded with Stuffit 7.5, make sure the cross-platform tab is set to "when a file contains a resource fork", and reexpand"), but always include a link to this topic for the user to fall back on as it will contain the latest info (for instance in case the user just forgot to think about a Mac when expanding, as is required for Stuffit 7978r.7 to activate the "old MacBinary compatibility" feature, in the thought-powered computers of 2134 ;)). More seriously, you may never know what will be needed to be done in the future.
Then, assemble your distribution folder. You can then open DropStuff from the Stuffit Standard package (probably bundled on your Mac, otherwise download it at www.stuffit.com), and after making sure that DropStuff is set to produce a stuffit archive and NOT a stuffitX one, drag and drop your distribution folder to the drag target (or file menu ->Stuff and select the folder, or drag and drop it to the DropStuff app in the Finder). After compression, you should get a .sit file. It's best to do a last safety check: try double-clicking it and check that you can reobtain your distribution folder this way. Once this check is made, the .sit file is suitable for uploading, go to the "IV Uploading" section.
d) Explanations and compression instructions for Mac plug-in designers who would like to compress their plug-in in .zip
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. The .sit compression format supports the resource forks, thus the reason it's so popular on Mac, one just has to stuff and everything Just Worksย; .zip by default doesn't: 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).
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, there are two ways to do a .zip archive as I described: use DropZip (the rather easy way), and 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 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 two main ways. Remember that use of Panther's built-in zipping feature ("archive" 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 users, it won't work for other OSX users, pre-OSX users, nor Windows users. -The first 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. -The second way is to do it manually, using for instance the free tools found in this package: http://evula.org/inf...s/binandzip.sit . 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-ins 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 it 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 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 "IV Uploading" section.
IV 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 (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). 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 observation of this very guide being another. 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 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.
This post has been edited by Zacha Pedro : 20 May 2005 - 11:28 AM
One thing that I really wanted to do was to update this guide: at the time I wrote it first, I still had the problems of Allume not having the cross-platform tab in Stuffit 8, and people at the same time uploading in .sitx (that only Stuffit 8 can decode), of PC people uploading stuff in .rez directly, without any ReadMe, and telling that it was PC-only, of people using Panther's built-in zip feature, etc..., fresh in my mind, and I reacted to that by writing this guide. While it may be good for a column in a newspaper, writing too hot-headed tends to be bad for a technical guide, since it was not very organised, I tried to explain everything at once, there were practical instructions in the middle of the concepts, etc... So this time, I took the time to rewrite myself well, taking the time to think about the reader and not let my feelings about the matter interfere. The first part (about the accompanying files) has not been touched much since it wasn't the problem at the time, so it was not that badly written. Otherwise, I completely reorganised stuff, though some paragraphs and sentences can be recognised.
At first, I intended to rewrite it when there would be a real solution from Allume instead of Stuffit 7.5; though the new Stuffit 8 contextual menu tool is great, it's difficult to use and meant as a short-term solution, and I don't want to wait for Stuffit 9 for Windows any more.
Have a good time making plug-ins!
Well, this one is superceded itself... Please check the new version at its definitive home (just as long as no one expells me from Bomb's plug-in guide, all stuff will be updated on-site there from now on)