BRL.GNet: Functions Modinfo Source  

GameNet

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.

Following a GNetSync, you can check which objects have been modified, created or closed using the GNetObjects function. This returns a linked list of GNet objects in a particular state.

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 function following 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.

Functions

Function CloseGNetHost( host:TGNetHost )
DescriptionClose a GNet host.
InformationOnce closed, a GNet host cannot be reopened.

Function CloseGNetObject( obj:TGNetObject )
DescriptionClose a GNet object.

Function CreateGNetHost:TGNetHost()
ReturnsA new GNet host.
DescriptionCreate GNet host.
InformationOnce 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 CreateGNetMessage:TGNetObject( host:TGNetHost )
ReturnsA new GNet object.
DescriptionCreate a GNet message object.

Function CreateGNetObject:TGNetObject( host:TGNetHost )
ReturnsA new GNet object.
DescriptionCreate a GNet object.

Function GetGNetFloat#( obj:TGNetObject,index )
DescriptionGet GNet object float data.

Function GetGNetInt( obj:TGNetObject,index )
DescriptionGet GNet object int data.

Function GetGNetString$( obj:TGNetObject,index )
DescriptionGet GNet object string data.

Function GetGNetTarget:Object( obj:TGNetObject )
ReturnsThe currently bound target object.
DescriptionGet a GNet object's target object.

Function GNetConnect( host:TGNetHost,address$,port,timeout_ms=10000 )
ReturnsTrue if connection successful, otherwise false.
DescriptionConnect to a remote GNet host.
InformationAttempts 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 GNetListen( host:TGNetHost,port )
ReturnsTrue if successful, otherwise false.
DescriptionListen for connections.
InformationCauses host to start listening for connection attempts on the specified port. Once a host is listening, hosts on other machines can connect using GNetConnect.

GNetListen may fail if port is already in use by another application, or if host is already listening or has already connected to a remote host using GNetConnect.

Function GNetMessageObject:TGNetObject( msg:TGNetObject )
ReturnsThe object that msg was sent to.
DescriptionGet message target object.

Function GNetMessages:TList( host:TGNetHost )
ReturnsA linked list.
DescriptionGet a list of GNet messages sent to local objects.

Function GNetObjectLocal( obj:TGNetObject )
ReturnsTrue if object is a local object.
DescriptionDetermine whether a GNet object is local.

Function GNetObjectRemote( obj:TGNetObject )
ReturnsTrue if object is a remote object.
DescriptionDetermine whether a GNet object is remote.

Function GNetObjects:TList( host:TGNetHost,state=GNET_ALL )
ReturnsA linked list.
DescriptionGet a list of GNet objects.
InformationGNetObjects 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 GNetObjectState( obj:TGNetObject )
ReturnsAn integer state.
DescriptionGet state of a GNet object.
InformationThe returned value can be one of the following:
Object StateMeaning
GNET_CREATEDObject has been created
GNET_SYNCEDObject is in sync
GNET_MODIFIEDObject has been modified
GNET_CLOSEDObject has been closed
GNET_ZOMBIEObject is a zombie
GNET_MESSAGEObject 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 GNetSync( host:TGNetHost )
DescriptionSynchronize GNet host.
InformationGNetSync 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 SendGNetMessage( msg:TGNetObject,toObject:TGNetObject )
DescriptionSend a GNet message to a remote object.

Function SetGNetFloat( obj:TGNetObject,index,value# )
DescriptionSet GNet object float data.

Function SetGNetInt( obj:TGNetObject,index,value )
DescriptionSet GNet object int data.

Function SetGNetString( obj:TGNetObject,index,value$ )
DescriptionSet GNet object string data.

Function SetGNetTarget( obj:TGNetObject,target:Object )
DescriptionSet a GNet object's target object.
InformationThis command allows you to bind an abitrary object to a GNet object.

Module Information

Version1.05
AuthorMark Sibly
LicenseBlitz Shared Source Code
CopyrightBlitz Research Ltd
ModserverBRL
History1.05 Release
HistorySome doc fixes
History1.04 Release
HistortFixed low level send/recv leaks
History1.03 Release
HistoryNow uses Pub.ENet
History1.02 Release
HistoryFixed Closing host not closing server socket
History1.01 Release