Modules/game pawn

game_pawn

Code: game_pawn.h

Category: Gameplay

Dependencies:

• vdp
• memory

Samples:

• s_game

✍

The game_pawn module handle character animation, rendering, collision and physics.

This module offer several structures the user can use to configure a pawn (a player, an enemy or any moving object) for rendering (multi-layers and flip/flap) and movement.

Once the pawn has been configured, functions can be used to change its state (action, position, etc.) and an update function can be used to apply these changes and display them on the screen.

Usage

To use this module, include "game_pawn.h" in your source code, and add "game_pawn" to the modules list (LibModules) in your project's configuration file (project_config.js).

✍

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

Samples

See module use cases in the sample programs:

• s_game

Settings

✍

Library configuration (msxgl_config.h):

// GamePawn setting
#define GAMEPAWN_ID_PER_LAYER		TRUE	// Set sprite ID for each layer (otherwise set per pawn)
#define GAMEPAWN_USE_PHYSICS		TRUE	// Add physics and collision features
// Pawn's bound (can be fixed for all pawn, or setable for each one)
#define GAMEPAWN_BOUND_X			16
#define GAMEPAWN_BOUND_Y			16
// Collision position options for each pawn's side
// - GAMEPAWN_COL_0
// - GAMEPAWN_COL_25
// - GAMEPAWN_COL_50
// - GAMEPAWN_COL_75
// - GAMEPAWN_COL_100
#define GAMEPAWN_COL_DOWN			(GAMEPAWN_COL_25|GAMEPAWN_COL_75)
#define GAMEPAWN_COL_UP				GAMEPAWN_COL_50
#define GAMEPAWN_COL_RIGHT			GAMEPAWN_COL_50
#define GAMEPAWN_COL_LEFT			GAMEPAWN_COL_50
// Options to determine which border collide or trigger events
// - GAMEPAWN_BORDER_NONE
// - GAMEPAWN_BORDER_DOWN
// - GAMEPAWN_BORDER_UP
// - GAMEPAWN_BORDER_RIGHT
// - GAMEPAWN_BORDER_LEFT
#define GAMEPAWN_BORDER_EVENT		(GAMEPAWN_BORDER_DOWN|GAMEPAWN_BORDER_LEFT|GAMEPAWN_BORDER_RIGHT)
#define GAMEPAWN_BORDER_BLOCK		(GAMEPAWN_BORDER_UP|GAMEPAWN_BORDER_DOWN|GAMEPAWN_BORDER_LEFT|GAMEPAWN_BORDER_RIGHT)
// Top/bottom border position (in pixel)
#define GAMEPAWN_BORDER_MIN_Y		0		// High border Y coordinade
#define GAMEPAWN_BORDER_MAX_Y		184		// Low border Y coordinate
#define GAMEPAWN_FORCE_SM1			FALSE	// Force the use sprite mode 1 (for MSX2) 
#define GAMEPAWN_USE_VRAM_COL		TRUE	// Use VRAM to chech tile collision (use RAM buffer instead)
#define GAMEPAWN_TILEMAP_WIDTH		32		// Width of the tiles map
#define GAMEPAWN_TILEMAP_HEIGHT		24		// Height of the tiles map

Dependencies

Dependency on other modules:

• vdp
• memory