COMMENT @%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

	Copyright (c) GeoWorks 1992 -- All Rights Reserved

PROJECT:	PC GEOS
MODULE:		Game Library
FILE:		game.def

AUTHOR:		Chris Boyke, Martin Turon

REVISION HISTORY:
	Name	Date		Description
	----	----		-----------
	CDB	3/ 8/92   	Initial version.
	martin	6/24/92		Added timer events
	BCHOW	3/11/93		Added custom high scores.

DESCRIPTION:
	Global definitions for the game library

	$Id: game.def,v 1.1 97/04/04 14:23:13 newdeal Exp $

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%@


SetDef	__GAME

StartLibrary	game




;-----------------------------------------------------------------------------
;	Classes		
;-----------------------------------------------------------------------------


;=============================================================================
;	HighScoreClass.  
;
;This class maintains a file of high scores and displays/updates this
;information during the game.  NOTE: Objects of this class *MUST* be
;on the app's active list, as they open the high score file on
;MSG_META_ATTACH, and close it on MSG_META_DETACH.
;
;=============================================================================
 

HighScoreClass	class	GenControlClass

;-----------------------------------------------------------------------------
;	MESSAGES		
;-----------------------------------------------------------------------------
 

MSG_HIGH_SCORE_ADD_SCORE	message
;
; The score will be added to the high scores file, if it passes the
; required criteria
;
; Context:	High score update mechanism
; Source:	usually the application
; Destination:  a HighScoreControlClass object
; Interception: This shouldn't be subclassed.  See
; 		MSG_HIGH_SCORE_TEST_SCORE below, for subclassing
;
; Pass:		dx:cx - score or pointer to score info, if subclassed
;		bp - block containing text string w/extra information
;		     				(freed by method handler)
;		     	 - or -
;		     0 for no extra information
;			
; Return:	carry set if score was added
;			ax - Destroyed
;		clear if score not added
;			ax - HighScoreScoreNotAddedReason
;
; Destroyed:	see Return:
;
;

HighScoreNotAddedReason	etype	word, 0
	;   Couldn't open the high score file
	;
	HSNAR_COULDNT_OPEN_FILE		enum HighScoreNotAddedReason

	;   Score wasn't good enough to be a high score
	;
	HSNAR_SCORE_NOT_GOOD_ENOUGH 	enum HighScoreNotAddedReason

	;    Player hit cancel or didn't enter in characters and
	;    hit ok
	HSNAR_NAME_NOT_ENTERED	 	enum HighScoreNotAddedReason

	;    In HSA_ONE_SCORE_PER_NAME mode, if the player didn't
	;    their personal previous high score
	;
	HSNAR_DIDNT_BEAT_EXISTING_PERSONAL_SCORE enum HighScoreNotAddedReason

	;    While the player was entering their name, somebody else	
	;    got a high score that pushed our player out of the
	;    the high score list. This is very rare.
	;
	HSNAR_HOSED_BY_OTHER_HIGH_SCORE	enum HighScoreNotAddedReason

	;    For backwards compatibility.
	HSNAR_NO_REASON			enum HighScoreNotAddedReason, MSG_HIGH_SCORE_ADD_SCORE

MSG_HIGH_SCORE_GET_NAME		message
;
;	Gets the name for the high score list. The default behavior will
;	be to put up a box asking for the user's name.
;
;	Context: High score update mechanism
;	Source: HighScoreControlClass object
;	Destination: HighScoreControlClass object
;	Interception: If the app wants to provide its own way of getting the
;		      user's name (e.g. use a character's name, if in a
;		      role-playing game)
;	Pass: dx:bp - ptr to buffer to hold MAX_USER_NAME_SIZE characters
;		      plus one null
;		      (if no non-nulls returned in buffer, then no score will
;		       be added).
;
;	Return:    cx = string length (not counting null)
;	Destroyed: ax, dx, bp
;

MSG_HIGH_SCORE_SHOW_SCORES	message
; 
; Show the high scores.
;
;
; 	PASS: cx - 0-based score to highlight, or -1 to not highlight any score
;	DESTROYED: nothing
; 	RETURN: nothing

MSG_HIGH_SCORE_FORMAT_SCORE	message
; 
; Formats the passed score according to the passed ScoreType.
; Apps can intercept this to provide their own formatting
;
;
; 	PASS: ss:bp - FormatScoreParams
;	DESTROYED: nothing
; 	RETURN: nothing

FormatScoreParams	struct
	FSP_score	dword
	; The score value that we want to display

	FSP_dest	fptr.char
	; Ptr to buffer to hold SCORE_BUFFER_SIZE-1 characters
FormatScoreParams	ends

SCORE_BUFFER_SIZE	equ	DATE_TIME_BUFFER_SIZE

