///////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////

				    IA::Astar  -  Information file
						v0.9a


Thank you for using IA::Astar ! This dll will provide you an easy access to pathfinding with 
the algorithm A*.

This help file will be translated into french in about 1 week.

I. Installation---------------------------------------------------------------------------------

Put the *.dll file in the directory "\Compiler\plugin-user" (in the DarkBASIC folder) and put 
the *.ini file in the directory "\Editor\Keywords" .

Now you can run the IDE and developp programs using IA::Astar!


II.Commands and errors codes--------------------------------------------------------------------

In IA::Astar you have 15 commands, but the number of commands is likely to rise.
You can use up to 4 pathmap, from number 0 to number 3.

	1.Commands Index
	
	__________Initialization commands:

		/!\ YOU MUST CALL THIS TWO COMMANDS WHEN YOU USE IA::Astar IN A PROJECT
	

	int AS_SET ASTAR (Number of cells (width), Number of cells (height), Tile size)
		This command set the size of each pathmap. Please note that all pathmap have 
		the same size.
		/!\ The parameters are the number of cell, not the size in 2D or 3D world!

		For example if you write :
					
					result=as_set astar(128,128,1)

		this will set up the whole pathmap to 128*128 cells.
		The tilesize parameter is useful when you want to retrieve a coordinate in DbPro units.

	
	void AS_START PATHFINDER *no parameters*
		This commands intialize other arrays.



	__________Freeing dll command:	
	

	void AS_END PATHFINDER *no parameters*
		This command free the memory when you want to close your program.
		Similar to "Delete ..." command.



	__________Pathmaps operations:

	
	int AS_READ PATHMAP (Filename, Pathmap number)
		This command load a file to the specified pathmap.

	int AS_WRITE PATHMAP (Filename, Pathmap number)
		This command write the specified pathmap into a file.		

	int AS_READ PATHMAP VALUE (Pathmap number, Coordinate X in pathmap, Coordinate Y in pathmap)
		This command rea the value wroten in the specified pathmap at the indicated coordinates.
		Actually the coordinates MUST be the coordinates of the cell in the pathmap.
		(this command doesn't use the Tilesize parameter)

	int AS_WRITE PATHMAP VALUE (Pathmap number, Coordinate X in pathmap, Coordinate Y in pathmap, Value to write)
		This command write a value between 0 and 255 in the specified cell of a pathmap.
		Actually the coordinates MUST be the coordinates of the cell in the pathmap.
		(this command doesn't use the Tilesize parameter)
		


	__________General informations:

	 
	int AS_GET HEIGHT *no parameters*
		This command returns the height of the pathfinder, which can be change using AS_SET ASTAR.

	int AS_GET WIDTH *no parameters*
		This command returns the width of the pathfinder, which can be change using AS_SET ASTAR.

	int AS_GET TILE SIZE *no parameters*
		This command returns the Tilesize parameter of the pathfinder, which can be change using AS_SET ASTAR.
		Please note that only these commands use this parameter:
			AS_SEARCH PATH
			AS_GET WAYTILE X
			AS_GET WAYTILE Y



	__________Pathfinding commands:


	int AS_GET PATH STATE (Path ID)
		This command returns the path state of the path indicated.
		The value is 0 if the path is not already searched, 1 if the path exist
		(means the pathfinder has found a path) and 2 if the pathfinder has not found a path.
		It is better to call this command after searching a path, because you can easily know if 
		the way between 2 points exists (before trying to draw this way).

	int AS_GET TOTAL WAYTILES (Path ID)
		This command returns the number of waytiles in the path specified.
		You can use this command to avoid errors or simply to move an object along the path

	int AS_SEARCH PATH (Path ID, Pathmap number, Start X (in real units), Start Y (in real units), End X (in real units), End Y (in real units))
		This command search a (potential) way between 2 points.
		The PathID parameter is the path number where the path will be saved.
		The Pathmap number is the number of the pathmap which will be used to find a way.
		Start X, Start Y, End X, End Y are in real units (DbPro units), this means that
		the Tilesize parameter intervenes to get cell coordinates before computing the path.

	int AS_GET WAYTILE X (Path ID, Location on path)
		This command returns the position x of the cell specified by the location on path.
		The location on path is between 0 and the value returned by AS_GET TOTAL WAYTILES
		The last cell on the path is the targeted cell.

	int AS_GET WAYTILE Y (Path ID, Location on path)
		This command returns the position y of the cell specified by the location on path.
		The location on path is between 0 and the value returned by AS_GET TOTAL WAYTILES
		The last cell on the path is the targeted cell.

	

	2.Errors code
	
	The commands returns value which can be error code.
	An error code is always <0.
	
	Here is the list of errors codes:

	-500 : unable to allocate memory - means that you cannot continue.
	-499 : incorrect parameter(s)

	-400 : the specified pathmap already exist
	-401 : the specified pathmap doesn't exist
	-420 : no waytile to read

	-300 : incorrect pathmap number ( int pathmap is between 0 and 3)
	-301 : out-of-range coordinates
	-302 : start cell coordinates out-of-range
	-320 : unable to open file
	-360 : incorrect path number (id must be between 0 and 9000 )	


III.Other help file

You can find in the "\help" directory an example using 2D.
Please note that this dll can be adapted easily to a 3D environment, but I have no example on this point (lack of time...)


IV.License

This dll is developped by Darktib.

This dll is not open-source.

You can to use this software for both commercial and non-commercial products, provided you abide by the following rules.

_You cannot modify, translate, reverse engineer, decompile, or disassemble this software in any shape or form.
_You cannot sell this dll, unless the dll is only a part of your product.
_You may not redistribute versions of the software modified by anyone but the author himself.
_You must say in your project/product that you use this dll, in exemple in the 'About ...' window.

The dll is provided "as-is", without any warranties of any kind, expressed or implied. You use at your own risk. The author will not be liable for data loss, damages, loss of profits or any other kind of loss while using or misusing this software.

It would be polite to inform me when you want to distribute a commercial product, or a non-commercial important product.

Copyright (c) 2007 Darktib

V.Thanks

I would like to thanks Patrick Lester , because he has learned me how to use Astar algorithm, with his excellent article
at the address : http://www.policyalmanac.org/games/aStarTutorial.htm.

And I would thank all Darkbasic user, for helping me during the developpment.


Visit the page : http://forum.thegamecreators.com/?m=forum_view&t=114240&b=5 to know all about future versions !


~Darktib

(Sorry if my english is bad, I'm french.)
