(This documentation was written up by SL, mostly in late january and early february 2005.)
(The starmap3 docs were revised as the format was revised while implementing it.)
__________________________________________________________________
Standard notes:
	(#B) indicates # bytes.
	(#b) indicates # bits.

Variable types:
	byte : 8 bit unsigned integer (1 byte)
	sbyte : 8 bit signed integer (1 byte)
	char : Also an 8 bit signed integer, but used for text (1 byte)
	short or int16 : 16 bit signed integer (2 bytes)
	ushort or uint16 : 16 bit unsigned integer (2 bytes)
	int or int32 : 32 bit signed integer (4 bytes)
	uint or uint32 : 32 bit unsigned integer (4 bytes)
	long or int64 : 64 bit signed integer (8 bytes)
	ulong or uint64 : 64 bit unsigned integer (8 bytes)
	float : 32 bit floating-point (4 bytes)
	double : 64 bit floating-point (8 bytes)
	
	
formula => name indicates that this isn't a variable in the file, it's a variable contained in another variable. For example:
	(1B) byte info
	If ((info&0x80)==0):	//It's a star system
		(info&0x1F) (5b) => Stellar type/class
		
__________________________________________________________________
starmap.bin (The standard NIV starmap format)
	(4B) int File size after importing the last inbox?
	And numerous entries. For each entry:
	If it's a star:
		(8B) double star_id
		(20B) string star_name, without a null terminator
		(4B) string " S##" where ## is the star type, without a null terminator.
	If it's a planet or moon:
		(8B) double planet_id (= star_id + body_number, where the first body (bodies are planets and moons) is 1)
		(20B) string planet_name, without a null terminator.
		(4B) string " P##" where ## is the body number, without null terminator. (For planets, the # of its orbit, e.g. 02 for the second planet, but not so for moons).
		
		Moons' default names end with "#../../" , with the first .. being the moon #, and the second .. being the planet #, e.g. the second moon of the fifth planet is #02/05.
		However, there are no names like this in the default starmap.bin.
	Each entry takes up 32 bytes.
__________________________________________________________________
		

__________________________________________________________________
starmap2.bin (The starmap format used by NoctisMapper)
	Numerous entries. For each entry:
		(4B) int star_x
		(4B) int star_y
		(4B) int star_z
		(4B) int index (0 is a star, higher values indicate a planet, only used by NoctisMapper to determine if this entry is for a star or planet) - Triceratops and Styracosaurus write the body number + 1 here.
		(4B) int unknown or unused (or body type) (0 for stars, unknown for planets, ignored by NoctisMapper) - Triceratops writes the body number +1 here (although it is already written to the index field as well). Styracosaurus (the SM2-writing component of SyncStarmap), on the other hand, writes the the planet type here (with the intention that NM could then be easily modified by Peek to read this to use it for NM's currently nonfunctional felisian planet features).
		(20B) string name, without a null terminator
		(4B) string " S##" or " P##" where ## is the star type, or the body number, without a null terminator.
	Each entry takes up 44 bytes.
		
	Entries may be unused (if they're deleted), if so, the name will be empty (filled with spaces, probably).
__________________________________________________________________


__________________________________________________________________
Starmap 3 (This is a new design for a better starmap format, which could have automated updating, etc):

Design goals:
	1. The user can do just about anything they want with starmap entries in Noctis, like now, however, certain things you do may remain local-only (for example, if you delete someone else's star name, the server will reject the change, and it'll be marked local-only in your starmap).
	2. Users have usernames and passwords, and entries in the starmap and guide are marked with the username submitting them (technically they're marked with the user's ID#, and a list of ID#s -> usernames is kept by the server and noctis). This means the person who named something can always rename it for everyone, and other people can't (Though locally renaming will be successful).
	3. You'll run a Sync-Starmap program to synchronize your starmap. It'll have an .ini file which contains your username, password, and the path your starmap file is in (by default, 'data'). If it isn't found in the specified path (or the path doesn't exist), the current folder ('.') is checked. If it still isn't found, the program will complain.
	4. To be more efficient in speed and size than previous starmap file formats.
	5. Currently, outboxes are sent to an email address as before. If you run sync-starmap, it will check for new inboxes and download and install them automatically.
	6. Sync-Starmap backs up your starmap/guide/users files before doing anything with them.
	7. (This one isn't implemented, since the current version of SM3 doesn't have an always-on server) Moderators can log in to a web-site and can delete entries, and send messages to users, so that they can delete invalid entries and send messages like "'Earth' isn't a legal name for a planet in the Noctis galaxy, because we don't allow planets to be named after real-world planets." Administrators can block users, IP addresses, etc, from submitting data to the server-starmap, or can block them entirely.

Ideally the moderators' stuff and the server scripts for this would run on anywherebb, but since Alex is almost never around, and this would need to be tested, it could be run from elsewhere, at least initially. There's also the concern that if a flaw is discovered in the server scripts and they need to be updated, it would be impossible to do that on anywherebb.com if Alex wasn't around at the time.

Starmap files:
	starmap3.map : Starmap data itself, the names of stars and planets, their type, etc.
	starmap3.usr : List of usernames and their ID#s
	starmap3.gd : The guide
	
Actions you can take relating to entries:
	1. Name a star, planet, or moon.
		If someone else tries to name it too, both names will be applied. You'll only see one in game, but you can ST etc with either name. There's a limit to how many names something can have, and if someone exceeds that limit, their name will only be known to them (it'll be marked local-only).
	2. Remove the name of a star, planet, or moon.
		The removal will be local-only if you aren't the person that gave the star/planet/etc that name. Also, stars which were imported from the original starmap.bin have no ownership information, so if you try to remove a label on one of those, it'll be local-only.
		
__________________________________________________________________
starmap3.map
	ushort fileFormatVersion;	//This is 1 currently. It's here to allow the possibility of improving the format later.
	ulong version;	//This is set after importing an outbox, and is included when sending inboxes - that's how the server knows which entries to send to us. If this reaches 0xffffffffffffffff, it will yell "AHHHH! ACK! OUT OF VERSION NUMBERS!" and die horribly. By that time, the file should be bigger than any existing hard drive anyways.
	Numerous entries. For each entry:
		(1B) byte flags (Has 8 bits, 0-7. If a bit entry line is blank, it's unused):
			Flags in the client's version:
				NOTE: If flags 7 and 6 are both set, that is a special condition which means this entry has never been sent in an outbox. Flag 6 will be cleared when it is sent.
				7: Include in outbox (If 1, we will include this entry in outboxes. This is cleared after writing an outbox - however, as long as "Sent but not recieved" is set, we will continue to include this entry. If we modify this entry later we will set this again, which is our clue that it still needs to be outboxed again later even after the server notes that it has the entry.)
				6: Local only (If this is true, 'include in outbox' will never be set if you change this entry locally - Noctis knows the server doesn't include this entry)
				5: Deleted (If true this entry has been deleted. It can be overwritten if 'include in inbox' is false.)
				4: Invalid (Set automatically by Noctis if any of the information in the entry is false, like the number of planets, etc)
				3: Star (If true this entry is for a star, if 0 it's for a planet or moon)
				2: Sent but not recieved (This is set when we write this into an outbox. It's cleared when we get it back in an inbox.)
				For stars:
					1: Fuel (There's scopeable lithium here)
					0: Felisian (has at least one felisian world)
				For planets:
					1:
					0:
			Flags in the server's version:
				7: Include in inbox
				6:
				5: Deleted (Deleted entries are never overwritten on the server, because it has to know to send them to clients still)
				4: Invalid
				3: Star
				2:
				For stars:
					1: Fuel
					0: Felisian
				For planets:
					1:
					0:
		Both stars and planets (and moons):
			(4B) discoverer //The ID# of the user who found this star. (0xFFFFFFFF means unknown, 0xFFFFFFFE means we made this entry but don't know our own user# yet.)
			(20B) char[20] name	//Without a null terminator
		Stars only:
			(4B) int star_sector_x
			(4B) int star_sector_y
			(4B) int star_sector_z
			(2B) ushort data:
				(data&0xF) (4b) => Stellar type/class // Bits 0-3, valid values 0-11
				((data>>4)&0x1F) (5b) => Number of planets //Bits 4-8, valid values 0-20
				((data>>9)&0x7F) (8b) => Number of moons //Bits 9-14, valid values 0-76
			(4B) uint file position of next alternate name, or 0 if there are none.
			Total: 43 bytes per star
		Planets and moons only:
			(4B) uint file position of star
			(2B) ushort data
				(data&0xF) (4b) => Planet type/class // Bits 0-3, valid values 0-10
				((data>>4)&0x1F) (5b) => Planet number //Bits 4-8, valid values 0-19	//If this object is a moon, this is the planet # of its parent, otherwise it's the planet's own ID#.
				((data>>9)&0x1F) (5b) => Moon number //Bits 9-13, valid values 0-19		//If this object is a planet, this is 0x1F (meaning not-a-moon). Otherwise it's the moon #.
				Bits 14-15 are unused.
			(4B) uint file position of next alternate name, or 0 if there are none.
			Total: 35 bytes per planet or moon.

__________________________________________________________________
Outbox format (written by Sync-Starmap):
	ushort fileFormatVersion;	//This is 1 currently. It's here to allow the possibility of improving the format later.
	ulong version;	//The version that the client has in starmap3.map.
	char[20] username;
	char[20] password;	//Size not known yet. Encrypted with webserver's public key?
	uint numMapEntries;
	uint numGuideEntries;
	Numerous map entries. Each entry is similar to entries in starmap3.map, except these flags only are meaningful (blank ones are not):
		(1B) byte flags (Has 8 bits, 0-7):
			7:
			6:
			5: Deleted
			4: (unused) //Invalid
			3: Star
			2:
			For stars:
				1: Fuel (There's scopeable lithium here)
				0: Felisian (has at least one felisian world)
			For planets:
				1:
				0:
		
		Discoverer, and alternate name pos are omitted, and planets note their star's sector coods.
		
		Both stars and planets (and moons):
			(20B) char[20] name	//Without a null terminator
			(4B) int star_sector_x
			(4B) int star_sector_y
			(4B) int star_sector_z
			Stars only:
				(2B) ushort data:
					(data&0xF) (4b) => Stellar type/class // Bits 0-3, valid values 0-11
					((data>>4)&0x1F) (5b) => Number of planets //Bits 4-8, valid values 0-20
					((data>>9)&0x7F) (8b) => Number of moons //Bits 9-14, valid values 0-76
			Planets and moons only:
				(2B) ushort data
					(data&0xF) (4b) => Planet type/class // Bits 0-3, valid values 0-10
					((data>>4)&0x1F) (5b) => Planet number //Bits 4-8, valid values 0-19	//If this object is a moon, this is the planet # of its parent, otherwise it's the planet's own ID#.
					((data>>9)&0x1F) (5b) => Moon number //Bits 9-13, valid values 0-19		//If this object is a planet, this is 0x1F (meaning not-a-moon). Otherwise it's the moon #.
					Bits 14-15 are unused.
			
	Numerous guide entries:
		Uchar flags;
		Dword subjectsx;
		Dword subjectsy;
		Dword subjectsz;
		Uword pNum;		//0x1F for the star
		Uword mNum;		//0x1F for a planet or star, otherwise, the # of the moon
		//So (pNum, mNum) would be:
		//Star: (0x1F, 0x1F)
		//2nd Planet: (2, 0x1F)
		//19th Moon of 2nd Planet: (2, 19)
		char[76] entry;

__________________________________________________________________
Inbox format (Read by Sync-Starmap):
	ushort fileFormatVersion;	//This is 1 currently. It's here to allow the possibility of improving the format later.
	ulong version;	//The version of this inbox.
	uint numUserEntries;
	uint numMapEntries;
	uint numGuideEntries;
	For each user entry:
		(4B) uint drifter_id
		(20B) char[20] drifter_name //(may or may not be null terminated)
	Starmap entries. Each entry is similar (but not identical) to entries in starmap3.map. Certain flags aren't meaningful, however (the ones which're blank).
		(1B) byte flags (Has 8 bits, 0-7):
			7: 
			6: Local only
			5: Deleted
			4: Invalid
			3: Star
			2:
			For stars:
				1: Fuel (There's scopeable lithium here)
				0: Felisian (has at least one felisian world)
			For planets:
				1:
				0:
		char[20] name
		uint discoverer
		int sector X coordinate (of the system)
		int sector Y coordinate (of the system)
		int sector Z coordinate (of the system)
		ushort data;
		
	For each guide entry:
		Uchar flags;
		Dword subjectsx;
		Dword subjectsy;
		Dword subjectsz;
		Uword pNum;		//0x1F for the star
		Uword mNum;		//0x1F for a planet or star, otherwise, the # of the moon
		//So (pNum, mNum) would be:
		//Star: (0x1F, 0x1F)
		//2nd Planet: (2, 0x1F)
		//19th Moon of 2nd Planet: (2, 19)
		Udword writer;	//the person who wrote the entry
		char entry[76];
__________________________________________________________________
			
starmap3.usr
	//Contains entries denoting the ID#s of individual drifters - the ID#s are used in starmap3 to save space, instead of using names.
	
	ushort fileFormatVersion;	//This is 1 currently. It's here to allow the possibility of improving the format later.
	ulong version;	//The version of this file.
	For each entry:
		(4B) uint drifter_id
		(20B) char[20] drifter_name //(may or may not be null terminated)
	
	The server's version (which is named 'starmap3.svr'):
	For each entry:
		(4B) unsigned long drifter_id
		(20B) char[20] drifter_name //(may or may not be null terminated)
		(32B) char[32] password hash (md5)
		(4B) uint entries submitted
		(4B) uint invalid entries submitted
		(4B) uint bad entries submitted
		------ Stuff below here is only included in an actual server version ------
		(?B) last login (time)
		(4B) uint last IP address0
		(4B) uint last IP address1
		(4B) uint last IP address2
		(4B) uint last IP address3
		(4B) uint last IP address4
		(4B) uint last IP address5
		(4B) uint last IP address6
		(4B) uint last IP address7
			The IPs are set to 0xffffffff if unused.
		(1B) byte banned (number of days they're banned for, if 0 they're not banned , if 255 they're banned forever)
			If they're banned, the 'data' variable below contains flags which specify how they're banned. If their banned,
			they can't log on with their username, that's always the case. The flags enable harsher measures.
		(1B) byte data
			(3b) bits 0-2: oldest IP (the next one overwritten if their next IP doesn't match an old one)
			7: Ban all invididual IPs
			6: Ban their MAC addresses
			5: Ban common subnets (If they have more than one IP with identical first, second, and third octets, all connections with those matching are blocked)
			4: Extreme ISP Ban (This acts like the ban common subnets, but looks for only identical first and second octets, and bans those.)
				If both 'Ban common subnets' and 'Extreme ISP ban' are set, then if the person has any matching first octets, those are blocked entirely. These is an extremely harsh measure, and not recommended for use.
			3: Wide bans for all IPs (If this is on, then 'ban common subnets' and 'extreme ISP ban' use ALL their IPs, not just ones which match at least one other)
		These flags exist to allow administrators more latititue in reinforcing bans against someone who refuses to stay banned. Additionally, holding 8 IPs instead of just one allows the bans to be more accurate and patterns to be discerned.
__________________________________________________________________

Starmap3.gd:
	ushort fileFormatVersion;	//This is 1 currently. It's here to allow the possibility of improving the format later.
	ulong version;
	For each entry:
		Uchar flags;	//bit 7 is 'include in outbox', bit 6 is 'local only'. bit 5 is 'deleted'. The other bits aren't used at this time. Both bits 7 and 6 together indicate this entry has never been sent in an outbox. That's used for determining if it can be really deleted from the file if it's got the deleted flag (it can't be if it's been sent to the server).
		Dword subjectsx;
		Dword subjectsy;
		Dword subjectsz;
		Uword pNum;		//0x1F for the star
		Uword mNum;		//0x1F for a planet or star, otherwise, the # of the moon
		//So (pNum, mNum) would be:
		//Star: (0x1F, 0x1F)
		//2nd Planet: (2, 0x1F)
		//19th Moon of 2nd Planet: (2, 19)
		Udword writer;	//the person who wrote the entry
		char entry[76];
__________________________________________________________________

Using sync-starmap if you're using NICE on a computer with no internet access:
Put your starmap3.map, starmap3.gd, starmap3.usr, and sync-starmap onto a computer with internet access. (It'd be easier to just copy the data folder)
Run sync-starmap. It will get http://noctis.sl.ecwhost.com/starmap-version.txt, and will read the version, then generate an outbox, and then start requesting inboxes from the server, and as it gets each one it will apply it. It will tell you to send the outbox to starmap at noctis dot sl dot ecwhost dot com.