The SGADE Documentation

the SGADE The Socrates Gameboy Advance Development Engine

The SGADE is a development library for the Nintendo Gameboy Advance. It's free for all uses and is distributed without guarantees. For more information visit the SGADE page.

Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

SoMultiPlayer

Module for handling multiplayer for 2, 3 or 4 players. More...

Files

file  SoMultiPlayer.c
file  SoMultiPlayer.h

Defines

#define SO_MULTI_PLAYER_PACKET_TRANSFER_SIZE
 Number of 16 bit transfers in a single packet.

#define SO_MULTIPLAYER_FRAME_RATE
 Frame rate at which you want each packet transfer to be complete.

#define SO_MULTI_PLAYER_9600_BPS
 Baud rate: 9600 bps.

#define SO_MULTI_PLAYER_38400_BPS
 Baud rate: 38400 bps.

#define SO_MULTI_PLAYER_57600_BPS
 Baud rate: 57600 bps.

#define SO_MULTI_PLAYER_115200_BPS
 Baud rate: 115200 bps.


Typedefs

typedef bool(* SoMultiPlayerFailureCallback )(void)
 Callback routine that is called whenever something is wrong with the communication.


Functions

void SoMultiPlayerInitialize (void)
 Initializes the multi player system;.

bool SoMultiPlayerStart (u32 a_BaudRate, u32 a_NumPlayers)
 Starts a multiplayer session.

void SoMultiPlayerStop ()
 Stops the current multiplayer s_Session.

void SoMultiPlayerUpdate (u16 a_OutGoingPacket[SO_MULTI_PLAYER_PACKET_TRANSFER_SIZE], u16 a_IncomingPackets[4][SO_MULTI_PLAYER_PACKET_TRANSFER_SIZE])
 Just call this every frame to handle all communication.

void SoMultiPlayerSetFailureCallback (SoMultiPlayerFailureCallback a_FailureCallback)
 Sets the callback routine that is called whenever something is wrong with the communication either during setup, or during communication.

u32 SoMultiPlayerGetNumPlayers (void)
 Returns the number of players in this s_Session.

u32 SoMultiPlayerGetID (void)
 Returns the ID of this GBA in a multiplayer session.

Detailed Description

Module for handling multiplayer for 2, 3 or 4 players.

Todo:
This module uses a hardcoded timer 3, we should make this user definable.

This module is for the GBA's multiplayer system where you can transfer packets from and to up to three other GBAs. It supports extensive error detection, and handles all possible failure cases. You can send a fair amount of bytes each frame, and it's very stable. If you lose a packet, it's because a cable got disconnected, or because you connected a third GBA in a 2 player session (for example).

In short, it rocks, it's Nintendo guideline-compatible, and I suggest you use it. Cheers.

Define Documentation

#define SO_MULTI_PLAYER_PACKET_TRANSFER_SIZE
 

Number of 16 bit transfers in a single packet.

The packet size in bytes is twice this number. Don't make this package too big please, otherwise you won't be able to complete a single packet transfer in a single frame. At a framerate of 60hz, I've had success with transfer sizes up to 16 (32 bytes).

Of course you should always be sending as few bits as possible anyway.

#define SO_MULTIPLAYER_FRAME_RATE
 

Frame rate at which you want each packet transfer to be complete.

Of course this is related to the packet size you are using. If you have a large packet size you might not be able to complete it at 60 hz. Just fiddle with this value, and the SO_MULTI_PLAYER_PACKET_TRANSFER_SIZE value until you have a satisfactory result.

I've sent up to 32 bytes (16 transfers) stable at 60 hz. But don't qoute me on that :) hehe.

Typedef Documentation

typedef bool(* SoMultiPlayerFailureCallback)( void )
 

Callback routine that is called whenever something is wrong with the communication.

Returns :
Let it return TRUE if you want to continue trying, or FALSE if you want to stop trying.

Function Documentation

u32 SoMultiPlayerGetID (  void    ) 
 

Returns the ID of this GBA in a multiplayer session.

Returns :
The ID of this GBA in the session. 0 if it's the master, 1, 2, or 3 if it's a slave.

u32 SoMultiPlayerGetNumPlayers (  void    ) 
 

Returns the number of players in this s_Session.

Returns :
The number of players in this s_Session. Can be 2, 3 or 4.

void SoMultiPlayerInitialize (  void    ) 
 

Initializes the multi player system;.

This should be the first SoMultiPlayer function you call. Multiple calls don't matter.

void SoMultiPlayerSetFailureCallback (  SoMultiPlayerFailureCallback    a_FailureCallback ) 
 

Sets the callback routine that is called whenever something is wrong with the communication either during setup, or during communication.

Parameters:
a_FailureCallback  The failure callback. Can be set to NULL if you don't want to use the callback.
Returns :
Let the callback return true if you want to continue trying, or false if you want to stop trying.

bool SoMultiPlayerStart (  u32    a_BaudRate,
u32    a_NumPlayers
) 
 

Starts a multiplayer session.

Parameters:
a_BaudRate  Speed of communication. Can be one of the SO_MULTI_PLAYER_*_BPS defines. Not that the the effective baudrate decreases with the amount of players connected. The speed using a baudrate of 115200 with 2 players is not the same as it is with 4 players.
a_NumPlayers  Number of participants in this multiplayer s_Session. Can be 2, 3 or 4.
Returns :
true if the session is active and can be used. false when the gameboys are not properly connected.
Warning:
The set failure callback will almost certainly fail at least once because of timing issues. I could add a couple of NOP instructies inbetween enabling and testing, but it's better to put some sort of countdown thingy in the failure callback, so it fails after 5 seconds of trying or maybe when the user presses a cancel-button.
Warning:
Do not call this routine again, without calling stopMultiSession again first.

void SoMultiPlayerUpdate (  u16    a_OutGoingPacket[SO_MULTI_PLAYER_PACKET_TRANSFER_SIZE],
u16    a_IncomingPackets[4][SO_MULTI_PLAYER_PACKET_TRANSFER_SIZE]
) 
 

Just call this every frame to handle all communication.

Parameters:
a_OutGoingPacket  Packet filled with the info you want to send;
a_IncomingPackets  Array of four packets that will be filled with the received information as far as the number of AGB's connected ofcourse.
This is the meat of the module. Here all stuff is done, so to speak... Ofcourse you can only call this when a multiplayer session is running. Use SoMultiPlayerStart to start a session.

Copyright 2002 by the SGADE authors. See SoLicense.h or Visit the SGADE page for more information.