Page 1 of 1

Regulations and Tipps for Uploading Addons to the Motherlode

Posted: 22.03.2013, 14:37
by Guckytos
Regulations and Tipps for Uploading Addons to the CelestiaMotherlode (ML)

Before uploading, please check if your addon is really ready for wider distribution. Here are some pointers on what should be kept in mind and looked after before releasing and uploading an addon to the ML.

General:
  1. It helps to look at your Addon from the point of view of those who will download it: Does it offer something new (check the catalog for similar Addons), or in better quality? Will other people find it actually interesting?
  2. Did you include a README file which explains all the details about your Addon, including installation? Always include an english README, and provide other languages in addition if you want.
  3. You must use only letters, numbers, underscore, and minus in file names. All other characters will cause problems of one kind or another.
  4. Keep in mind that Celestia is a multi-platform program.
    Other platforms (Linux/Unix) don't consider the file "abc.jpg" and "ABC.jpg" equal, so you should enter all filenames carefully with correct and same case for each object across all files and models for your addon.
    Make sure directories like "textures\medres" or "models" are written all lowercase. Keeping everything lowercase and without blank spaces is probably the easiest solution. This is particularly important when creating 3DS or CMOD files.
  5. The ML admins reserve the right to not offer an addon for download, or to remove it later.

COPYRIGHT INFORMATION:
France has a 3 strikes and the US just launched a 6 strike. Plus our host is inside the DMCA influence sphere.
The following rules apply for things within your addon (i.e. maps, models, textures, ...), but as an example just a texture will be mentioned in the following points.
  1. If the texture is 100% yours, that is you made it ALL (i.e. with a fractal generator or a paint program) and you did not reuse other images to make a "Frankenstein" texture then you can do with it what ever YOU want.
    A recommendation would be to put it under a CC license i.e. "CC-BY-SA". But basically that is up to you.
  2. If you REUSE someone elses work, you MUST follow THEIR COPYRIGHT restrictions as described by the original creator.
  3. Some maps/models/textures FREE to USE BUT NOT TO REDISTRIBUTE!!!! So DO NOT use them in an addon -- it is illegal.
    Others are fine to redistribute for NON-COMMERCIAL uses.
  4. You MUST use what the original creator of the work wants and it is ALWAYS a good idea to ASK PERMISSION first if it is not a CC or GPL license, and even then it is very polite manners to do so.
  5. Include a web address to the original artwork you used! And include the type of copyright it is under!
  6. You can NOT change the original copyright! Say from NON-COMMERCIAL to CC -- that is also illegal in most of the world (except when you HAVE EXPRESS WRITTEN PERMISSION TO DO SO!)

Addon Installation:
  1. The Addon should work simply by decompressing it into Celestia's extras-folder and restarting Celestia. Only in rare circumstance should a user need to modify other files.
  2. Also read the ML Addon Installation page and ensure that the described installation procedure fits to your add-on.

File type:
  1. Addons should be packaged in ZIP files with standard compression. Don't use RAR, ACE, self-extracting ZIP-files etc.
  2. The ML tries to avoid executable files for a number of reasons, so unless we have a good reason and some trust in it's creator we won't host executables.

File Size:
  1. Try to keep the (basic) Addon small – not everybody has a broadband access to the Internet, and many big files put additional load to the servers the Celestia Motherlode is hosted at. Avoid PNG textures unless you need their special capabilities (like transparency). Use normal quality settings when saving JPG files, maximum quality only gives slightly better quality but much larger files. Don't artificially increase the resolution of textures.
  2. Due to some changes on the ML hosting site please keep each single ZIP file under 100 MB. This is also to make it easier for people to download the single files (and not have to repeat a huge download due to a failure).
    (Note: If it is an exceptionally high quality add on you can contact the admin and ask if a big archive can be used. But whether or not it will be granted is up to the ML admins.)

How to upload:
  1. The addon can uploaded to the ML by using the following methods:
    HTTP for archives up to 8 MB
    FTP for archives bigger than 8 MB

After upload:
  1. After the upload to the ML the addon will be checked for consistency with the ML rules.
  2. Please be patient after your upload! Sometimes it may takes a week or more until your addon is checked and ready for a publication in our catalogs.
  3. If there are problems detected with your addon you will be contacted by the checker and given a report on the found problems to be rectified before the next upload and check.

Addon-Checker comments on important points:
Summary:
--- MOST IMPORTANT ---
  1. They MUST run on different operating systems
    a) Windows (XP, Vista, 7 -- there will NOT BE Windows 8 "Metro" support, nor win8 ARM support)
    b) Linux, every one that supports QT4, that is almost all of them.
    c) Apple Mac OS-x 10.?
  2. Capitalization errors -- VERY important
  3. Missing images -- is everything that is supposed to be there REALLY there
  4. *.ssc errors -- even very experienced people make "typos"

Notes on #1:
1)
Windows dose things VERY differently than a UNIX system, so as such we NEED to use the MOST strict rules that a operating system uses so that the add on WILL run on all 3 major types of operating systems.

