Modules/game pawn
From MSX Game Library
< Modules
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.
Contents
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.).
// 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:
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
Note: For now, GAMEPAWN_COL_UP, GAMEPAWN_COL_RIGHT and GAMEPAWN_COL_LEFT are fixed to GAMEPAWN_COL_50.
Dependencies
Dependency on other modules:
Documentation
Update to new game/pawn module
You can still use the old game_pawn module, but to take advantage of the new features and performance improvements, it is recommended that you switch to the new game/pawn module. Here is a guide to converting a program using the old module to the new one.
| Update module list in project settings (project_config.js): | ||
LibModules = [ "game_pawn", ... ]; |
» | LibModules = [ "game/pawn", ... ]; |
| Replace all GAMEPAWN_ define options by PAWN_ in lib settings (msxgl_config.h): | ||
// GamePawn setting #define GAMEPAWN_ID_PER_LAYER FALSE // 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 GAMEPAWN_BOUND_CUSTOM #define GAMEPAWN_BOUND_Y GAMEPAWN_BOUND_CUSTOM ... |
» | // Pawn setting #define PAWN_ID_PER_LAYER FALSE // Set sprite ID for each layer (otherwise set per pawn) #define PAWN_USE_PHYSICS TRUE // Add physics and collision features // 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 ... |
| Add new pawn options in lib settings (msxgl_config.h): | ||
// Pawn setting #define PAWN_ID_PER_LAYER FALSE // Set sprite ID for each layer (otherwise set per pawn) #define PAWN_USE_PHYSICS TRUE // Add physics and collision features |
» | // Pawn setting #define PAWN_ID_PER_LAYER FALSE // Set sprite ID for each layer (otherwise set per pawn) #define PAWN_USE_RT_LOAD FALSE // Load sprite pattern data on the fly (real-time) #define PAWN_USE_SPRT_FX FALSE // 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 |
| Replace module include in source file: | ||
#include "game_pawn.h" |
» | #include "game/pawn.h" |
| Rename functions in source file: | ||
GamePawn_Initialize GamePawn_SetPosition GamePawn_InitializePhysics GamePawn_SetAction GamePawn_SetMovement GamePawn_Update GamePawn_Draw |
» | Pawn_Initialize Pawn_SetPosition Pawn_InitializePhysics Pawn_SetAction Pawn_SetMovement Pawn_Update Pawn_Draw |
| Rename structures in source file: | ||
Game_Sprite Game_Frame Game_Action Game_Pawn |
» | Pawn_Sprite Pawn_Frame Pawn_Action Pawn |