doc/protocol.txt

   1 Minetest protocol (incomplete, early draft):
   2 Updated 2011-06-18
   3
   4 A custom protocol over UDP.
   5 Integers are big endian.
   6 Refer to connection.{h,cpp} for further reference.
   7
   8 Initialization:
   9 - A dummy reliable packet with peer_id=PEER_ID_INEXISTENT=0 is sent to the server:
  10         - Actually this can be sent without the reliable packet header, too, i guess,
  11           but the sequence number in the header allows the sender to re-send the
  12           packet without accidentally getting a double initialization.
  13         - Packet content:
  14                 # Basic header
  15                 u32 protocol_id = PROTOCOL_ID = 0x4f457403
  16                 u16 sender_peer_id = PEER_ID_INEXISTENT = 0
  17                 u8 channel = 0
  18                 # Reliable packet header
  19                 u8 type = TYPE_RELIABLE = 3
  20                 u16 seqnum = SEQNUM_INITIAL = 65500
  21                 # Original packet header
  22                 u8 type = TYPE_ORIGINAL = 1
  23                 # And no actual payload.
  24 - Server responds with something like this:
  25         - Packet content:
  26                 # Basic header
  27                 u32 protocol_id = PROTOCOL_ID = 0x4f457403
  28                 u16 sender_peer_id = PEER_ID_INEXISTENT = 0
  29                 u8 channel = 0
  30                 # Reliable packet header
  31                 u8 type = TYPE_RELIABLE = 3
  32                 u16 seqnum = SEQNUM_INITIAL = 65500
  33                 # Control packet header
  34                 u8 type = TYPE_CONTROL = 0
  35                 u8 controltype = CONTROLTYPE_SET_PEER_ID = 1
  36                 u16 peer_id_new = assigned peer id to client (other than 0 or 1)
  37 - Then the connection can be disconnected by sending:
  38         - Packet content:
  39                 # Basic header
  40                 u32 protocol_id = PROTOCOL_ID = 0x4f457403
  41                 u16 sender_peer_id = whatever was gotten in CONTROLTYPE_SET_PEER_ID
  42                 u8 channel = 0
  43                 # Control packet header
  44                 u8 type = TYPE_CONTROL = 0
  45                 u8 controltype = CONTROLTYPE_DISCO = 3
  46
  47 - Here's a quick untested connect-disconnect done in PHP:
  48 # host: ip of server (use gethostbyname(hostname) to get from a dns name)
  49 # port: port of server
  50 function check_if_minetestserver_up($host, $port)
  51 {
  52         $socket = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);
  53         $timeout = array("sec" => 1, "usec" => 0);
  54         socket_set_option($socket, SOL_SOCKET, SO_RCVTIMEO, $timeout);
  55         $buf = "\x4f\x45\x74\x03\x00\x00\x00\x03\xff\xdc\x01";
  56         socket_sendto($socket, $buf, strlen($buf), 0, $host, $port);
  57         $buf = socket_read($socket, 1000);
  58         if($buf != "")
  59         {
  60                 # We got a reply! read the peer id from it.
  61                 $peer_id = substr($buf, 9, 2);
  62
  63                 # Disconnect
  64                 $buf = "\x4f\x45\x74\x03".$peer_id."\x00\x00\x03";
  65                 socket_sendto($socket, $buf, strlen($buf), 0, $host, $port);
  66                 socket_close($socket);
  67
  68                 return true;
  69         }
  70         return false;
  71 }
  72
  73 - Here's a Python script for checking if a minetest server is up, confirmed working
  74
  75 #!/usr/bin/env python3
  76 import sys, time, socket
  77
  78 address = ""
  79 port = 30000
  80 if len(sys.argv) <= 1:
  81     print("Usage: %s <address>" % sys.argv[0])
  82     exit()
  83 if ":" in sys.argv[1]:
  84     address = sys.argv[1].split(":")[0]
  85     try:
  86         port = int(sys.argv[1].split(":")[1])
  87     except ValueError:
  88         print("Please specify a valid port")
  89         exit()
  90 else:
  91     address = sys.argv[1]
  92
  93 try:
  94     start = time.time()
  95     sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
  96     sock.settimeout(2.0)
  97     buf = b"\x4f\x45\x74\x03\x00\x00\x00\x01"
  98     sock.sendto(buf, (address, port))
  99     data, addr = sock.recvfrom(1000)
 100     if data:
 101         peer_id = data[12:14]
 102         buf = b"\x4f\x45\x74\x03" + peer_id + b"\x00\x00\x03"
 103         sock.sendto(buf, (address, port))
 104         sock.close()
 105         end = time.time()
 106         print("%s is up (%0.5fms)" % (sys.argv[1], end - start))
 107     else:
 108         print("%s seems to be down " % sys.argv[1])
 109 except Exception as err:
 110     print("%s seems to be down (%s) " % (sys.argv[1], str(err)))