Appendix I 3DGS Multiplayer Commands

Appendix I

3DGS Multiplayer Commands

I have attempted to list all of the current 3DGS commands that pertain to multiplayer coding and a short description of each.

Command Line Options:

-cl

Joins to a mulitplayer session in client mode.

-ip name

Through the -IP command line option the server name, the server's machine name, domain name or IP address can be given when starting a client in multiplayer mode.

Connects to the server with the given IP address on the network or internet. The given name or address is available during game play in the predefined server_name string. If this command line option is not given, the server will be searched on the local network.

-nc (Pro)

The -nc command line option prevents the engine from checking itself for possible virus or hacker tampering at game start. This way, the EXE can be 'wrapped' into another program for using the registration or unlock feature of some distribution channels.

-pl name

By this option an individual name can be given to each client in a multiplayer system (up to 16 characters). Otherwise the engine will generate a client name. During gameplay the name is available in the player_name string.

-port number

Through this command line option, a port address for TCP/IP client/server communication can be given. Valid ports are in the range 2300..2400. If no port is given, a default port address is assigned. A port address can only be given for the server - the client will connect to the right port automatically.

-sn name

Through this command line option the session name can be given when starting a server or a client in multiplayer mode. The default session name is the name of the main script file without extension, e.g. "office" for starting the office.wdl. The given name or address is available during gameplay in the predefined session_name string.

Run-Time Options:

server

Predefined if the engine is started as a server (-sv command line option).

client

Predefined if the engine is started as a client (-cl command line option).

player_name

This string contains the name of the client in a multiplayer game.

It can be given through the -pl command line option; otherwise a unique name is generated automatically.

session_name

Contains the name of the current session in multiplayer mode.

dplay_smooth

If set to 0, entity updates from the server are directly displayed on the clients, without prediction or smoothing. If set at 2 (default) or above, the position and angles of entities are predicted based on their last values received from the server. This produces smooth movements and rotations, but can lead to visible 'overshooting' when the server update frequency is low.

If dplay_smooth is set to 3 or above, MDL animation is also interpolated on the client by predicting the frame and the inbetweening factor. If the model contains more than one animation cycle, frame prediction can sometimes fail, which leads to undesired 'jerks' if the server updates come in slow and irregular intervals. Therefore only use animation prediction when the server update rate is set to 1 tick per update or better..

Range:

0, 2, 3

dplay_unreliable

If this variable (default 0) is set to 1, even important multiplayer messages are sent in non guaranteed mode. This reduces the required bandwidth in multiplayer systems, but also reduces the reliability of messages.

Range:

0 - UDP guaranteed protocol (default)

1 - UDP non guaranteed protocol

dplay_entrate

The time between entity updates from server to client, in ticks (default 1 = 16 updates per second). The higher the value, the less bandwidth is needed, but the worse is the lag on the clients. If the value is set to 0, the entities will be updated every server frame. At -1 no updates will be sent at all.

Range:

-1 .. 16

dplay_pingrate

Number of ticks on the client per keep alive message sent to the server (default 16 = one message per second). The keep alive message is used for detecting client disconnection on the server.

Range:

0 .. 255

dplay_clienttimeout

Sets the number of ticks after which a client is automatically disconnected when he does not respond. Default: 80 (5 seconds).

Range:

0 .. unlimited in Ticks (default: 80)

dplay_timeout

Time in ticks for unreliable network messages to expire if they could

not be sent during that period due to low bandwidth.

Range:

0..16, default 3 (~180 ms). 0 disables the expiration mechanism (client only).

Remarks:

Network messages must expire after some time to prevent a buffer

overflow and falling out of sync when the available bandwidth is

exceeded. The lower dplay_timeout, the lower the traffic, but the higher

the packet loss due to dropping of expired messages.

On the client, this value can be set to 0, which means that even

unreliable messages never expire. In that case the client waits

at the end of every frame until all pending messages are sent. This was

the behavior of engine versions prior to 6.3, and can result in a

reduced frame rate on slow connections.

dplay_sync

