RPG TOOLKIT DEVELOPMENT SYSTEM, 3.0 HISTORY

RPG Toolkit Development System 3.0 alpha
Instructions and What's New
May 22, 2003 
Copyright 2003 by Christopher Matthews

Well, it's been 9 months in the making, and here's the first public release of TK3.
It's an alpha release, so it's not perfect (yet).  The speed and stability
will changes as we move towards a 3.0 release.  See the following for more info...

Upgrading your version 2 game
-----------------------------
-I *highly* suggest that you keep a backup copy of the version 2 game, since TK3 will
 change a lot of files on you.
-Let's say your game is called MyGame:
	-Copy the contents of the Toolkit2\Game\MyGame\ folder to Toolkit3\Game\MyGame\
	-Copy Toolkit2\Main\MyGame.gam to Toolkit3\Main\
	-Copy the files in Toolkit2\Plugin\ to Toolkit3\Game\MyGame\Plugin\
		-*DO NOT* copy multiplug.  Yo shouldn't use multiplug with version 3.
	-Copy the files in Toolkit3\Game\Basic\Plugin\ to Toolkit3\Game\MyGame\Plugin\
	-You may have to manually set the plugins you wish to use by editing your main file.
-That should do it.
-When files are openend, they will be converted for you.  Some changes from v2 to v3:
	-When a character, item or enemy is loaded, their graphics are converted to Tile Bitmap 
	 files (*.tbm) saved in the Bitmap\ folder, ansd the animations are converted to 
	 Animation (*.anm) files, saved in the Misc\ folder.
	-It wouldn't hurt to open your players/items/enemies and save them in the editor to
	 force this process to occur.  Otherwise it is done automatically when you run trans3

What's done
-----------
-Completely re-done graphics system using DirectX.
-Largely re-done interface for the editor, including MDI.
-New RPGCode commands.
-New [true] multitasking system.
-Updated plugin system.
-Menu and Fight plugins.
-Basic setup utility

What needs to be done
---------------------
-Lots of testing.
-Help files need to be written.
-Finalized plugin SDK should be released.
-System needs to be made localizable (currently only works in English).
-Isometric boards need to be improved *a lot*.  It's very primitive at the 
 moment.
-#Prompt, #CallShop, #CallPlayerSwap commands need to be updated.
-Update the audio system.  Currently I'm considering Audiere and FMOD.
-Increase number of items per board.
-Update UI for the editor.
-New demo game.
-Need lots of new default media -- can anyone help?
-Update the RPGCode editor with components from VorteX (currently 
 it uses no VorteX code).
-Pixel-based movement.

New RPGCode stuff
-----------------
-We now have true multitasking!  You'll see that your RPGCode programs truly
 do run concurrently (players/npcs walk at the same time, etc).
-RPGCode3 has some new tricks.  The biggest is the ability to return values from 
 methods.  For example, you can now do:
 
 #a$ = Wait()
 
 instead of:
 
 #Wait(a$)
 
-Commands that return values can still take a variable in their arguments, but it is now 
 optional.  The preferred way is to return the value into the variable on the left hand side of
 an '=' sign.

-New RPGCode commands:

MISC COMMANDS:
-------------
#AutoCommand
	-Removes the requirement to use the '#' symbol in front of every command.
	-Put this at the top of every program :)
	-Example:
		#AutoCommand
		
		Mwin("Hello!")
		a$ = wait()

#GameSpeed(speed!)
	-Replaces #CharacterSpeed
	-Defines the overall game speed.
	-if speed! == 3, then the game will run it's fastest
	-if speed! == 0, the game will run it's slowest.


SCOPE COMMANDS:
---------------
-RPGCode3 defines *scope* for variables.  Scope is just a way of managing where variables can
 be read from.

-In Toolkit2, all variables were *Global*.  This means that if you set a variable in one 
 program, it could be read in a different program anytime in the game.

-TK3 still defauls all variables to global scope, but it now has the ability to set
 varaibles to *Local* scope.
 
-Local variables are variables that exist only while the program that created them
 is running.  When that program ends, those variables are destroyed and cannot
 be read by a different program.

-What's more, methods can have their own local variables that cannot be ready by 
 parts of the same program that lie outside the method.
 
#value$ = Local( varName$ [, value$] )
#value! = Local( varName! [, value!] )
	-Create a local variable, or explicitly get it's value.
	-Example:
		#AutoCommand
		
		*Create a local variable
		local( myLocalVar! )
		
		*show the value of that variable (will be 0)
		mwin( "<myLocalVar!>")
		
		*explicitly show the avlue of that variable:
		mwin( "<local(myLocalVar!)>")
		wait()
		end

#value$ = Global( varName$ [, value$] )
#value! = Global( varName! [, value!] )
	-Create a global variable, or explicitly get it's value.
	-Example:
		#AutoCommand
		
		*Create a gloabl variable
		global( myGlobalVar! )
		
		*show the value of that variable (will be 0)
		mwin( "<myGlobalVar!>")
		
		*explicitly show the avlue of that variable:
		mwin( "<global(myGlobalVar!)>")
		wait()
		end

-It is good practice to explicitly declare all of your variables as local or global 
 before using them.  For example:
 
 #AutoCommand
 
 local(name$)
 name$ = prompt("What is your name?")
 mwin("Hello, <name$>")
 wait()
 end
 
 -Creates a local variable called name$.  When this program ends, name$ is destroyed.


CURSOR MAP COMANDS:
-------------------
-Cursor maps are a fancy way to create a menu.  They allow you to specifiy 'hotspots'
 on the screen that the user can move a pointer between with the keyboard or mouse.
 