2)
The first thing that is checked after upload is any 3d models for Capitalization issues:
A) the name of the image used MUST match the real image name
B) the file extension MUST be lowercase

The meshes call textures and maps so the Capitalization MUST match the real image in the "textures" folder.
The easiest way of doing this for .3ds, and BINARY .cmod is to use a HEX code editor to read the binary data. In this case the human readable information is what you need -- the NAME(S) of the image(s) being used.

A screenshot of a hex editor reading a .3ds that is NOT fallowing the rules. The image names used are all uppercase and the file extension is also uppercase.
-- See the window on the right side for the all cap image names --
-- An addon doing this will not be accepted to the ML--
(A black desktop theme is used)
Image

For the ANCII text .cmod a good text editor will do. Some examples for that are "SCiTE" or "Notepad++" on Windows and Gedit, Kate, Emacs, and VI on Linux.

[NOTE to MS Windows users]
Microsoft sees fit BY DEFAULT to "hide known file extensions" in the settings of Windows.
This is also Windows SECURITY 101!
Turn OFF the set by default "hide known file extensions" so that way you know that the i.e. the PDF you are about to click on IS IN FACT "Invoice.pdf" and is NOT "Invoice.pdf.exe" and you are about to install a virus.

Changing this setting also lets you know that the map.jpg IS in fact using a lower case file extension and not .JPG

3) Textures and Images
A few things:

1) Please use maps that DO map to a sphere and is in SimpleCylindrical format --- see the tutorials section of the forum.

2) A "bumpMap" is NOT NEEDED. A bad one looks, well, VERY BAD, so if you do not start off with a 16 bit height map to begin with do not use a "bad" bump map. It is very easy to make a very ugly bumpmap.
So if you can not make a good one or if you did not start with a 16 bit DEM then please do not feel the need to include them.

A BumpMap for Celestia is a 8 bit (256 tones) GRAYSCALE image that does NOT have an ALPHA Chanel.

There is also a "NormalMap" (the blue images you might see). If you do not know what they are and can NOT make the VERY SPECIAL TYPE of NormalMap that Celestia uses, then please do not make one.
-- SEE the tutorials for Normal maps. PS. Photoshop does NOT make the type of "NormalMap" that Celestia uses!!!

Also in the textures is checked the Capitalization of the map VS. the .ssc definition
(This is done though running the debug output in Celestia [ < shift > + < ~ > ] )

Notes on #2
"Capitalization errors"
  1. All file extensions MUST be lowercase (i.e. .ssc, .jpg, .png, .dds)

    [NOTE to mostly MS Windows users]
    For some odd reason a lot of Microsoft programs sometimes change the capitalization. PhotoShop can save images to UPPERCASE file extensions (and if file extensions are hidden, then you will never know).

    Some 3d programs are VERY BAD at this: The image you assign to a mesh might be all lowercase, BUT the 3ds mesh might have uppercase for the image.
    Some Linux programs can do this too if set to do so --- So please check the models with a HEX editor BEFORE you upload them.

  2. An image in /textures/medres must have the capitalization match the name used in the .ssc
  3. A good rule of thumb is to pick a naming scheme and STAY WITH IT
    Examples:
    ImageOne.jpg
    imageone.jpg
    -- still fine to use BUT a bit hard to read -- image_one.jpg ( underscores are hare to read )

    Using a scheme like ImageOne.jpg makes reading a long name easy (i.e. MarsNormalMap.png, BlueMarsCluods.png)

Notes on #3
"Missing images"
PLEASE run the debug output in Celestia [ < shift > + < ~ > ] before packaging the addon!
The number of lines that this output uses can be set at the very end of the "celestia.cfg" file. If you have a bigger addon it is good to set it to a high value i.e. "2048" lines.
Quote from celestia.cfg:
#------------------------------------------------------------------------
# The number of rows in the debug log (displayable onscreen by pressing
# the ~ (tilde). The default log size is 200.
#------------------------------------------------------------------------
LogSize 2048
You will very quickly see if something is missing with a "unrecognized or missing" error. This can also come from typos, see #4.

Notes on #4
#ssc errors #
Normally these are typos, so please double check them. But not all of them.
These are things that WILL output an error in the "debug log".
--- SO USE IT PLEASE !!! ---
1)
Just making up a name for a "custom orbit" - will toss an error.

2)
Redefining an object and leaving the name a blank with two "". Celestia can handle 4 of these BEFORE killing the add on. If there are 5 the add on will not even work!

3)
The order of things in the .ssc.
This is a bit hard to explain so an example is used:
-- A ship is in orbit around a moon --
Well the planet that the moon orbits MUST be defined/called BEFORE the moon. And the moon MUST be defined/called before the ship.

Celestia reads the .ssc from the start to the end. So if you put a ship at the top BEFORE the moon or planet, Celestia will toss an error about NO MOON for the ship to orbit.

Simple logic: "a" before "b" and "b" before "c".

4)
A common "oops": Forgetting to remove a # at the front of an option you are using. (# tells Celestia this is a comment that it can ignore.)