This variable determines whether multiplayer send functions wait until the data is actually sent, or write the data into an internal send buffer and return immediately.

Range:

-1 : Never wait until the data is sent (not recommended - client and server will fall out of sync).

0 : Wait until data is sent for entity updates, don't wait for send instructions (default).

1 : Always wait until the data is sent (behavior prior to version 6.2).

dplay_bps

Approximate data rate of a client in bytes per second (bps). Client only.

dplay_bpspeak

Peak data rate of a client in bytes per second (bps). Client only.

dplay_bpsreliable

dplay_bpsunreliable

Bytes per second received in reliable and unreliable mode.

On the client, these values are for the connection ot the server. On

the server, the values are for the connection to the last connected

client.

The values are indicated in the 4th and 5th row of the net column in

the statistics panel.

dplay_latency

This variable shows the latency time in milliseconds. Latency is the time needed to send a data packet from client to server and receive it back. Inside a LAN, the latency time normally is between 10 and 100 ms, while in the internet it can be up to 300 ms. Client only.

dplay_maxclients

gives the maximum number of clients that can connect to a server.

Range:

1..4, default 4 (Commercial Edition)

1..unlimited, default 25 (Pro Edition)

Remarks:

If more clients try to connect to a session, they are refused. In

the development version error 1403 "Too many clients" is displayed.

dplay_localfunction

Start entity actions in a loaded level even on a client. Can be used

for local entity functions without the need to send the function by

proc_local or proc_client.

Affects the level_load, but not the ent_create instruction. The

entity action could use the connection variable to decide whether

it's running on the client or on the server, and behave accordingly.

dplay_packetsize

Maximum size of an UDP network message packet, in bytes. The engine

collects messages in a buffer until they sum up to the given size,

then they are sent together in a single packet.

Range:

0..1024, default 128.

Remarks:

The message buffer is sent at least once per frame, even if the packet

size is not reached. At a packet size of 0, messages are not buffered

but sent straight away. The bigger the packet size, the less packets

are sent, but the slower they travel over the net. The packet size

should be less than 1000 bytes, because routers or other equipment on

the internet often delay or drop larger UDP packets.

dplay_dropped

Number of packets per second that did not reach the target machine

because they were lost on the internet or timed out due to low

bandwidth. Indicated in the 5th row of the statistics panel Net column.

Can be used to determine whether a game is playable on a certain

connection, or to automatically reduce the dplay_entrate when a lot of

packets are dropped.

connection

This variable is set to 0 at game start. As soon as a multiplayer connection is established, it is automatically set to 1, 2, or 3, dependent on the engine running in server, client, or client/server mode.

Range:

connection == 0 No connection to Multiplayer system

connection == 1 Connection as Server to Multiplayer system

connection == 2 Connection as Client to Multiplayer system

connection == 3 Connection as Server and Client to Multiplayer system

server_ip

These predefined strings hold the name and the first IP address of the server in a multiplayer game. On a client the strings are empty. They can be used to display the information the clients have to enter in the IP field in order to connect.

Remarks:

For connecting on a local network the server name can be used; for connecting over the internet the IP address or the domain name must be used.

server_name

Remarks:

For connecting on a local network the server name can be used; for connecting over the internet the IP address or the domain name must be used.

session_name

Contains the name of the current session in multiplayer mode.

session_connect (sessionname, hostname); (Pro)

Switches to a different session on another server. The first string parameter contains the name of the new session, the second parameter gives the name, domain or IP address of the new server. This way, level or zone changing in a multiplayer environment can easily be performed:

Remarks:

If an empty string is given for the server IP, a dialogue box will pop up for entering the domain name or IP manually. If the server or session is not found, an error message will appear.

Parameters:

sessionname - Name of Session

hostname - Domain- or IP Address

event_disconnect

entity.enable_disconnect

The entities' client has disconnected and left the multiplayer game. The EVENT function can be used to remove the entity.

Important:

After start of an EVENT function, all event-dependent variables and pointer s, like NORMAL etc., keep their values only until the next wait instruction. During the wait pause they can (and certainly will) be changed from other functions. If you want to keep them longer, copy them into entity skills. For clarity, let the entities' main action do most of the work, and keep the EVENT function as short and simple as possible, without any wait instructions.

