Sharing Content

From Cube Wiki
Revision as of 16:59, 12 December 2014 by Admin (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

If you have created any sort of content for Sauerbraten, chances are you will want to distribute it. There are standards for this and certain procedures can help ensure your creation works well. This text covers basic cross-platform caveats and general structure of the form in which your content is best presented to your audience. Not following such guidelines can get your content flagged or even deleted, so paying attention pays off.

On Quadropolis.us, you should follow their packaging guide, which shares a common root with this document.

Quick Info

As always, this is phrased in Sauerbraten terms. Your specific copy might have slightly different foldernames and/or requirements; where appropriate we will mention some of these in detail.

Place your own content and the below into a ZIP-file. ZIP is essentially universal. Make sure it can be extracted directly into the player's home folder -- not their installation folder! Read up on FAQ: homeDIR: game-HOME-dir VS game-INSTALL-dir on the FAQ.

  • ./packages/base/ = base package: folder_a_single_map.ogz
  1. mapname.ogz (or mapname.cgz, mapname.bgz -- depending on the game)
  2. mapname.cfg
  3. mapname.txt
  4. mapname.jpg -- this should be 256 by 256 -- which will be displayed in the GUI menu, assuming it's made menu selectable by the user or some of your own scripting.
  • ./packages/yourname/ = personal package folder
  1. map/pack/misc. CFG files
  2. texture image files
  3. skybox-folder with appropriate images

Creating a ZIP

You should always package your content into a ZIP file. Don't just use your favorite file compressor! ZIP is the most widely available file compression and packing format, and is easily (de-)compressed on all target platforms. Even with popularity aside, ZIP often gives better compression on the already well compressed data used with Sauerbraten. Maps, for example, are already saved with ZIP compression, therefore other packers (e.g. RAR) will go to lengths to try compress the files even further, often resulting in overhead (making the file larger than the ZIP).

You could ask, "Why ZIP a map at all?" But the beauty of packing your files up like this is that you can include a read-me with your file(s). Including a read-me is seen as good practice, and allows you to include licensing information (Creative Commons etc), contact information, detailed map description/information and maybe even something about yourself.

But the true benefit is that users simply go to their game-HOME and unpack right into that folder -- again, this way of unpacking a ZIP is most widely available on the target platforms -- if you put (as people still often do) your installation-files into an extra subdirectory inside your ZIP people will have to go into that subfolder and move the files from there one up and then delete your subfolder... spare them this and anything like it; you'd like them all to work simple and all the same yourself!

Therefore, a minimalistic distribution file would be a ZIP containing a OGZ map file and a CFG map config inside packages/base and a README_mapname.txt either inside packages/yourname or on the top-level. Be sure to have something of your own and unique in the filename, not that "someone careless" simply overwrites your readme.txt file, call it readme_myProject_2020apr01.txt.

You could also use *.html, but not *.pdf, *.rtf and especially not *.doc. To quote Eric Raymond: "Never, ever expect hackers to be able to read closed proprietary document formats like Microsoft Word or Excel. Most hackers react to these about as well as you would to having a pile of steaming pig manure dumped on your doorstep. Even when they can cope, they resent having to do so.")

More importantly however, always package what is required, not everything used (i.e. repackaging core Sauerbraten textures used in your map is wrong, not to mention a violation their license).

Creating a Read-Me

Many people make the mistake of calling their READMEs README.txt. This results in people overwriting other people's READMEs, and the whole thing gets confusing fast. Therefore, an easy solution is to call it README_mapname.txt, where mapname should be replaced with an identifying name.

Information your README should include:

  • Your identification: Self explanatory but it's up to you if you want to include your real life information or just your pseudonym in the Sauerbraten community (or both).
  • Description of content: A title or short sentence giving (at least an indication) of what to expect. If your release is "beta" (i.e. not final) you should say so here!
  • Date or Version: Often forgotten and always sorely missed, the date can give an indication as to which release of Sauerbraten was the design target, saving users troubleshooting time. For example even some maps in the 2006-04-26 release gave "old map format" errors, and things like this can happen in the future.

Optional information your README could include:

  • Background information: Tell the story behind the map, talk about the usage of the script, give location of further documentation and/or explain your intentions/reasoning if required for your package.
  • Credits: You should note everybody and anybody who has in some way contributed to your package enough to earn a mention here, and it is considered proper etiquette within any collaborative community. Include the source of any packages you used (include a URL) and of course don't forget all those that gave you critique on the way to finishing your package.
  • Known issues: A list of any issues or caveats users may encounter that you are aware of (for example platform independencies).
  • Contact information: Methods to contact you will make it possible for feedback and bug information to reach you, however this might also lead to more spam reaching your inbox.

