Scripting Reference/CraftStudio.Network

(This is documentation for an upcoming feature, it's not final nor usable)

Network play in CraftStudio

Networking lets you make your games work over the Internet so that they can be played together by multiple players. Although made as simple as possible, networking will likely affect most aspects of your game so it's best to build it in along with your game rather than as an afterthought.

See also the NetworkSync component documentation.

Technical details

Networking in CraftStudio uses the UDP protocol for communication.

CraftStudio.Network.Server.Start

CS.Network.Server.Start( [number] port=CS.Network.DefaultPort )

Starts accepting connections on the specified port number (defaults to 4233).

You'll need to manually connect to your server locally with CS.Network.Connect (passing "127.0.0.1" as the hostname) if you want to treat your local game as just another network player.

This is a server-side function.

CraftStudio.Network.Server.Stop

CS.Network.Server.Stop()

Disconnects all players and stops listening to incoming connections.

This is a server-side function.

CraftStudio.Network.Connect

CS.Network.Connect( [string] hostname, [number] port=CS.Network.DefaultPort, [function] callback=nil )

Opens a connection to the specified hostname (or IP) on the specified port number.

When the connection has been established, the specified callback function will be called.

This is a client-side function.

CraftStudio.Network.Disconnect

CS.Network.Disconnect()

Closes any open connection.

This won't call your OnDisconnected handler.

This is a client-side function.

CraftStudio.Network.OnDisconnected

CS.Network.OnDisconnected( [function] callback )

Defines which function to call (if any) when a disconnection happens. You can pass nil to disable it.

This is a client-side function.

CraftStudio.Network.Server.OnPlayerJoined

CS.Network.Server.OnPlayerJoined( [function] callback )

Defines which function to call (if any) when a player has joined. You can pass nil to disable it.

The callback will be passed a table containing player info with the following keys:

• id: a unique ID attributed to this player
• name: the player's name (alphanumeric)
• authenticated: a boolean stating whether the player is authenticated against the master server or not

This is a server-side function.

Example: Printing the player's ID when they join

function PlayerJoinHandler( player )
    print( "Player with ID " .. player.id .. " has joined!" )
end

CraftStudio.Network.Server.OnPlayerLeft

CS.Network.Server.OnPlayerLeft( [function] callback )

Defines which function to call (if any) when a player has left (or been disconnected). You can pass nil to disable it.

The callback will be passed the disconnected player's ID.

This is a server-side function.

Example: Printing the player's ID when they leave

​function PlayerLeftHandler( playerId )
    print( "Player with ID " .. playerId .. " has left!" )
end

CraftStudio.Network.Server.DisconnectPlayer

CS.Network.Server.DisconnectPlayer( playerId, reason="" )

Disconnects the specified player, optionally specifying a reason as text that will be passed to the player's OnDisconnected handler.

CraftStudio.Network.RegisterMessageHandler

CS.Network.RegisterMessageHandler( [function] handler, [CS.Network.Side] server or players side )

Registers a function as callable on the players (client-side) or the server (server-side). Message handler functions must be registered before they can be used to respond to messages.

Possible values for the second parameter are CS.Network.Side.Server or CS.Network.Side.Players.

Example: Registering a server message handler

​function Behavior:DoSomethingFun( data, playerId )
    print( "Got a DoSomethingFun message from player with ID " .. playerId )
end
CS.Network.RegisterMessageHandler( Behavior.DoSomethingFun, CS.Network.Side.Players )