The GameNet module (GNet for short) provides a set of commands for creating and managing multiplayer network games.
GNet works a little differently than other networking libraries. Instead of being primarily 'message based', GNet works by synchronizing a collection of GNet objects over a network.
Each GNet object contains 32 &slots which are similar in nature to the fields of BlitzMax objects. You can write to these slots using the SetGNetInt, SetGNetFloat and SetGNetString commands, and read from these slots using the GetGNetInt, GetGNetFloat and GetGNetString commands. The actual meaning of the data contained in these slots is completely up to you, but will typically include such information as player position, score, hitpoints and so on.
Note that you can only modify GNet objects that you have yourself created. Such objects are known as local objects, while objects created elsewhere are known as remote objects.
To start using GNet, you must first create a GNet host with the CreateGNetHost command. Once you have created a host, you can either connect to other GNet hosts using GNetConnect, or prepare to accept connections from other hosts using GNetListen.
The GNetSync command brings all GNet objects up to date. This involves notifying other hosts about any modifications you have made to local GNet objects, and processing notifications from other hosts about any modifications to remote GNet objects.
GNet also provides a simple messaging system. A GNet message is actually just a special type of GNet object, so you initialize messages using the standard GNet commands for writing slots. Once created and initialized, a message can be sent to a remote object using the SendGNetMessage command.
Incoming messages can be processed using the GNetMessages command after a GNetSync. This function returns a linked list of messages objects which can be examined using the standard GNet commands for reading slots. In addition, the GNetMessageObject command can be used to determine which local object a message was intended for.
Description: Create GNet host
Returns: A new GNet host
Information: Once you have created a GNet host, you can use it to create objects with CreateGNetObject, connect to other hosts with GNetConnect and listen for connections from other hosts with GNetListen.
Function CloseGNetHost( host:TGNetHost )
Description: Close a GNet host
Information: Once closed, a GNet host cannot be reopened.
Function GNetSync( host:TGNetHost )
Description: Synchronize GNet host
Information: GNetSync will update the state of all GNet objects. Once you have used this command, use the GNetObjects function to determine which objects have been remotely created, modified or closed.
Function GNetListen( host:TGNetHost,port )
Description: Listen for connections
Returns: True if successful, otherwise false
Information: Causes host to start listening for connection attempts on the specified port. Once a host is listening, hosts on other machines can connect using GNetConnect.
Function GNetConnect( host:TGNetHost,address$,port,timeout_ms=10000 )
Description: Connect to a remote GNet host
Returns: True if connection successful, otherwise false
Information: Attempts to connect host to the specified remote address and port.
A GNet host must be listening (see GNetListen) at the specified address and port for the connection to succeed.
Function GNetObjects:TList( host:TGNetHost,state=GNET_ALL )
Description: Get a list of GNet objects
Returns: A linked list
Information: GNetObjects returns a list of GNet objects in a certain state.
The state parameter controls which objects are listed, and can be one of &GNET_ALL, &GNET_CREATED, &GNET_MODIFIED or &GNET_CLOSED.
Note that with the exception of &GNET_ALL, the returned lists will only ever contain remote objects.
Function GNetMessages:TList( host:TGNetHost )
Description: Get a list of GNet messages sent to local objects
Returns: A linked list
Function CreateGNetObject:TGNetObject( host:TGNetHost )
Description: Create a GNet object
Returns: A new GNet object
Function CreateGNetMessage:TGNetObject( host:TGNetHost )
Description: Create a GNet message object
Returns: A new GNet object
Function SendGNetMessage( msg:TGNetObject,toObject:TGNetObject )
Description: Send a GNet message to a remote object
Function GNetMessageObject:TGNetObject( msg:TGNetObject )
Description: Get message target object
Returns: The object that msg was sent to
Function GNetObjectState( obj:TGNetObject )
Description: Get state of a GNet object
Returns: An integer state
Information:The returned value can be one of the following:
|GNET_CREATED||Object has been created|
|GNET_SYNCED||Object is in sync|
|GNET_MODIFIED||Object has been modified|
|GNET_CLOSED||Object has been closed|
|GNET_ZOMBIE||Object is a zombie|
|GNET_MESSAGE||Object is a message object|
Zombie objects are objects that have been successfully closed and will never again be used by GameNet. Therefore, such objects will never appear in any list returned by the GNetObjects function.
Function GNetObjectLocal( obj:TGNetObject )
Description: Determine whether a GNet object is local
Returns: True if object is a local object
Function GNetObjectRemote( obj:TGNetObject )
Description: Determine whether a GNet object is remote
Returns: True if object is a remote object
Function SetGNetInt( obj:TGNetObject,index,value )
Description: Set GNet object int data
Function SetGNetFloat( obj:TGNetObject,index,value# )
Description: Set GNet object float data
Function SetGNetString( obj:TGNetObject,index,value$ )
Description: Set GNet object string data
Function GetGNetInt( obj:TGNetObject,index )
Description: Get GNet object int data
Function GetGNetFloat#( obj:TGNetObject,index )
Description: Get GNet object float data
Function GetGNetString$( obj:TGNetObject,index )
Description: Get GNet object string data
Function SetGNetTarget( obj:TGNetObject,target:Object )
Description: Set a GNet object's target object
Information: This command allows you to bind an abitrary object to a GNet object.
Function GetGNetTarget:Object( obj:TGNetObject )
Description: Get a GNet object's target object
Returns: The currently bound target object
Function CloseGNetObject( obj:TGNetObject )
Description: Close a GNet object