#id! = CreateCursorMap( [id!] )
	-Create a cursor map.
	-Return: id of cursor map created.
	
#KillCursorMap( id! )
	-Destroy a previously created cursor map.

#CursorMapAdd( x!, y!, id! )
	-Add a hotspot to the cursor map.
	-x! and y! are the screen coordinates where the hotspot exists.
	-id! is the id of the cursor map to add it to.
	
#selected! = CursorMapRun( id! [, selected!] )
	-Run a cursor map.  Allows the user to choose between the hotspots
	 on the screen.
	-Returns the index of the selected hotspot (in the order they were created)
	 starting at 0.  Returns -1 if the user pressed ESC.
	 
Cursor Map Example:
done! = 0
while ( done! == 0 )
{
	text( 17, 10.5, "New Game" )
	text( 17, 12, "Load Game" )
	text( 17, 13.5, "Quit" )

	cMap! = CreateCursorMap()
	CursorMapAdd( 295, 180, cMap! )
	CursorMapAdd( 295, 210, cMap! )
	CursorMapAdd( 295, 230, cMap! )
	res! = CursorMapRun( cMap! )
	KillCursorMap( cMap! )

	if ( res! == 0 )
	{
		* new game
		history()
		done! = 1
		end
	}
	if ( res! == 1 )
	{
		* load game
	        dirsav(dest$)
	        if(dest$~="CANCEL")
	        {
	            load(dest$)
	            done!=1
	            end
	        }
	}
	if ( res! == 2 )
	{
		* new game
		dos
		done! = 1
		end
	}
}
end


CANVAS COMMANDS:
----------------
-Canvases are offscreen drawing areas.  You can later draw these onto the screen.

#id! = CreateCanvas( sizex!, sizey! [, id!] )
	-Create a new canvas of size sizex! X sizey! ( in pixels)
	-Returns the id of the canvas you can later refer to.
	
#KillCanvas( id! )
	-Destroy an offscreen canvas.
	-Remember to kill all canvases you create when you are done with them.
	 Offscreen canvases take up enough memory that you can really start slowing
	 things down if you're not dilligent.
	 
#DrawCanvas( id!, x!, y! [, sizex!, sizey! [, destId!] ] )
	-Draw a canvas, either to the screen or another canvas
	-id! is the canvas to draw
	-x! and y! are the location to draw to.
	-if specified, sizex! and sizey! are the size in pixels to scale it to.
	-if specified, destId! is the id of the destination canvas to draw to.
	 If not specified, this is the screen.
	 
-Many drawing commands allow you to use canvases.
-For instance:
	*draw title.jpg to the screen...
	#Bitmap( "title.jpg" )
	
	#id! = CreateCanvas( 50, 50 )
	*Draw title.jpg to canvas id!
	#Bitmap( "title.jpg", id! )
	
	#DrawCanvas( id!, 10, 10 )
	#KillCanvas( id! )
	
	
THREAD COMMANDS:
----------------
-These commands manage threads.  Threads are just multitasking RPGCode programs...

id! = #Thread( program$, persist![, id!] )
	-Create a multitasking thread.
		-program$ is the name of the program to run.
		-if persist! == 1, then the thread continues to run after the player has
		 left this board.
		-if persist! == 0, then the thread will stop when the player leaves this board.
		-id! is an optional variable that will hold the return value.  The preferred way is to
		 leave this out and assign the return value to the variable onthe left hand side of the
		 '=' sign.
	-Returns: An id you can use to refer to this thread in the future.
	-Example:
		#id! = CreateThread( "mythread.prg", 0 )
		-Creates a thread from the program mythread.prg, which will run only as long as 
		 the user is on this board.  We will later refer to this thread with the
		 value stored in id!
		 
#KillThread( id! )
	-Stop execution of a thread
	-id! is the id of the thread to stop.
	-Example:
		KillThread( id! )
		-Stops the thread created in the last example.
		
id! = #GetThreadId( [id!] )
	-Get the thread id of the currently running program.
	-id! is an optional value.  The preferred way is to get the return value on the left 
	 hand side of the '=' sign.
	-Returns: The thread id, or -1 if the program running is not a multitasking thread.
	-Example:
		in mythread.prg:
		
		#id! = GetThreadId()
		#KillThread( id! )	*equivalent to #end
		-When the mythread.prg starts to run, it can call this to get it's own thread id.

#ThreadSleep( id!, duration! )
	-Put a thread to sleep for a certain amount of time.
	-id! is the id of the thread to put to sleep
	-duration! is the time in seconds for the thread to sleep
	-When a thread is asleep, it does not execute and requires no CPU time.
	-Example:
		#ThreadSleep( GetThreadId(), 10 )
		#MWin( "10 seconds later!" )
		-Puts the current thread to sleep for 10 seconds.  
		-When 10 seconds is up, execution continues as normal.
		
#ThreadWake( id! )
	-Force a sleeping thread to wake up
	-id! is the id of the thread to wake up.
	-If a thread has been put to sleep, this command will start it executing again

#remain! = ThreadSleepRemaining( id! [, remain!] )
	-Find how much time is left in a sleeping thread.

#ret$ = TellThread( id!, command$ [, ret$] )
#ret! = TellThread( id!, command$ [, ret!] )
	-Call a command inside a thread from outside the thread.
	-Allows one thread to communicate with another.
	-id! is the id of the thread to communicate with
	-command$ is an RPGCode command to run inside that thread
	-The return value from that command is returned to us.
	-Example:
		Say we have a running thread, and it's id is stored in the 
		variable id!
		
		That thread has a method called #talk that retirns a number.
		
		We can call that #talk method from a different program:
		
		#ret! = TellThread( id!, "#Talk()" )