ScoreType	etype	byte
	ST_POINTS			enum	ScoreType
	ST_ELAPSED_TIME			enum	ScoreType
	ST_MONEY			enum	ScoreType

HighScoreAttributes	record
	HSA_LOW_SCORE_IS_BETTER:1
	;If set, then the high score list is sorted in reverse order
	; (lower scores are better - golf style)
	
	HSA_ONE_SCORE_PER_NAME:1
	; If present, each name will be allowed to show up in the HighScore 
	; list only once - if the user already has a highscore higher than 
	; his current one, it won't add one.
	;
	; You will probably want to get the user name ahead of time, and 
	; subclass MSG_HIGH_SCORE_GET_NAME to avoid asking him what his name 
	; is. Otherwise, if the user has a score in the top 10, but he already
	; has a higher score in the highscore list, it'll prompt him to enter 
	; his name, then it'll figure out that the score won't be added, 
	; leaving him confused and hurt when his score doesn't show up.
	;
	:6
HighScoreAttributes	end
;-----------------------------------------------------------------------------
;	INSTANCE DATA		
;-----------------------------------------------------------------------------
 
 
	HSI_fileName	lptr.char
	; long name of high scores file

	HSI_fileHandle	hptr
	; handle of high score file

	HSI_creator	GeodeToken
	; creator token

	HSI_highScoreTitle	lptr.visMoniker
	; Title of the "High Score Display" box

	HSI_highScoreLine1	lptr.visMoniker
	HSI_highScoreLine2	lptr.visMoniker
	HSI_highScoreLine3	lptr.visMoniker
	HSI_highScoreLine4	lptr.visMoniker
	; lines to display in the box that reads in the user name


	HSI_scoreType		ScoreType
	; How to display the score

	HSI_attrs		HighScoreAttributes

MAX_HIGH_SCORES equ 10
; Max # entries in file

HIGH_SCORE_DEFAULT_FEATURES	equ	mask HSF_DATE or mask HSF_SCORE or mask HSF_SHOW_HIGH_SCORES_TRIGGER

HighScoreFeatures	record
	HSF_SCORE:1
	; Display scores
	HSF_DATE:1
	; Display the date that the high score was added
	HSF_EXTRA_DATA:1
	; Display extra data
	HSF_SHOW_HIGH_SCORES_TRIGGER:1
	; Add a trigger that displays the high scores
HighScoreFeatures	end




; The High Score data file is a VM file consisting of a map item which
; is a chunk array of HighScoreArrayElement structures.
;
HighScoreArrayElement	struc
	HSAE_name	dword	; DB item of name
	HSAE_score	dword	; DB item of score
	HSAE_extra	dword	; DB item of extra data
	HSAE_year	word
	HSAE_month	byte
	HSAE_day	byte
HighScoreArrayElement	ends

;-----------------------------------------------------------------------------
;	VARDATA		
;-----------------------------------------------------------------------------
ATTR_HIGH_SCORE_SHOW_SCORES_TRIGGER_MONIKER	vardata	lptr
; This is the moniker of the "Show High Scores" trigger. It should be
; the chunk of a visMoniker.

ATTR_HIGH_SCORE_NAME_TITLE_MONIKER		vardata lptr.char
ATTR_HIGH_SCORE_DATE_TITLE_MONIKER		vardata lptr.char
ATTR_HIGH_SCORE_SCORE_TITLE_MONIKER		vardata lptr.char
ATTR_HIGH_SCORE_EXTRA_TITLE_MONIKER		vardata lptr.char
; This allows the app to override what string will show up above the
; score/extra data columns. It should be a chunk containing a string
; (not an actual moniker).
;

protominor HighScoreNoSound

ATTR_HIGH_SCORE_DONT_PLAY_SOUND			vardata
; This allows the app to prevent the high score controller from playing
; a reward sound when the user has achieved a high score.  An Application's
; sound mute feature can be propogated thru setting/resetting this attribute.

protoreset

HighScoreClass	endc


;
; GenApplication GCN lists to be placed on:
;	GAGCNLT_SELF_LOAD_OPTIONS

GameStatusControlClass	class	GenControlClass

GameStatusControlClass	endc
;-----------------------------------------------------------------------------
;	etypes		
;-----------------------------------------------------------------------------

GameStatus	etype	byte
	GS_NULL		enum	GameStatus	;The status when app is first
						; started.
	GS_PAUSED	enum	GameStatus	;Status when game is paused
	GS_TEMP_PAUSED	enum	GameStatus	;Temporary pause
	GS_MINIMIZED	enum	GameStatus	;Status when minimized
	GS_RUNNING	enum	GameStatus
	GS_RESTARTING	enum	GameStatus
	GS_GAME_OVER	enum	GameStatus
	GS_STOPPED	enum	GameStatus


