Modules/game pawn/Usage

Define pawn's sprites

The visual of a pawn is defined by one or more sprite layers. The Game_Sprite structure allows to define the parameters of each layer : The X/Y offset of the layer relative to the Pawn position, the pattern number offset from the pattern number defined in the animation, the sprite color and a special flag for display.

Example:

A two color sprite (2 layer): ‎

const Game_Sprite g_SpriteLayers[] =
{
	{ 0,  0, 0,  COLOR_WHITE, 0 }, // Sprite position offset: 0,0. Pattern offset: 0. Color: White. No special flag
	{ 0, -8, 4,  COLOR_GRAY, 0 }, // Sprite position offset: 0,-8. Pattern offset: 4. Color: Gray. No special flag
};‎

Define pawn's animations

Each animation is defined by a list of Game_Frame structures that determine : The pattern number of the animation frame, the duration of the frame in number of display cycles, and a function to call when the character reach a given frame of the animation. Create a structure for each animation. You have to provide a complete list of all action that the pawn can do.

Example:

Push animation with function to trigger ‎

const Game_Frame g_FramesPunch[] =
{
	{ 0,	4,	NULL}, // Display pattern 0 for 4 render cycles
	{ 8,	4,	NULL},
	{ 8,	1,	DoPunch }, // call function DoPunch() when Pawn is displaying this frame
	{ 16,	4,	NULL },
	{ 24,	4,	NULL },
};‎

Define pawn's actions

An action is defined in the Game_Action structure and include a animation plus some parameters like the looping of the animation or a flag to determine if the action can be interrupted.

Examples: ‎

const Game_Action g_AnimActions[] =
{ //  Frames        Number                  Loop?  Interrupt?
	{ g_FramesIdle,  numberof(g_FramesIdle), TRUE,  TRUE },
	{ g_FramesMove,  numberof(g_FramesMove), TRUE,  TRUE },
	{ g_FramesJump,  numberof(g_FramesJump), TRUE,  TRUE },
	{ g_FramesPunch, numberof(g_FramesFall), FALSE, FALSE }, // Play once, can't be interrupted
};‎

Initialize pawn

All pawn management is carried out via a Game_Pawn structure (each pawn must have its own structure). Once the sprite and animation data have been defined, the pawn must be initialized.

‎Examples: ‎‎

GamePawn_Initialize(&g_PlayerPawn, g_SpriteLayers, numberof(g_SpriteLayers), 0, g_AnimActions); // Initialize pawn structure
GamePawn_SetPosition(&g_PlayerPawn, 16, 16); // Set pawn position

Initialize pawn

If you want to use the physics and collision functionalities, you must set the GAMEPAWN_USE_PHYSICS option in your library configuration file (msxgl_config.h). Next, you need to define two callback functions:

• one that determines whether a given block of background is a blocker or not,
• and the other which receives collision-related events (touching the screen edge, falling, etc.).

Examples: ‎‎

// Physics callback
void PhysicsEvent(u8 event, u8 tile)
{
	switch(event)
	{
	case PAWN_PHYSICS_BORDER_DOWN:
	case PAWN_PHYSICS_BORDER_RIGHT:
	case PAWN_PHYSICS_COL_DOWN: // Handle downward collisions 
	case PAWN_PHYSICS_COL_UP: // Handle upward collisions
	case PAWN_PHYSICS_FALL: // Handle falling
		break;
	};
}

// Collision callback
bool PhysicsCollision(u8 tile)
{
	return (tile & 0x80);
}

/* ... */

GamePawn_InitializePhysics(&g_PlayerPawn, PhysicsEvent, PhysicsCollision, 16, 16); // ‎Initialize pawn physics