Frequently Asked Questions

What goes into the ZIP and what does not?

Your ZIP should include a subdirectory structure so it can be unpacked into the main Sauerbraten directory. A simple checklist would be:

  • Map file (OGZ) in "packages/base/file.ogz" inside the ZIP
  • Map config file (CFG) in "packages/base/file.cfg"
  • Your package data in "packages/mydata/" (mydata usually being your pseudonym within the Sauerbraten community)
  • Scripts can be placed inside the root directory, the data folder or your package folder.

Using third-party package data (like a skybox from Quadropolis) should only be included if:

  1. You have written permission from the original author
  2. You really need to be independent from possible changes on the original data

If both apply, create a folder in "/packages" for holding your package data but be sure to adapt all paths (in your CFG's) to this new folder. If you don't have the author's permission, the best way to do it is to provide a download link to the required third-party package and put it into the node-description on quadropolis and inside your README. Creating two versions of your package is also a viable solution, one including the whole data set (requires author's permission!) and another with just the additions you have created (since some people might already have or even have a newer version of that third-party package!).

In some cases, you will not need the author's permission, depending on the license they have used for their package, however if you do use their package, send them an email to let them know anyway. This can be useful in situations where the author is no longer active in the Sauerbraten community and is hard to get in touch with. If you do not know the license or can't contact the author you have to assume it's copyrighted and you may not use in your package!

How do I get my package into the next release of Sauerbraten?

If your work is of a high standard and useful in the development of Sauerbraten, it will. Shouting at the developers in all capital letters will make you seem immature, and repeated requests will make you somewhat of an annoyance, reducing your chances of ever getting something into Sauerbraten. Maturity is extremely important. For more information, read eihrul's here.

How can I ensure everybody will enjoy my work?

Well, actually you can't, but that's just aesthetics for you! More seriously though, there are some known issues with platform dependencies with Sauerbraten. Safest bet is to package all data in (preferably) PNG for images, OGG for music and WAV for sounds.

Also ensure that all filenames are lower-case! Some operating systems are case sensitive, meaning that Texture.JPG is different to texture.jpg, causing all sorts of problems with your package. This applies to all files included with the package. Don't forget to make sure that your map does not begin with a capital letter so that TAB completion works!

Windows, by default, doesn't show file extensions. This can cause problems with other operating systems (as mentioned above). You can fix this by following these instructions:

  • Open Windows Explorer/My Computer
  • Click on the Tools menu
  • Select Folder Options
  • Click on the View tab
  • Make sure "Hide extensions for known file types" is not checked
  • Press OK

Don't forget to rename all your package files with lowercase letters (including the extension) after changing the setting!

Remove all the _DS_store stuff when zipping on a Mac, the Thumbs.db files if coming from Windows, linux usually has no such files. They can often double the size of the file since they contain un-delete data and/or imagery - they can also give attackers insight into your system - removing them is really worth finding out how.

    • This paragraph could be enhanced by descriptions of what to do on each system - community members: please post something on pastebin and then link to it on the talk:-page here : Thank You!

Common Mistakes

Many people make the same mistakes when packaging their files, over and over again. To prevent this happening to you, make sure you don't make any of the same mistakes here:

  • Including garbage with your package: Other than including content already distributed with Sauerbraten, many users include rubbish such as thumbs.db (created by Windows when Thumbnail view is used) and CVS folders. Windows users in particular should make sure hidden and system files are set to visible so this doesn't happen (thumbs.db is invisible otherwise).
  • Giving maps extremely common names/existing names: There are probably more than ten maps titled 'castle' on Quadropolis (for example), and this becomes a problem when they start overwriting each other. Also, don't name your new map 'metl4'.
  • Copyright violations: Including other user's content without permission is wrong (unless of course they provide it under a license which allows that). Expanding on this, modifying existing maps and then republishing them on Quadropolis is also a copyright violation, unless you have the author's permission (highly unlikely).

When You're Done

If you've gotten to this point and covered all the bases above, then congratulations, but how do you go about distributing your content, you ask? The most common method is to post it on Quadropolis, which is the semi official site for Cube Engine related maps, mods, and other content. Be sure to register a username and read their user's guide and packaging guide before posting.

Good luck creating!