- Development Guide for Cadisman and Cadisman Map editor
- 0.4 BETA release

 1. GAME FILES
  1.1 World files (world #.bd3)
     These are simple text files which have the tileset used (obsolete) and then the map data
     Each world has maps (or screens) from 1 to 100. Each 'map' is 40x25 tiles
     Each tile has a ASCII byte assigned to it. for example G is grass.
     Newer XMS tiles don't have these user friendly arrangments; they are from chr(127) on.
     So, in the BD3 file...
      tileset
      map1
      map2
      map3
      ...
      map100
 
      where mapX looks like...

bbbbbbbbCbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
bFFFFFbbCbbb||///b///////bGGGGGGGGGGGGGG
bFFFFFFFCSGb////|b||/|||/bGGGGGGGGGGGGGG
bFFFFFFFCGb/////b///////bGGGGGGGGGGGGGG
bFFFFFFFCCbbbCCvbbbCbbb/bGGGGGGGGGGGGGG
bGGGGGGGCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
blllllqCCCCCCGGGGCCCCCCCCC{{D{bbbbbb      <-- Example of a map in a bd3 (map1 of world 1)
b@@/l{{{C{Cb/bbbbbbGbbbbbb{CC{b/bb/////
b///@l{{{CCCb///|||bGbTTTTb{CC{b/|/////
b/g/@l{{{CGb/////bbbTTTTbGCCGb////////
b////lS{{CGGb|//|||bTTTTTTbGCCGb///////b
b///CCCCCGbb//bbbbTTTT||bGCCGbbbbbbbbb
blllllGGCGGGqCCGGGbbb///bGCCGb////////
bbbbbbGGCCCGC///////bGCCD/////////
bbbbbbbbCCCCCCCCCCCbbbbbbbbCCGbbbbbbbbb
bbCaCaCCCCCCCCCCCCCCCCCCCCCCCCGGGGGGGGGG
bbbCCCCbCCCbbbbbbCCGGGGGGȋCGGbbbbbbG
bjbCCCCbCCCb///bCCtGGGGGGtCGGbb/TlTbbC
bCCCCCCCCCCb|/||bCCGtCCCtGCGb//TlTTbC
bCCaCaCbCCC/////bCCCCwwwwwCCCCC///TlTTbC
bbbbbbbbCCCbbbbbbCCGtCCCtGCGb//TlTTbC
b{GCCCCCCCCGtGttGCCtGGGGGGGtCGbb/TlTbbC
bll//lllCCCtGttGtCCGGGGGGGGCCGGbbbbbbG
bl/////lCCCbbbbbbCCCGGGGGGGCCGGGGGGGGGG
bl///||lCCC////|bCCCCGGGG{GtCC{{t{t{GGGG

     1.2 UDT Files
       UNIT DATA files are correspondent to the current world you are on. These are a random
       access record file, storing all the units on the map's information, including monsters.
     1.3 PDT
       PLAYER DATA files stores the players inventory, bank, clothes, and various other useful
       bits of information. Just in a list format.
 
    All the files mentioned so far are the ones that are written when saving a game.
    They can either be found in maps\ or player\[playername]\
    Next there are the more specific data files

  2. DATA files
   2.1 Objects.dat - Precious information about the items such as cost, icon index, id, name etc.
   2.2 buyN.dat (where N is a number) is what the different shops sell. Listed is the item's 
       four-letter ID and amount of stock that the shop has. shop 0 is the general stores.
   2.3 labl N.dat - labels and there positions on map N is listed in these files. includes colours.
   2.4 XP.dat and similar named files are random acces files storing the xp level data. 
       rename them for different levels (xp2.dat is the one that the game refers to)
   2.5 monster.dat : random-access. monster ability details (attack, defence, strength)
   2.6 tileset.dat: referred to when all graphics. Most files with *.spr is a ground tile, while
       *.ico are item icons. These pictures are stored under sprites\
   2.7 mix.dat - stores the items needed and produced when mixing (e.g. making fire)
   2.8 fname.dat, lname.dat - names of contractors.


  SECTION 3 - QUESTS and SCRIPTING

   Most of the files referred to here are under quest\

   3.1  *.DAT files are the conversation files   
     3.1.1 LISTING OF SCRIPTING COMMANDS AND THEIR APPLICATION 
       (in order of select case in intrface.bas)

        'clone', 4 arguments: X, Y, NAME1$, NAME2$ : used to clone unit 
           where X and Y are absolute world coordinates
           NAME1$ is the name of the cloned unit.
           NAME2$ is the name of the unit to clone. if a period, the name of the 
             unit that triggers the script is cloned.
           e.g. "clone_106_137_orc_orc"

        'unit', 3 arguments: RANK, NAM$, ICON
           Used to create a unit at 1,1. This unit can then be warped.

        'targetai', 1 argument: N, where N is the unit # of the unit for the player
           to target. if a period is substituted, the speaker is targeted.

        'targetplayer', No args: tells speaker to target the player
           NB: keywords with no args must be followed by an underscore
           e.g.  "targetplayer_" 

        'dmap',No args: redraws current screen position

	'fade', "  : fades screen out

	'palette' " : reloads default palette "data\default.pal"

	'finish' " : tells script executor to stop. very useful

	'msg', 1 arg, MSG$: displays MSG$ in the message area

	'setqs', 1 arg, QS: sets quest stage to QS

	'cmap', 1 arg, MAP: sets current map to MAP. obsolete since scrolling

	'scroll', 2 args, X and Y: coords to set the scroll to. necessary to 
                                   be followed by a dmap to redraw at new position

	'evil' and 'good', both 1 arg 'A'. Adds A amount of good or evil points

	'team', 1 arg: TEAM. Changes player's team to TEAM (e.g. if you become evil)

	'run', 2 args: FILE, SCRIPT. Opens [FILE].cfg and executes external script SCRIPT

	'give', 2 args: ID, N. Same a procedure give. Gives N amount of ID items where ID
               is four-letter item id

	'take', 2 args: ID, N. self-explanatory.

	'gotit' 2 args: ID, N. returns true to an IF statment if you have N amount of ID

	'dead' 1 arg: ID. returns true to an IF statment if unit(ID) is dead

	'mode', 2 args: ID, MODE: sets unit(ID)'s mode to MODE. Can sub in a period to use
               speaker rather than ID
	'xp' , 2 args: SKILL, XP: adds XP to skill number SKILL

	'warp', 3 args: X, Y and UNIT. If UNIT is longer than 3 letters it is treated as the
                          unit's name, otherwise it's the unit's index number. X and Y are the
			  coordinates to warp the unit to.
	'target', 3 args: X,Y, and UNIT. Makes UNIT target(move to) X,Y.
        'rclick', 2 args: X,Y: simulates a right-click at X,Y
	'hilite', 3 args: X,Y,C: hi-lights a circle on the map of colour C and at X,Y
        'rank', 2 args: UNIT and RANK. Makes UNIT's rank=RANK. UNIT can be a period.
	'say', 2 args: NAME and SENTENCE. Triggers NAME to say sentence number SENTENCE.
		NAME can be a period for speaker. Use this only in the script files, not the
                procedure (*.CFG) files.
	'ssay'. As above except should only be used in the procedure CFG files.
	'killall', 1 arg: NAME. Kills all unit that go by the NAME.
	'mode2', 2 args: MODE and NAME. Sets all units of NAME to MODE.
	'allagro', 2 args. NAME and 1 unused. Gets all NAME aggressive.


         Here is a commented example of a conversation file: ('<-' denotes a comment)
	EXAMPLE:
	0    <- current quest stage                           
	    "Hey, what are you doing here?" <- QUESTION
	    "I'm looking for training.","setqs_1&say_._1"  <- note ampersand & to separate statements
	    "Minding my business, sir", "finish_" <- ANSWER 2
	1
	    "Well, Lord Young is the one to see about that."
	    "Who is Lord Young?", "say_._2"
	    "I see. Thank you, sir.","setqs_2&finish_"
           
      So when you talk to a character, the character's conversation file is opened.
      Then the file is scanned through until the current quest stage is found.
      As there are multiple questions for the same QS, the first one is chosen.
      Then the following questions are linked by 'say_._1', for example.


   3.2  Script (*.CFG) files are referred to by the conversation files
	Their format is as follows...

 	[procedure]
	  [statements]
	  ...
	"_end"
 	[procedure]
	  [statements]
	  ...
	"_end"    

         And so on...

         IF CONDITIONS.
            
            if ([condition])
	      [trueStatement]
	      [falseStatement]
          
        If [condition] is true, first statment is executed, otherwise, second is executed.
	Do not put a "_finish" in a script file. only conversation files.
  3.3 Script Cautions
	
	If you have trouble making a script because you get an error, make sure you:
	 - Don't loop script files (call 1 script from another)
	 - Don't overflow the stack by using a 'say' in a script file
	   Every time you have a script keyword,  Script sub is run.
	   If you do this:
	     run_this_script
               this_script
	         run_that_script
	     ... and that script runs script2 and so on and so forth
	   It will overflow: OVERFLOW in module INTRFACE at blah:00blah	 
	 - Be careful. There's no safety devices
	 - If you get an Illegal Function Call when running a script, (error 5)
            it means that the MID$ function went past the end of the string.
            You ain't supplied enough arguments for the specified keyword

    4. MAP EDITOR

       Controls:
         Cursor Keys - scroll maps same as in game
         SpaceBar - Switches between mapEdit mode and UnitEdit mode.
         In mapEdit mode, click to place a tile. Right-click to select a different tile.
         You can also type keys to select a different tile, such as G for grass or 
           C for cobble. PgUp and PgDn also scroll thru the tiles.
          Press 1,2,3, or 4 to choose brush size.
	 In UnitEdit mode, click to select a unit. Press m to move that unit. Press
          c to clone that unit.
         In either mode, press v to see the map data.
	 Press Esc to save. If you wish to quit without saving press Esc or Enter again.
         Press ` (beside 1) to activate console.
         Valid console commands are:
 	info - for information on saving UDTs
	monster - place new monster (unit). Press m to replicate this monster
	unit - place new unit
        plot - set up plot. plots say who owns what land.
	q - yet another (older) way to place new ai.
*********************
	vumap - VUMAP IS A VERY HANDY TOOL
	 To use: just click to paint on the map with the selected tile character. (use keys only).
    		 use - and += to increase/decrease the size of the brush, respectively.
	 Press Esc when u want to save. always save as a bd3 if anything.
********************
	world - allows you to change which world you ar editing and load
      	        other ones. It is only very rudimentary and does not load UDTs.
		I may set up a GUI for loading/saving/changing worlds.
	Thats all.

     5. THE MODULES
          If you want to edit the game, here's a list of the functions, procedures, and 
          important variables... and what they do
      5.1 CDM.BAS - Main Module.
            This is the one that gets all the function declarations, all the variables, all the
            XMS work. If it didnt fit anywhere else it went in here.

	Buyland - fairly useless. tells you how much the plot cost	     
	Changesuit - completely useless
	Choice1 - obsolete
	ChooseClothes - when you have to choose clothes colours at the start of the game
	ClickSqr - called whenever you click. This sub calls rclicksqr for doing the default
		action thingummy.
	CreateGuy - sub used to create units without erasing living ones
	CreateMonster - as above, except loads in stats from the monster.dat
	DoConsole - called when you type something in to the console with com.blahblah
	DrawBar - draws the sidebar with the six tab icons
	DrawPlots - yep you guessed it
	ExitGame - deallocates XMS and quits
	FindSqr - func for finding which unit is at a certain coords
	Fstring - returns a string from strings.dat
	HandleKeys - take a wild guess. Triggered from main module
	INITGAME - loads map, inits heaps of stuff
	LoadLabels - part of the heaps of stuff mentioned previously... to LOADLABELS!
	LoadMonster - loads monsters from monster.dat
	Lpalette - resets default palette
	Rclicksqr - very important. sets unit modes and stuff
	rmenu - that menu that comes up. You put in an array, it spits out your selection
	UseMenu - fairly obsolete
	WhichBar - a func I'd forgotten about 'til i wrote this. chooses wich bar u wanna smelt
	WhichPlot - returns which plot the coords are in.

	5.2 ENGINE.BAS
	 The beast. The rusty old remains of a 3 year old program still can be seen floating in this
 	  very module. Deals mainly with mappage and drawage and movage. very boring.

	CheckAdjacent - sees if unit is on top of or beside a square returns 1 or 2
	Collide - returns -1 if collision at X,Y
	Dist - Pythagora's Thereom used as Distance FOrmula
	DrawGuys - Redraws units.
	DrawMap - redraws map. modes can either draw whole map or 1 tile
	GROUND - func that returns what tiles is at X,Y
	GuyAtSqr - Returns what units are at sqr XY if any
	HmapEditKeys - handdles mapeditmode keys. now built into map editor
	InMap - Checks whether somethign is on-screen
	LoadMaps - loads the maps for the world and draws the pic on videopage 2
	LoadSpr - pic loader
	LoadTiles - processes tileset.dat. Is responsible for long wait at start of game.
	MapGlobalX and Y - these now just refer to Xscroll% and Yscroll%
	MiniDIgit - draws a tiny font
	MINPUT - message input sub
	MoveGuys - Moves all guys. Player's waypoints are followed here
	MSG - func produces a messages. is a global func.
	Pause - pause
	SaveBDT - saves a BD3
	ShowWays - displays waypoints like when you press e
	TraceWays - sets up waypoints for player to use when you move
	UpdateTempMap - phased out
	WhichMap - phased out
	
	5.3 INTRFACE.BAS
		The menus, the dialogues, the script, it's here.

	AddPlayer - not used
	AINPUT - input box function
	Buy - when you click buy it runs. Load buy X.dat files
	GetKW(2-5) - used for processing script strings. have args from 1 to 4
	GetUnit - returns number of unit with NAME
	LoadDlg - the Load Dialogue. Very useful, for load game save game etc
		   looks pretty terrrible though
	LoadGame - i wonder
	SaveGame -
	LoadUDT - loads a UDT specified
	Mainmenu - 
	Manual - loads manual.txt
	Says - this is called when you talk to a character
	Script - see section 3.1
	Trade - just shows a message asking whether you want to buy or sell
	ViewEmployed - shows what people you have working for you

	5.4 ITEMS.BAS is pretty big. It deals with all the items and inventory/bank stuff
	
	AddRock - obsolete
	BankLoop - a sub that loop when viewing the bank
	CheckRocks - an unused sub that slows the game down by 70%
	CheckTabs - checks which tab to display if any and processes keys
	Deposit - deposit to the bank
	Deposit2 - deposit used when not actually at bank 
	EmptySlots - returns how many empty slots in your inventory of 36 slots
	EmptySlotsB - returns how many empty slots in your bank 100 slots
	ForgeBar - what happens when you got to forge a bar
	GetBankNo - item ID number in, bank number out
	GetID - returns the numeric item ID from the string ID
	GetInvNo - item ID number in, inventory number out
	Give - what item and how many to put in inventory. Does not perform much 
	       checking of whether it fits. You have to do that
	Mix - what happens when you right-click on something in the inventory
	ObjectInfo - the little box that appears when you drag an item onto the
		skills book icon in the inventory
	Possess - returns how many items of [id] you posssess
	PossessB - returns how many items of [id] you posssess in your bank
	PossessSubType - returns how many items of [id], group, subgroup you posssess
	ShowBank - display your bank
	ViewBank - what happens when you go to your banker
	ViewInventory - redraw inventory
	ViewInventory2 - redraw bank inventory
	ViewOptions - views the options tab
	ViewSkills - views the skills tab
	ViewTabs - tab viewing redirector
	ViewTiles - not up to much
	ViewWorn - view weapon wearing tab
	Wear - what happens when you press Enter on an inventory item
	Withdraw - withdraw from d bank

	5.4 UNITS.BAS  fighting, level-upping, contracting, moding
	
	AIonAI - when AI fights AI
	BankTake - takes stuff outta your bank acccount
	BLooScreen - when you die this runs
	CheckLevels - sees if you have gained a new level
	EmployMenu - when you talk to a employment agent
	Fight - when you fight a baddie
	FighAI - when a baddie fights back
	GetContract - small dialog. clicking on the item icon changes the deal
	GetMakeID - sees which things each type of employee can make
	LoadObs - loads the items into the array
	ModeGuy. - this is a 16 kb sub. 1st part is unit modes, 2nd is ground modes
		unit modes are what happens when you do something to a unit, say, kill it
		Ground modes are when you use a furnace or anvil or water or wheat.
	ReadSign - is SUPPOSED to tell you whats on the sign
	RefreshInv - makes sure you have no cobwebs (items with amt 0) in your inventory
	Weekly - this is called every so often to give you interest
	YesNo - this is the message box that appears all the time. Enter means yes, Esc means no
	
		
	5.6 GAME VARIABLES

	In the header file (or include file) are the game types and common variables.
	The unit type which is unit(x) as Bunit
	and the Object type or items which is obj(x) as ObjectType

	These two are the most important user-defined type vars.
 	There are some other important ones.
		Primary% and Secondary% are used for pageflipping and are swapped every time
			you DrawMap with mode=1. Secondary% is the unseen page.
		world is the current world and is a single-precision
	Also in the header file are declarations for the XMS handles. They're all integers
		TIME& is the game time and controls movement. A little about this:
	          TIME is incremented in the main module every game loop.
		  When a unit moves or is told to do so, it is given an MVT which is the current
		  TIME plus about 30 loops. So when the TIME is then equal to the Unit's MVT,
 		  the units moves a square and the MVT is reset to TIME+30 again. 
	 	  if the TIME somehow passes the MVT without resetting it, or the MVT is set 
		  behind the TIME, the unit is frozen because the TIME will never equal the 
                  MVT to reset the MVT. This is frozen time.
		Xscroll% and Yscroll% have replaced currentmap completely.


            








        