event_receive

entity.enable_receive

This event is triggered when the entity receives a skill sent by send_skill.

Remarks:

send_skill(entity.skill,var mode)

Sends the given entity parameter - for instance, a skill or skill

vector - to the other PCs in a network. If executed on a server, it

sends the skill to the creator of the entity, or to all clients. If

executed on a client, it sends the skill to the server. The skill or

skill vector is updated on the same entity instance on the other PCs.

Returns:

0 if the parameter was not sent due to SEND_RATE or for other reasons,

otherwise nonzero.

Parameters (new):

entity.skill - the entity parameter to be sent.

mode - either 0 or a combination of the following flags:

SEND_VEC - send 3 consecutive skills used as a vector.

SEND_ALL - send to all clients, rather than to the creator of the entity (only when executed on the server).

SEND_UNRELIABLE - send in unreliable mode. Otherwise it's sent in reliable mode.

SEND_RATE - send only every n'th frame, while n = dplay_entrate/time.

Remarks:

- Triggers event_receive on the target entity.

- The entity must exist on the target machine. So don't perform this

instruction immediately after creating the entity. Use sleep(0.5)

to wait until all target machines have received the newly created

entity.

- Send most entity parameters, like user input, in unreliable mode.

Only important entity status changes like shooting or opening a door

should be send in reliable mode. Reliable messages won't expire, which

could result in a buffer overflow and falling out of sync on slow

connections when many reliable messages are sent.

send_string (string);

send_string_to (entity, string);

Through this instruction the given string is sent from a client to the server, or from the server to all clients. The ON_server or on_client event function is triggered on each PC which has received the string, the content of that string is replaced by the received string. This instruction can be used for exchanging messages, but also for executing instructions on all clients simultaneously.

Parameters:

string - string to send

Remarks:

send_string_to executed on the server sends the string only to client who has created the given entity. When executed on the client it sends the string to the server, regardeless of which entity is given.

send_var (var);

send_var_to (entity, var);

Sends a variable or an array from a client to the server, or from a server to all clients. The ON_server or on_client event function is triggered on each PC which has received the variable, the content of the variable or array is replaced by the new values. Only user-defined variables can be sent; predefined system variables or old-style skills can't be sent. If the variable is a vector or an array, all elements are sent.

Parameters:

var - variable which should be send.

Remarks:

send_var_to executed on the server sends the variable only to client who has created the given entity. When executed on the client it sends the variable to the server, regardeless of which entity is given.

proc_local(entity,function)

proc_client(entity,function)

These instructions start a client-side function for the given entity.

Proc_local starts the given function on all clients.

Proc_client starts the given function only on the client which has created the given entity or it's creator entity.

Local or client functions can be used for detecting local mouse events, for starting local sound or particle effects, or for local entity animation.

Parameters:

entity - Entity which function should be started

function - to started Function

Remarks:

· These instructions can only be executed on the server in a multiplayer game. The function does not run on the server, only on the clients. The entity must also exist on the clients, and will become the MY entity for the local functions.

· The last proc_local instruction of each entity is stored. If a new client connects, it is started again on this client. Therefore local functions will even run on clients that connect after the proc_local execution on the server. For using this mechanism, do not start more than one proc_local instruction per entity.

· By using the connection variable, a function can do different things dependent on whether it's running on the server, on a client, or on both.

proc_kill (var mode)

Terminates another function. Each function can be started several times, so many instances of the same function can be running simultaneously. proc_kill will terminate all instances of a certain function, with a filter set by mode. Modes can be combined by adding.

Parameters:

mode = 1 terminates all functions created by the MY entity.

mode = 2 terminates all functions created by the YOU entity.

mode = 4 terminates all other instances of the current function.

proc_late();

Moves the current function to the very end of the function scheduler list. Necessary when the execution order of functions within one frame cycle is important, which is the case when the function needs results or entity or camera positions that are calculated by other functions. The other functions must then run earlier during each frame cycle.

