Onyx Function Reference

Onyx function reference

A simple start.

Dolphinity Organiser - free planning, project management and organizing software for all your action lists

This article lists available engine functions. These functions call into the C++ engine, so they are the portal between the C++ and the Onyx world.

Group	Function prototype	Description
Math	float abs(float x)	returns the absolute number of 'x'
	float acos(float x)	returns the acosine value of 'x'
	float asin(float x)	returns the asine value of 'x'
	float atan2(float y,float x)	returns the arctangent of y/x in radians.
	float cos(float x)	returns the cosine
	float deg2rad(float x)	Converts degrees to radians.
	float lerp(float x,float y,float s)	Linear interpolation; returns *x+s(y-x)**. No clamping is used on any value.
	float rad2deg(float x)	Converts radians to degrees.
	int rand()	returns a random number between 0 and 32767.
	float sin(float x)	returns the sine of 'f' (in radians)
	float sqrt(float x)	returns the square root of 'x'
	void srand(int seed)	Sets the seed for the rand() function.
	float tan(float x)	returns the tangent
	float EaseIn(float x1,float x2,float t,float d)	Easing in. t=time, d=duration (i.e. EaseIn(10,20,1.5,3.0) will give the value between 10 and 20 halfway the time). v0.9.0RC8+
	float EaseOut(float x1,float x2,float t,float d)	Easing out.
	float EaseInOut(float x1,float x2,float t,float d)	Easing in and out.
	float EaseInElastic(float x1,float x2,float t,float d)	Easing in only with an elastic edge.
	float EaseOutElastic(float x1,float x2,float t,float d)	Easing out with an elastic effect.
Output	void echo(int) void echo(float) void echo(string)	Echoes a value to the console.
Networking	void GetHostName(string s)	Returns the hostname in 's' (the COMPUTERNAME environment variable in Windows)
	handle UDPOpen(stringdata host,int port)	Opens a UDP socket. If 'host' is an empty string, this socket can be used for reading. If a 'host' is specified though, it becomes write-only.
	void UDPWrite(handle socket,pointer p,int size)	Writes a binary blob to the socket.
	void UDPWriteString(handle socket,stringdata s)	Writes a string to the socket.
	void UDPClose(handle socket)	Closes the socket.
Shared memory	handle SHMOpenServer(stringdata name,int size)	Opens a shared memory server. This one exposes a piece of shared memory under the give name with the given size. This makes interprocess communication with other real processes or Onyx processes possible. Note that these shared memory parts are operating system-wide.
	void SHMWrite(handle h,pointer p,int size)	Writes a part of the shared memory.
	void SHMClose(handle h)	Closes the shared memory part.
Timing	float time_script()	Returns time in seconds since the script was started.
	void sleep(int ms)	Waits for 'ms' milliseconds. This busy waits, so should generally be avoided!
Miscellaneous	void GetArg(int n,string s)	Returns the argument passed to onyx_run.exe in 's'. Only usable in onyx_run.

