 -------------------------------------------------------------
    Documentation for the matrixshard-towncontrol datafiles:
 -------------------------------------------------------------
  
 "towns"
 
 town1
 {
   townid		[integer, serial number of town]
   teleport  	        [{x,y,z}, coordinates of a teleport point to reach the town]
   //citysize		[integer, amount of players with housing assigned to them]  --outdated - donot use!!! use playerindex and check the references instead!
   townname 	        [string, name of town]
   houseindex 	        [{house1,house2,...}, houses refernce list]
   goldreserve 	        [integer, amount of gold a town owns]
   currency 	        [string, identifier e.g. "gold"]
   //currencyprint 	[integer, amount of money given out so far]
   lastchange	        [{onlinetimer,...}, list of last changes (to prevent randomness)]
                          [1]: last election //4 weeks
                          [2]: last taxchange //2 weeks
                          [3]: last cityname change //2 weeks
                          [4]: last towncolor change //2 weeks
   cityindex    	[{{area1,area2,...},{region1,region2,...}}, index of areas and regions]
   area*                [{x1,y1,x2,y2}, coordinates top left, bottom right]
   region*              [{x1,y1,x2,y2}, coordinates top left, bottom right]
   bannedlist 	        [{{serial1,name1},{...}}, list of banned players who can't join a city]
   playerindex 	        [{reference1,reference2,...}, index of player member references to datafile]
   towncolors           [{integer,integer}, primary/secundary town colors]
   major 		[{serial,name}, mayor who governs this city (damn spelling error)]
   joinfee 		[integer, how much gold to join?]
   taxesperweek	        [integer, how much gold/week]
   ==============================================================================================   
   staffids             ---removed, 0bsolete---
   staffupkeep          [struct, placed NPC's and their serials!]
                         <npcname> := {serial,serial,...}, serials of npcs on duty of that type 
   hiredstaff	        [struct, amount of hired but unplaced NPC's]
                         <npcname> := integer, amount of hired but unplaced NPC's
   ==============================================================================================                            
   racerelations        [array{[0/1/2],...}, 15 positions - one for each race]
                          0: hostile, will be attacked on sight.
                          1: neutral, people can walk in the city but not settle down
                          2: friendly, can join the city, race can be hired for npc's
   cityrelations        [array{[0/1/2],...}, 1 position for each city id, tells relations]
                          0: war, will be attacked on sight
			  1: neutral, no special relations
                          2: allied, (Empire?)
   newsindex	        [{newsref1,...}, a list of news items]
   news*		[{"header",onlinetimer,"line1",...,"line6"}, news entries]
   salestax		[integer, how much is added to the price of goods being sold]
   lasttax              [timer, date the town was taxed last time. New cities have 0]
   npcunrest	        [integer, increases if the city cannot pay npc-fees, 1=30% quitchance]
   donations	        [integer, how many donations the town got this week]
   donationsold	        [integer, how much donations the city got last week]
   serviceincome	[integer, how much the city earned offering services]
   serviceincomeold	[integer, how much the city earned last week with services]                    
   saletaxincome	[integer, how much the city earned with sales taxes this week]
   saletaxincomeold     [integer, how much the city earned with sales tax last week]
   servicefee	        [integer(0-50) how much % is charged on any serviceable fees]
                          - BANK note: no charge for depositing money in local town!
                          - BANK note: accessing local treassury is charge free (no use!)
                          - BANK note: simple charge for any adding to account in own city
                          - BANK note: simple charge for depositing in a different town!
                          - BANK note: double charge for buying a house!
   //propertysaleincome ...idea - currently property sales are not reported as income in statistics!
   description	        [{line1,line2,line3,line4,line5}, major's description of the city]
   cashentries	        [{{value, who.name,timer},{...}, all direct banking transactions(reporting)]
   //customvote	        ...idea to allow majors custom votes and after a week receive results.
   isvote		[0/integer,is there a vote running?]
                          1: vote for mayor
   votechoice	        [{entry1,entry2,...}, choice of candidate references for the vote]
   voteamt		[{integer, integer,...}, nr. of votes for above candidates]
   votetitle	        [string, text to display as voting question]
   founded		[timer, the time it was founded, just for reference]
   weaponsallowed       [-/1, specifies if people may wear weapons in town - always 0 so far]

    ...the next three entries are addons for a possible empire support:
    (the mayor of the capital is automatically the emperor, and gains mayor rights in all cities)
   subordinate	        [integer, if exists, reference to the #id of a capital (Empire Support)]
   capital		[0/1, if exists this town is a capital of an Empire]
   subordinates	        [{1,2,3}, array of city #id's that are loyal]
 }

 ----------------------------------------------------------
 
 "houses"
 
 house*
 {
   houseid		[integer, id of that specific house]
   townid		[integer, specifying the town it's in]
   houseindex   	[{area1,area2,...}, Index of houseregions]
   housearea*	        [{x1,y1,x2,y2}, coordinates top left, bottom right]
   housename	        [string, Name of the house]
   ownerindex   	[{Playerref1,...}, people living there or owning it]
                        [{Guildref1}, if it's a guildhouse - the 1 (!) guild owning it]
   isshop		[0-5, describes if the house is a legal shop or public building]
                          0: a common house for living
                          1: this place is a shop. Normal people can live here too though
                          2: A public building. Owners can place vendors and stuff, but
                             only the major and his building administrates can build there.
                             Owners need to pay rent though!
                             A bit crude this system I know, but really, I didn't want to
                             start giving out housing privileges... where would that lead?
                          3: guild hall
                             Owners cannot be players/citizens but "guilds" - thus guildlords
                             of that guild can build there, even if they are not city members.
                             Taxing is normal - the guild is taxed. 
                          4: Fortification 
                             not really a building, no owner - merely defined for the map!
                          5: Roads
                             not really a building, no owner - merely defined for the map!
                          6: Inactive
                             not really a building, no owner - merely defined for the map!
   housetax		[integer, how much the tax for a house in gold/week is]
   opentax              [integer, amount of money left to be paid for this house!]
                          Note: this property only exists on buildings of type guild!
   lockdown		[{serial,...}, list of item serials locked down in this house]
   saleactive           [1 or n/a, Optional, defines if a house is being sold]
   salekey              [array, specifies the 'lock-key-string' that allows a key to unlock the main door]
                          array[1]: string, key-string to unlock door
                          array[2]: integer, objtype of the key //Note: so far only #0x1012 is accepted!!!
                          array[3]: integer, graphic id of the key
                          array[4]: integer, color of the key
                          array[5]: 0/1, was the key newbiefied
                          //note: the key will always be renamed to "Master key of the <propertyname>"
   saleprice            [integer, Optional parameter: price or value of the property (excl. salestax)]
   saletext             [array of 7 strings, Optional parameter: a text description for the sale]
 }

 ----------------------------------------------------------
 
 "players"
 
 p**** //playerserial 
 {
   playername	        [string, name of player for offline reference]
   playerserial	        [integer, playerserial]
   accountname          [string, accountname]
   townid		[town he's a member from]
   lasttax		[integer, taxes he paid]
   rank	        	[his rank within the town]
                          1: member, 2: citizen, 3: merchant, 4: lord, 5: major 6: emperor (not used)
   title                [string, each noble can have a title, assigned by his mayor/king]
   cashbox		[integer, money in his cashbox (gold) Taxes will be autopaid]
   //cashbox2   	[{{moneytype, id, amt in storage},{...}}, other currencies owned]
   privs          	[{0/1,...}, one position for each right]
                          [1]: Guards, Commanding and moving them, ban/unban players, dismiss 
                               guard NPC's, unjail prisoners (captured by guard NPC's) 
                          [2]: Finance: change taxes (headtax,housing, banking & trade tax), 
                               hire & dismiss npc's, treassury access, tax collection, may 
                               banish (or arest??) citizens who fail to pay taxes, define 
                               house-areas (=sell land), authorize "forging"?? 
                          [3]: Diplomts: Manage city relations, Manage racial relations,
                               may ban & unban players. 
                          [4]: Builders: May build roads and other structures all over town, 
                               as well as on "related" territory, authorize "forging" 
                          [5]-[7]: Not used! (historic)
   homeless		[0/1, is the person without a home?]
                          WARNING: homeless lords/majors don't qualify for re-election!       
   houseref		[{houseref1,...}, reference to the place(s) where the player lives]
   voteme		[0/1/2, shows if the player candidates for public positions]
			  0: don't vote me, 1: make me lord, 2: make me major
                          INFO: Only players with housing assigned have this entry!
   lastmsg		[{line1,line2,line3}, three lines of text to display upon next login]
   hiredstaff	        [struct, amount of hired but unplaced NPC's]
                         <npcname> := integer, amount of hired but unplaced NPC's
   staffupkeep          [struct, placed NPC's and their serials!]
                         <npcname> := {serial,serial,...}, serials of npcs on duty of that type 
   unrest		[0/1, define if you wish new elections]
   havevote		[0/1, describes if the player can still vote] 
   candidate	        [0/1, describes if the player is a candidate for mayor -> noquit,nobanned]
   //income		[integer, idea to have town mayors assign an income to citizens that is
                              automatically paid from the treassury in order to take over
                              special city tasks (such as librarian or Player-townguard)]
   guildmember          [{{guildid(member),...},{guildid(leader),...}}, guildmembership]
   showguildid          [integer, guild-id - for showing guild belongings on paperdoll!]
 }

 ------------------------------------------------------------------------------------------------------
 
 "upkeepcost"
 
 townstaff
 {
   index                [{TownAdministrator,Townbanker,...}, Lists all available <npcname>'s]
   <npcname>            [struct, upkeepcost details for this npctype]
                         <npcname> := e.g. 'TownBanker' (see npcdesc!)
                         struct.upkeep      [integer, amount of gold the npc costs per week]
                               .services    [{service1,...}, array of serviceprices for this npc]
                               .[<service>] [integer, amount of gold charged for this service]
 }
 
 statics
 {
   freezereport		[{{rep1},{...},...}, report concerning freezing attempts]
                              Format for each entry is {timer, who.name, what, x, y, #amt}
 }
 
 globals
 {
   nexttax		[timer, time when next taxing will occoure (serverrestart?!)
   taxperiod		[integer, seconds between taxes. Default: 604800 = 1 week]
                              WARNING: Change this value for debugging only!
   criticalrng		[integer, radius to check versus static lag (housebuilding)]
   criticalmass		[integer, amount of locked items allowed in radius (see above)]
   lockitembase		[integer, minimum amount of items allowed lockdown]
   lockitempamt		[integer, how many tiles a house must have to lock +1 items]	
 }

 ----------------------------------------------------------

guilds:

g**** //guildserial
{
   guildid		[integer, serial number of guild]
   guildname      	[string, name of guild]
   houseindex 	        [{house1,house2,...}, houses refernce list]
   goldreserve 	        [integer, amount of gold a guild owns]
   leaderindex          [{reference1,reference2,...}, index of player guildleaders references]
   memberindex 	        [{reference1,reference2,...}, index of player member references to datafile]
   description	        [{line1,line2,line3,line4,line5}, guild description]
   founded		[timer, the time it was founded, just for reference]
   transactions         [{{timer, playerserial, playername, unix-timestamp, amount}, ...}, list of transactions]
   hiredstaff	        [struct, amount of hired but unplaced NPC's]
                         <npcname> := integer, amount of hired but unplaced NPC's
   staffupkeep          [struct, placed NPC's and their serials!]
                         <npcname> := {serial,serial,...}, serials of npcs on duty of that type 
 }