Modifies:

Function is set at the end to the scheduler list

entity.nosend

Prevents sending of any entity parameter updates from server to clients.

Range:

on - send no parameter updates.

off - send parameter updates (default)

Remarks:

Normally the server periodically updates all changed entity parameter on the clients. For reducing the bandwidth, certain parameters, or even all, can be exempt from the updates. Those parameters can then be set by local functions (proc_local) on the client side. By fine-tuning the parameters to be sent, and doing entity effects and animation on the client side, the network traffic can be remarkably reduced and two or three times as much clients can be served.

When setting this flag immediately after entity creation, the entity can remain invisible on the client because it's file name and position is not sent. For preventing this, set a nosend flag only after the time between two entity updates, given by dplay_entrate, is passed.

entity.nosend_alpha

Prevents sending of alpha.

Range:

on - prevents sending of alpha

off - alpha will send form server to client. (default)

entity.nosend_ambient

Prevents sending of ambient and albedo.

Range:

on - prevents sending of ambient and albedo.

off - ambient and albedo will be sent (default)

entity.nosend_angles

Prevents sending of pan, tilt, roll.

Range:

on - prevents sending of pan, tilt, roll.

off - pan, tilt, roll will be sent to the clients (default)

entity.nosend_attach

Prevents sending any ent_morphskin instructions.

Range:

on - ent_morphskin won't be sent, the skin changes only locally.

off - ent_morphskin will be sent to the clients.

entity.nosend_color

Prevents sending of red, green, or blue.

Range:

on - prevents sending of red, green, or blue.

off - red, green, or blue will be sent to the clients (default)

entity.nosend_flags

Prevents sending of all visual entity flags.

Range:

on - don't send visual entity flags.

off - send them to the clients (default).

entity.nosend_frame

Prevents sending of frame and next_frame.

Range:

on - prevents sending of frame and next_frame.

off - frame and next_frame will be sent to the clients (default)

entity.nosend_light

Prevents sending of lightrange.

Range:

on - prevents sending of lightrange.

off - lightrange will be sent to the clients (default)

entity.nosend_origin

Prevents sending of x,y,z.

Range:

on - prevents sending of x,y,z.

off - x,y,z will be sent to the clients (default)

entity.nosend_scale

Prevents sending of scale_x, scale_y, scale_z.

Range:

on - prevents sending of scale_x, scale_y, scale_z.

off - scale_x, scale_y, scale_z will be sent to the clients (default)

entity.nosend_skin

Prevents sending of the skin number.

Range:

on - prevents sending of the skin number.

off - skin number will be sent to the clients (default)

entity.nosend_sound

Prevents sending entity_sounds.

Range:

on - prevents sending entity_sounds.

off - entity_sounds will be sent to the clients (default)

entity.nosend_uv

Prevents sending of u,v.

Range:

on - prevents sending of u,v.

off - Texture offsets u,v will be sent (default)

on_server = function

The function is executed when the server receives a message from a client. The event_type variable is set to the type of the message. When the message contains a string, a pointer to the received string is handed over as parameter to the function.

Remarks:

There are 4 types of server events:

event_join: A client has joined the session. The client name is handed over.

event_leave: A client has left the session. The client name is handed over.

event_string: A client has sent a string to the server. The string pointer is handed over.

event_var: A client has sent a variable or an array to the server.

on_client = function

The given function is executed when a client receives a message from the server. The event_type variable is set to the type of the message. When the message contains a string, a pointer to the received string is handed over as parameter to the function.All key, mouse, or other event functions may be changed anytime by other functions (eg. ON_F1 = function;), so that the same key or button may start different functions at different times.

Remarks:

There are 2 types of client events:

event_string: The server has sent a string to all clients. The string pointer is handed over.

event_var: The server has sent a variable or an array.

ent_createlocal (string filename, vector Position, function);

Creates a entity locally on client. A local entity is not transmitted to the server, and thus not visible on other clients. The entity function runs on the local machine. Local entities can be used for advanced particle effects, player weapons or the like.

Previous Page Contents Next Page