Group	Function prototype	Description
Strings	float atof(stringdata s)	Converts a string to floating point.
	int atoi(stringdata s)	Converts a string to integer.
	int split(stringdata s,stringdata delimiter,string[] sOut,int count)	Splits a string into separate string based on a delimiter. For example: *string s[5]; int n=split(''hello world'','' ",s,5);*
	int strcmp(stringdata s1,stringdata s2)	String comparison, like in C++. Returns 0 if the strings are equal. A value greater than zero indicates that the first non-matching character has a greater value in s1 than in s2. A negative value indicates the opposite.
	void str_replace(stringdata s,stringdata search, stringdata replace)	Replaces each occurence of <search> in <s> to <replace>.
	int strpos(stringdata s,stringdata search)	Returns the position of 'search' inside string 's'. Returns -1 if not found. Note the first position is 0. v0.9.0RC9+

Group	Function prototype	Description
.ini files	handle IniOpen(stringdata name)	Opens an ini file and returns a handle, subsequently to be used by the other Ini*() functions.
	void IniClose(handle h)	Closes the ini file, previously opened using IniOpen().
	int IniGetInt(handle h,stringdata path,int default)	Returns an integer value, i.e. int n=IniGetInt(h,"mypath.x",3)
	void IniGetString(handle h,stringdata path,string s,stringdata default)	Returns a string value in 's'. I.e. IniGetString(h,"mypath.name",s,"defaultName")
	float IniGetFloat(handle h,stringdata path,float default)	Reads a floating point value from the file.
File system	void chdir(stringdata s)	Changes the current directory. Try to avoid this in multithreading situations (all threads will share the current directory, which may not be what you want).

Group	Function prototype	Description
Process control	void wait(int event)	OBSOLETE! will halt the script until an event is triggered from inside the engine. The events are key points inside the Racer engine where things can be tweaked; specific events exist for specific purposes. To overrule behavior, you need to use the right event to avoid the effect of your modifications to get lost as the engine calculates new values.
	exit	Stops the virtual thread. Note that a script can have multiple running threads. When exit is called, the SPU is stopped from running any further. So it also stops getting called for future callbacks. This is useful for example in situations where you want to stop the SPU from taking CPU resources (instead of just checking for the same condition over and over).
	int fork()	Forking creates a new thread, running the script on a separate SPU. fork() returns 0 for the child process, and non-zero for the parent process. An example is this: if(fork()==0)g(); else f(). Which runs f() and g() in two separate (virtual) threads. Virtual here means they don't actually multithread, but are run as two separate streams for the virtual machine. See also Unix fork(), where this function was based on. The forked process inherits and shares all variables from its parent process. In practice, you can use this function to run a countdown timer independently for example.
	int ProcessCount(stringdata procName)	Returns the number of processes found which are called 'procName'. I.e. int n=ProcessCount("notepad.exe").
	void system(stringdata s)	Runs the given command, as if from a command prompt.

Group	Function prototype	Description
Debugging	void debug(stringdata s)	Will print using qdbg(), which means a UDP terminal (udpterm.exe) should be used in conjunction with setting dev.udp_out to your UDP terminal's location. I.e. udp_out=192.168.0.101:7000, which writes to UDP port 7000.
	void debugDialog(stringData s)	Shows a dialog with the given text. This is quite intrusive so should be used sparingly.
	void error(stringdata s)	Generates an error, which is written into QLOG.txt.

These functions call into the C++ side of the engine.

Group	Function prototype	Description
Entities	int GetPlayerEID()	Returns the player entity ID. This entity will define any controller output for example (such as force feedback).
	void SetPlayerEID(int eid)	Sets the entity ID of the player. This is required for controllers to start working.
	int GetFocusEID()	Returns the focus entity ID; this is the entity that is being tracked with the camera for example.
	void SetFocusEID(int eid)	Sets the focus entity ID.
Ini files	int IniGlobalGetInt(stringdata key,int default)	Returns an int from the racer.ini main settings file. I.e. int t=IniGlobalGetInt("race.max_time_race",0);
	float IniGlobalGetFloat(stringdata key,float default)	Returns a float from the main settings file (racer.ini).
	void IniGlobalGetString(stringdata key,string s,stringdata default)	Gets the value of the 'key' in 's'.
	handle IniGetMain()	Returns a handle to the main settings file.
Timing	int GetSimTime()	Returns the local simulation time. This time is affected by console commands like 'realtime'.
	int GetServerTime()	Returns the multiplayer (estimated) server time. This timer has the same value on all PC's in the network. It is synchronized, so can be slightly off, but for a LAN environment, this is at most a few milliseconds. Useful to use in animations for example in multiview environments (multiple PC's rendering one scene for multiple monitors/projectors).

These functions are available when running the hardcoded Racer simulation inside the engine.

Group	Function prototype	Description
Cars	int CarsGetCount()	Returns the number of loaded cars.
	handle CarGet(int n)	Returns a handle to car #n.
	handle CarGetLocal()	Returns the handle to the local (player) car.
	void CarGetDirectory(handle hCar,string s)	Returns the car path in 's', i.e. "data/cars/mycar"
	float CarGetLapDistance(handle hCar)	Returns the lap distance for the car.
	int CarGetIndex(handle hCar)	Returns the car index based on a handle.
	void CarMakePaceCar(handle hCar)	Declares a car to be a pace-car.
	void CarSetKinematic(handle hCar,bool yn)	Declares a car kinematically controlled or not, based on 'yn' (true or false).
	void CarWarp(handle hCar,float lapDistance,float u)	Warps a car to a position on the track. 'u' is normally 0.5, but can vary from 0 (left) to 1 (right).
	void CarWarpToPos(handle hCar,Vector3 pos,float yaw)	Warps a car to a world position, with 'yaw' being the initial yaw in radians.
	void CarSetVelocity(handle hCar,float vel)	Sets the velocity of a car. Note that this modifies the selected gear, engine rpm, wheel spin speed and whatever is needed to get an acceptable new state at the new velocity.

Dolphinity Organiser - free planning, project management and organizing software for all your action lists

(last updated March 17, 2014 )