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 Pawn_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 Pawn_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 Pawn_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 Pawn_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 Pawn_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 Pawn_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);
}

/* ... */

Pawn_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):

// Pawn setting
#define PAWN_ID_PER_LAYER			FALSE	// Set sprite ID for each layer (otherwise set per pawn)
#define PAWN_USE_RT_LOAD			TRUE	// Load sprite pattern data on the fly (real-time)
#define PAWN_USE_SPRT_FX			TRUE	// Allow sprite effects (crop, flip, mask, rotate)
#define PAWN_SPRITE_SIZE			16		// Sprite size mode (8 for 8x8 pixel mode, or 16 for 16x16)
#define PAWN_USE_PHYSICS			TRUE	// Add physics and collision features
// Pawn coordinate unit
// - PAWN_UNIT_SCREEN				Default screen (pixel) unit (8-bit unsigned int)
// - PAWN_UNIT_QMN(n)				Fixed-point (Qm.n) unit (16-bit signed int)
#define PAWN_UNIT					PAWN_UNIT_SCREEN
// Pawn's bound (can be fixed for all pawn, or setable for each one)
#define PAWN_BOUND_X				PAWN_BOUND_CUSTOM
#define PAWN_BOUND_Y				PAWN_BOUND_CUSTOM
// Collision position options for each pawn's side
// - PAWN_COL_0
// - PAWN_COL_25
// - PAWN_COL_50
// - PAWN_COL_75
// - PAWN_COL_100
#define PAWN_COL_DOWN				(PAWN_COL_25|PAWN_COL_75)
#define PAWN_COL_UP					PAWN_COL_50
#define PAWN_COL_RIGHT				PAWN_COL_50
#define PAWN_COL_LEFT				PAWN_COL_50
// Options to determine which border collide or trigger events
// - PAWN_BORDER_NONE
// - PAWN_BORDER_DOWN
// - PAWN_BORDER_UP
// - PAWN_BORDER_RIGHT
// - PAWN_BORDER_LEFT
#define PAWN_BORDER_EVENT			(PAWN_BORDER_DOWN|PAWN_BORDER_RIGHT)
#define PAWN_BORDER_BLOCK			(PAWN_BORDER_UP|PAWN_BORDER_LEFT)
// Top/bottom border position (in pixel)
#define PAWN_BORDER_MIN_Y			0		// High border Y coordinade
#define PAWN_BORDER_MAX_Y			191		// Low border Y coordinate
#define PAWN_TILEMAP_WIDTH			32		// Width of the tiles map
#define PAWN_TILEMAP_HEIGHT			24		// Height of the tiles map
// Collision tilemap source
// - PAWN_TILEMAP_SRC_AUTO ........ Backward compatibility option
// - PAWN_TILEMAP_SRC_RAM ......... Tilemap located in a buffer in RAM (best for performance)
// - PAWN_TILEMAP_SRC_VRAM ........ Tilemap located in VRAM (slow but don't need additionnal data)
// - PAWN_TILEMAP_SRC_V9 .......... Tilemap located in V9990's VRAM
#define PAWN_TILEMAP_SRC			PAWN_TILEMAP_SRC_VRAM
// Pawn's sprite mode
// - PAWN_SPT_MODE_AUTO ........... Backward compatibility option
// - PAWN_SPT_MODE_MSX1 ........... Sprite Mode 1 (MSX1 screens)
// - PAWN_SPT_MODE_MSX2 ........... Sprite Mode 2 (MSX2 screens)
// - PAWN_SPT_MODE_MSX12 .......... Sprite Mode 1 & 2 (MSX1 & MSX2 screens)
// - PAWN_SPT_MODE_V9_P1 .......... V9990 sprite in P1 mode
// - PAWN_SPT_MODE_V9_P2 .......... V9990 sprite in P2 mode
#define PAWN_SPT_MODE				PAWN_SPT_MODE_MSX1

Note: For now, PAWN_COL_UP, PAWN_COL_RIGHT and PAWN_COL_LEFT are fixed to PAWN_COL_50.

Dependencies

Dependency on other modules:

• vdp
• memory