Peer to Peer

A library for p2p online multiplayer games.

File:
p2p.lib, p2p_next.dll
Version:
1.0
Author:
Marcus Johansson

Contents

Details
Sub routines


Details

With this library you can write "serverless" online multiplayer games. One player creates a lobby and acts as server, that other players (clients) can connect to.

Lists of active game lobbies are (optionally) stored on NaaLaa's server. These lists, including the IP addresses of the lobbies, can be fetched by your program.

As with most p2p games, if you're behind a router, you will need to make a "port forward" on your router to your computer if you wish to create a lobby that other players can connect to. The default port used by the library is 31903. However, while developing and testing your game, you can start several instances of the program and let one of them act server while the other connects to "localhost" - in this case, no "port forwarding" is required. How you forward a port from the router to your computer depends on what type of router you have. Use Google and you will probably find an answer.


Subroutines

Name
Parameters
Brief description
function
P2P_Init
Init the library.
procedure
P2P_Terminate
Terminate the library.
function
P2P_CreateLobby
game$, user$, extra, public
Create a lobby.
procedure
P2P_SetLobbyExtra
extra
Set lobby extra flag.
procedure
P2P_PingLobby
Ping lobby on naalaa server.
procedure
P2P_SetLobbyAutoPing
value
Set lobby auto ping.
function
P2P_SearchClient
Initiate search for a client.
procedure
P2P_CancelSearch
Cancel search for client.
function
P2P_IsSearching
Returns true if a client search is active.
procedure
P2P_Disconnect
Disconnect as client or server.
function
P2P_FindLobbies?[]
game$
Find lobbies for specific game.
function
P2P_Connect
server$, user$
Connect to lobby.
procedure
P2P_Update
Update.
procedure
P2P_Send
id, msg$
Send a message.
procedure
P2P_SendTo
rcv, id, msg$
Send a message to a specific user.
procedure
P2P_ComposePackage
id
Initiate the composition of a package (complex message).
procedure
P2P_AddInt
value
Add an integer value to a package.
procedure
P2P_AddFloat
value#
Add a floating point value to a package.
procedure
P2P_AddString
value$
Add a string value to a package.
procedure
P2P_SendComposed
Send composed package (complex message).
procedure
P2P_SendComposedTo
rcv
Send composed package (complex message) to specific user.
procedure
P2P_Decompose
msg$
Decompose received package (complex message).
function
P2P_GetInt
Get integer value from decomposed message.
function
P2P_GetFloat#
Get floating point value from decomposed message.
function
P2P_GetString$
Get string value from decomposed message.
function
P2P_Receive
&pkg?
Get message (if any) sent by server/clients.


Subroutine documentation

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.

Parameter
Mode
Description
game$
In
Name or identifier of your game - make it unique.
user$
In
Name of user (you can embedd more information than the actual name, it's all up to your program's needs).
extra
In
Can be used for whatever you want. This value can be changed later on with P2P_SetLobbyExtra. You can, for example use it to flag that the lobby is full and then check the value when you get the results from P2P_FindLobbies.
public
In
Set to true if you want the lobby to be visible when calling P2P_FindLobbies.

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.

Parameter
Mode
Description
extra
In
Can be used for whatever you want.

[ 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.

Parameter
Mode
Description
value
In
True for enabling auto ping, false to disable.

[ 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.

Parameter
Mode
Description
game$
In
Game identifier, same as in P2P_CreateLobby.

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.

Parameter
Mode
Description
server$
In
ip address of lobby.
user$
In
Client (your) user id.

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].

Parameter
Mode
Description
id
In
Message identifier.
msg$
In
Message.

[ 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].

Parameter
Mode
Description
rcv
In
User id of receiver.
id
In
Message identifier.
msg$
In
Message.

[ 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.

Parameter
Mode
Description
id
In
Message identifier, works as with P2P_Send.

[ Back ]


procedure P2P_AddInt ( value )

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

Parameter
Mode
Description
value
In
Value.

[ Back ]


procedure P2P_AddFloat ( value# )

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

Parameter
Mode
Description
value#
In
Value.

[ Back ]


procedure P2P_AddString ( value$ )

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

Parameter
Mode
Description
value$
In
Value.

[ 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.

Parameter
Mode
Description
rcv
In
User id of receiver.

[ 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.

Parameter
Mode
Description
msg$
In
Message to decompose (usually the msg$ field of the object returned by P2P_Receive).

[ 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 ]


Generated with NLDoc 20160818.