Peer to Peer

function P2P_Init ( )

This function must be called prior to using any of the other functions.

Return value
True on success, else false.

[ Back ]

procedure P2P_Terminate ( )

You can call this function before ending your program, but it's not necessary, as the extension does it automaticly upon program exit.

[ Back ]

function P2P_CreateLobby ( game$, user$, extra, public )

Create a lobby and optionally add it to the listings on NaaLaa's server. If listed, the lobby will be removed from the server when it times out or you call P2P_Disconnect.

Return value
True on success, else false.

[ Back ]

procedure P2P_SetLobbyExtra ( extra )

If the lobby was created as public, you can use this to change the extra flag stored on the NaaLaa server. A client downloading the lobby list for your game can check this flag. See P2P_CreateLobby.

[ Back ]

procedure P2P_PingLobby ( )

If the lobby was created as public you can use this function to tell the NaaLaa server that your lobby is still alive. A lobby will automaticly be removed if it has not been pinged for 10 minutes. You can optionally enable automatic ping with P2P_SetLobbyAutoPing.

[ Back ]

procedure P2P_SetLobbyAutoPing ( value )

If the lobby was created as public, the NaaLaa server will need to be notified that it's still alive every now and then, or the lobby will be removed from the listing. If you enable auto ping with this function, P2P_PingLobby will be automaticly called once every 5th minute.

[ Back ]

function P2P_SearchClient ( )

If you're a server (have created a lobby), this function will initiate the search for a client. After calling this function you have got to start polling for messages with the P2P_Receive function. When a user connects you will get a message with the id P2P_USER_CONNECTED and the user name in the msg string. The usr field will be a unique identifer (integer) for the client. If you want more users to be able to connect, you then need to call P2P_SearchClient again.

Return value
True on success, false on failure.

[ Back ]

procedure P2P_CancelSearch ( )

Calling this function will abort the search for a client initiated with P2P_SearchClient.

[ Back ]

function P2P_IsSearching ( )

If you're the server, this function will return true if you're currently searching for a client.

Return value
True if a client search is active.

[ Back ]

procedure P2P_Disconnect ( )

If you're a client this will close your connection to the server. The server and all other clients will receive a P2P_USER_DISCONNECTED message through the P2P_Receive function with your unique id in the usr field. If you're the server, all clients will receive a P2P_CONNECTION_LOST message.

[ Back ]

function P2P_FindLobbies?[] ( game$ )

This function will fetch a list of lobbies for the specified game from the NaaLaa server. It returns an object array with the fields ip$, user$ and extra. ip$ is the ip address of the lobby, which you will send to P2P_Connect. user$ is the name of the user hosting the lobby, and extra is the flag that the server has set. If no lobbies are found, the returned list will be empty.

Return value
Object array with lobby information.

[ Back ]

function P2P_Connect ( server$, user$ )

Connect to server with specified ip address. This call will halt your program for some seconds and then return true on success or false on failure.

Return value
True on success, false on failure.

[ Back ]

procedure P2P_Update ( )

You MUST call this function once every tick (usually 60 times per second) in your program loop after you have created a lobby or connected to one. Else message passing (P2P_Send, P2P_Receive et.c. won't work).

[ Back ]

procedure P2P_Send ( id, msg$ )

Send a message to all other users (server/clients). id is an identifier for the message, usually a unique value that tells what kind of message it is. msg$ is the actuall message. id must be in the range [1..100].

[ Back ]

procedure P2P_SendTo ( rcv, id, msg$ )

Send a message to the user with id rcv. id is an identifier for the message, usually a unique value that tells what kind of message it is. msg$ is the actuall message. id must be in the range [1..100].

[ Back ]

procedure P2P_ComposePackage ( id )

This can be used to compose a message that consists of one or more primitive parts (integer, floating point and string values). For example, if you want to send information about the player's position in a 2D game, you could compose a package containing the x and y coordinate.

[ Back ]

procedure P2P_AddInt ( value )

After calling P2P_ComposePackage, use this function to add an integer value to the package.

[ Back ]

procedure P2P_AddFloat ( value# )

After calling P2P_ComposePackage, use this function to add a floating point value to the package.

[ Back ]

procedure P2P_AddString ( value$ )

After calling P2P_ComposePackage, use this function to add a string value to the package.

[ Back ]

procedure P2P_SendComposed ( )

After calling P2P_ComposePackage and adding your values, use this function to actually send the package to all users (server/clients).

[ Back ]

procedure P2P_SendComposedTo ( rcv )

After calling P2P_ComposePackage and adding your values, use this function to actually send the package to a specific user.

[ Back ]

procedure P2P_Decompose ( msg$ )

After receiving a package (complex message) created with P2P_ComposePackage, you need to call this function to decompose the msg$ field of the object returned by P2P_Receive. Then use P2P_GetInt, P2P_GetFloat and P2P_GetString to fetch the values in the same order as they were added when creating the package.

[ Back ]

function P2P_GetInt ( )

Returns an integer value from message decomposed with P2P_Decompose.

Return value
Value.

[ Back ]

function P2P_GetFloat# ( )

Returns an integer value from message decomposed with P2P_Decompose.

Return value
Value.

[ Back ]

function P2P_GetString$ ( )

Returns a string value from message decomposed with P2P_Decompose.

Return value
Value.

[ Back ]

function P2P_Receive ( &pkg? )

You need to poll for messages send by the server or clients in your program loop. Call this function after calling P2P_Update. If a message was found, the function will return true and the pkg object that you passed to it will contain information about the message. The id field is the identifier of the message (set when calling P2P_Send or P2P_ComposePackage). usr is the unique identifier of the user (client or server) that sent the message. msg$ is the actual message.

There are a couple of predefined messages that are automaticly sent on certain events. They have the following id values (constants):

• P2P_USER_CONNECTED - A user connected, msg$ is the username
• P2P_USER_DISCONNECTED - A user disconnected, msg$ is the username
• P2P_CONNECTION_LOST - The connection to the server was lost

Return value
True if a message was found, else false.

[ Back ]