;-----------------------------------------------------------------------------
;	Structures		
;-----------------------------------------------------------------------------
 
; Gee, a one-byte block!
 
GameStatusNotificationBlock	struc
	GSNB_status	GameStatus
GameStatusNotificationBlock	ends

;-----------------------------------------------------------------------------
;	Records		
;-----------------------------------------------------------------------------
 
GameStatusControlFeatures	record
	GSCF_START:1
	GSCF_ABORT:1
	GSCF_PAUSE:1		; If you set PAUSE, you must also set
				; CONTINUE 
	GSCF_CONTINUE:1
GameStatusControlFeatures	end


GameContentClass	class	VisContentClass

;-----------------------------------------------------------------------------
;	Messages		
;-----------------------------------------------------------------------------
 

MSG_GAME_CONTENT_START_GAME	message
;
; Start a new game.  Sets GameStatus to GS_RUNNING.  Note -- this can
; be sent to a currently running game, in which case the proper
; behavior is to begin a new game.
;
; Context:	Sent when the user chooses "Start Game" in the game
;		menu.
; Source:	game menu
; Destination:  Any GameContent object
; Interception:	Default behavior is to seed the random number
;		generator -- subclass will want to add other behavior
;
; Pass:		nothing 
;			
; Return:	nothing 
;
; Destroyed:	ax,cx,dx,bp


MSG_GAME_CONTENT_PAUSE_GAME	message
; Pause a currently-running game.  Changes GameStatus to GS_PAUSED,
; and enables the "Continue" button.  Does nothing if game currently
; isn't running.
;
;
; Source:	Sent by the GameControl object
; Destination:  The target GameContent
; Interception: Subclasser will want to give some notification to the
; 		user that the game is paused.
;
; Pass:		nothing 
;			
; Return:	nothing 
;
; Destroyed:	ax,cx,dx,bp
;

MSG_GAME_CONTENT_CONTINUE_GAME	message
; Continue a paused game.  Does nothing if game isn't currently paused
;
; Source:	Send by GameControl
; Destination:  Target gameContent
; Interception: subclass will remove "game paused" display, if any,
; 		and 
;
; Pass:		nothing 
;			
; Return:	nothing 
;
; Destroyed:	ax,cx,dx,bp
;
;
;
;

MSG_GAME_CONTENT_ABORT_GAME	message
; Abort the current game.  Game is in same state as when app is first
; launched. 
;
; Source:	GameControl
; Destination:  the target GameContent
; Interception: Subclass should make sure game is ended cleanly
;
; Pass:		nothing 
;			
; Return:	nothing 
;
; Destroyed:	ax,cx,dx,bp
;


MSG_GAME_CONTENT_GAME_OVER	message
; End the game.  
;
; Context:	This message should be sent to the content when the
; 		game ends (ie, user dies or wins)
; Source:	???
; Destination:  GameContent
; Interception: subclass should play an appropriate win or lose
; 		sequence.  Pass/Return/Destroyed values are up to the
;		caller and the subclass -- there is no default behavior

;
; Pass:		???
;			
; Return:	???
;
; Destroyed:	???
;

MSG_GAME_CONTENT_TIMER_TICK	message
; This message is sent repeatedly by the system as long as the game is running.
; The interval between ticks is determined by GCI_timerInterval (which is the
; number of 1/60 seconds.)
;
; To stop further timer tick messages, change the game status to not running
; (by aborting, pausing, etc.)
;
; Context:	Sent on each time interval when the game is running
; Source:	Sent by system timer
; Destination:  Any GameContentClass object
; Interception: Default behavior is to register for another timer tick with the
;		system.  Subclass can intercept this message to do timing stuff
;		(e.g. make a move).  Should call superclass somewhere in
;		your handler.
;
; Pass:		cxdx	= tick count (returned by TimerGetCount)
;			
; Return:	nothing
;
; Destroyed:	ax, cx, dx, bp
;

MSG_GAME_CONTENT_TEMP_PAUSE		message
; Temporarily pause the game, for example, when the content loses the
; focus.

MSG_GAME_CONTENT_END_TEMP_PAUSE		message
; Resume the game

;-----------------------------------------------------------------------------
;	Instance data		
;-----------------------------------------------------------------------------
 
	GCI_status		GameStatus
	GCI_gstate		hptr.GState
	GCI_timerHandle		hptr
	GCI_timerID		word
	GCI_timerInterval	word	; # of 1/60 seconds between timer ticks
	GCI_baseWidth		word
	GCI_baseHeight		word

GameContentClass	endc
 
;-----------------------------------------------------------------------------
;	Exported routines		
;-----------------------------------------------------------------------------
 
global GameRandom:far

EndLibrary	game
