Home

A simple start.

Introduction

This article explains how to perform UDP networking in Onyx.

** Note that this is still alpha functionality - the syntax may change - this page updated for v0.9.0RC6 **

UDP networking is used heavily in Racer for all kinds of communication over ethernet. You can access UDP networking functionality in Onyx to perform your own UDP networking.

Onyx comes in 2 parts; Onyx outside of Racer and Onyx inside Racer. The external variant may be useful sometimes to use Onyx as a sort of BASIC, but then with a C++-like syntax. Racer comes with onyx_run.exe, which can be used to run Onyx scripts (that have no link to Racer) as is. In Racer itself, there is the 'run' command which compiles & runs Onyx scripts (.oxs).

Sending out a string

This example sends out a simple string in a single packet. Note that to verify the functionality, you can run udpterm (which is included in each Racer installation, look for udpterm.exe). By default, UDPTerm will listen to UDP port 7000 and print the (ASCII) contents of each packet that comes in.

void main()
{
  handle h;

  h=UDPOpen("127.0.0.1",7000);
  UDPWriteString(h,"Hello");
  UDPClose(h);
}

Handles are generic values that will point to actual objects inside the Racer engine. In this case, the handle represents the UDP network handle.

Note that in the future, this functionality will probably be wrapped in a class.

Writing binary data

Strings are often not the way you want to communicate. Binary data is normally shorter, and can be used to interface to other applications outside of Racer. Here is an example how to write a piece of binary data to UDP.

class Vector3
{
  float x,y,z;
};

Vector3 v;
handle  h;

void main()
{
  v.x=123;
  v.y=124;
  v.z=125;
  h=UDPOpen("127.0.0.1",7000);
  UDPWrite(h,&v,sizeof(Vector3));
  UDPClose(h); 
}

The 'Vector3' class has 3 floats. This matches the C++ layout that would be written the same way. It will be 12 bytes large. The packet that is sent out will also be 12 bytes long.

To verify this one, use udpterm's hexadecimal option; run udpterm as 'udpterm 7000 -hex'. The received packet will be displayed as hexadecimal values.

Reading binary data

Reading binary packets can be done as follows (Racer v0.9.0RC8+). Notice the empty host string in the call to UDPOpen().

class Vector3
{
  float x,y,z;
};
Vector3 v;

void main()
{
  handle h;
  int n;

  h=UDPOpen("",7000);              // All hosts are accepted

  echo("Waiting for a packet to arrive...");
  while(1)
  {
    n=UDPRead(h,&v,sizeof(v));
    if(n>0)break;
  }

  echo("Packet received. Bytes:");
  echo(n);
  echo("Contents: (x)");
  echo(v.x);

  UDPClose(h);
}

Note that 'n' contains the number of bytes actually read. You pass a length to UDPRead() (sizeof(v) in the above example), and reading will be restricted to that buffer length, to avoid memory overflows when a larger packet arrives.

(last updated August 8, 2013 )