OSCII-bot code reference

OSCII-bot code reference

Generated by OSCII-bot v0.6

Scripts use lines beginning with @ to specify various parameters:

@input : specifies a device to open for input. Usage:

@input devicehandle MIDI "substring devicename match" [skip_count]
@input devicehandle OSC "1.2.3.4:port"
@input devicehandle OSC "*:port"
@input devicehandle OMNI-MIDI -- receives all MIDI received by other scripts
@input devicehandle OMNI-OSC -- receives all OSC received by other scripts
@input devicehandle OMNI-MIDI-OUTPUT -- receives all MIDI sent by other scripts
@input devicehandle OMNI-OSC-OUTPUT -- receives all OSC sent by other scripts
Note: in OSCII-bot v0.4+, you can send OSC messages to an OSC input device, which will send to the IP/port of
the last message received.
@output : specifies a device to open for output. Usage:
@output devicehandle OSC "host:port" [maxpacketsize (def=1024)] [sleepinMS (def=10)]
@output devicehandle MIDI "substring match" [skip]
Note: in OSCII-bot v0.4+, you may also receive messages from an OSC output (if the other end replies).
@init : begins code that is executed on script load/recompile.
@timer : begins code that is executed periodically, usually around 100 times per second.
@midimsg : begins code that is executed on receipt of a MIDI message. In this case, msg1/msg2/msg3 will be set
to the parameters of the MIDI message, and msgdev will receive the MIDI device index. In OSCII-bot v0.5+, if a
SysEx message is received, msg1/msg2/msg3 will all be 0, and oscstr will be set to a string with the SysEx data.
@oscmsg : begins code that is executed on receipt of an OSC message. In this case, msgdev will specify the
device, oscstr will be set to a string that specifies the OSC message, and see oscparm() to query the values of the
OSC parameters. To quickly match the OSC message against various strings, see match() or see oscmatch().
@import : import functions from other reascripts using @import filename.txt -- note that only the file's
functions will be imported, normal code in that file will not be executed.

Special variables:

msg1/msg2/msg3: used to specify MIDI message values received by @midimsg or sent (see midisend())
msgdev: specifies the device on receipt of a MIDI or OSC message in @midimsg or @oscmsg
oscstr: specifies a string of a received OSC message in @oscmsg, or (OSCII-bot v0.5+) of a SysEx message in
@midimsg. Will be set to -1 if not valid.
fmt0..fmt31: specifies (deprecated) format values for various functions including sprintf(), match(), oscmatch(),
etc.
time: set to a timestamp in seconds with at least millisecond granularity

The code for OSCII-bot is written in a simple language (called EEL2), which has many similarities to C. Code is written
in one or more of the code sections listed above. Some basic features of this language are:

Variables do not need to be declared, are by default global, and are all double-precision floating point, or strings if
a # prefix is specified
Basic operations including addition (+), subtraction (-), multiplication (*), division (/), and exponential (^)
Bitwise operations including OR (|), AND (&), XOR (~), shift-left (<<), and shift-right-sign-extend (>>). These
all convert to integer for calculation.
Parentheses '(' and ')' can be used to clarify precidence, contain parameters for functions, and collect multiple
statements into a single statement.
A semicolon ';' is used to separate statements from eachother (including within parentheses).
A virtual local address space of about 8 million words, which can be accessed via brackets '[' and ']'.

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]
OSCII-bot code reference

A shared global address space of about 1 million words, accessed via gmem[]. These words are shared between
all OSCII-bot scripts.
Shared global named variables, accessible via the '_global.' prefix. These variables are shared between all OSCII-
bot scripts.
User definable functions, which can define private variables, parameters, and also can optionally access
namespaced instance variables.
Numbers are in normal decimal, however if you prefix $x or 0x to them, they will be hexadecimal (i.e. $x90,
0xDEADBEEF, etc)
You may specify the ASCII value of a character using $'c' or 'c' (where c is the character). You can also specify
multibyte characters using 'xy'
If you wish to generate a mask of 1 bits in integer, you can use $~X, for example $~7 is 127, $~8 is 255, $~16 is
65535, etc.
Comments can be specified using:
// comments to end of line
/* comments block of code that span lines or be part of a line */

Operator reference
Listed from highest precedence to lowest (but one should use parentheses whenever there is doubt!):

[]
z=x[y];
x[y]=z;

You may use brackets to index into memory that is local to your script. Your script has approximately 8 million
(8,388,608) slots of memory and you may access them either with fixed offsets (i.e. 16811[0]) or with variables
(myBuffer[5]). The sum of the value to the left of the brackets and the value within the brackets is used to index
memory. If a value in the brackets is omitted then only the value to the left of the brackets is used.
z=gmem[y];
gmem[y]=z;

If 'gmem' is specified as the left parameter to the brackets, then the global shared buffer is used, which is
approximately 1 million (1,048,576) slots that are shared across all scripts

!value -- returns the logical NOT of the parameter (if the parameter is 0.0, returns 1.0, otherwise returns 0.0).
-value -- returns value with a reversed sign (-1 * value).
+value -- returns value unmodified.

base ^ exponent -- returns the first parameter raised to the power of the second parameter. This is also available
the function pow(x,y)

numerator % denominator -- divides two values as integers and returns the remainder.

value << shift_amt -- converts both values to 32 bit integers, bitwise left shifts the first value by the second. Note
that shifts by more than 32 or less than 0 produce undefined results.

value >> shift_amt -- converts both values to 32 bit integers, bitwise right shifts the first value by the second,
with sign-extension (negative values of y produce non-positive results). Note that shifts by more than 32 or less
than 0 produce undefined results.

value / divisor -- divides two values and returns the quotient.

value * another_value -- multiplies two values and returns the product.

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]
OSCII-bot code reference

value - another_value -- subtracts two values and returns the difference.

value + another_value -- adds two values and returns the sum.

a | b -- converts both values to integer, and returns bitwise OR of values.

a & b -- converts both values to integer, and returns bitwise AND of values.
a ~ b -- converts both values to 32 bit integers, bitwise XOR the values.

value1 == value2 -- compares two values, returns 1 if difference is less than 0.00001, 0 if not.
value1 === value2 -- compares two values, returns 1 if exactly equal, 0 if not.
value1 != value2 -- compares two values, returns 0 if difference is less than 0.00001, 1 if not.
value1 !== value2 -- compares two values, returns 0 if exactly equal, 1 if not.
value1 < value2 -- compares two values, returns 1 if first parameter is less than second.
value1 > value2 -- compares two values, returns 1 if first parameter is greater than second.
value1 <= value2 -- compares two values, returns 1 if first is less than or equal to second.
value1 >= value2 -- compares two values, returns 1 if first is greater than or equal to second.

y || z -- returns logical OR of values. If 'y' is nonzero, 'z' is not evaluated.

y && z -- returns logical AND of values. If 'y' is zero, 'z' is not evaluated.

y ? z      -- how conditional branching is done -- similar to C's if/else

y?z:x

If y is non-zero, executes and returns z, otherwise executes and returns x (or 0.0 if ': x' is not specified).

Note that the expressions used can contain multiple statements within parentheses, such as:

x % 5 ? (
f += 1;
x *= 1.5;
) : (
f=max(3,f);
x=0;
);

y = z -- assigns the value of 'z' to 'y'. 'z' can be a variable or an expression.

y *= z -- multiplies two values and stores the product back into 'y'.
y /= divisor -- divides two values and stores the quotient back into 'y'.
y %= divisor -- divides two values as integers and stores the remainder back into 'y'.
base ^= exponent -- raises first parameter to the second parameter-th power, saves back to 'base'
y += z -- adds two values and stores the sum back into 'y'.
y -= z -- subtracts 'z' from 'y' and stores the difference into 'y'.
y |= z -- converts both values to integer, and stores the bitwise OR into 'y'
y &= z -- converts both values to integer, and stores the bitwise AND into 'y'
y ~= z -- converts both values to integer, and stores the bitwise XOR into 'y'

Some key notes about the above, especially for C programmers:

( and ) (vs { } ) -- enclose multiple statements, and the value of that expression is the last statement within the
block:
z = (
a = 5;
b = 3;
a+b;

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]
OSCII-bot code reference

); // z will be set to 8, for example

Conditional branching is done using the ? or ? : operator, rather than if()/else.

a < 5 ? b = 6; // if a is less than 5, set b to 6
a < 5 ? b = 6 : c = 7; // if a is less than 5, set b to 6, otherwise set c to 7
a < 5 ? ( // if a is less than 5, set b to 6 and c to 7
b = 6;
c = 7;
);

The ? and ?: operators can also be used as the lvalue of expressions:

(a < 5 ? b : c) = 8; // if a is less than 5, set b to 8, otherwise set c to 8

Strings
Strings can be specified as literals using quotes, such as "This is a test string". Much of the syntax mirrors that of C: you
must escape quotes with backslashes to put them in strings ("He said \"hello, world\" to me"), multiple literal strings
will be automatically concatenated by the compiler. Unlike C, quotes can span multiple lines. There is a soft limit on the
size of each string: attempts to grow a string past about 16KB will result in the string not being modified.

Strings are always refered to by a number, so one can reference a string using a normal JS variable:
x = "hello world";
gfx_drawstr(x);

Literal strings are mutable in OSCII-bot, and you can also have other named strings:

You can use the fixed values of 0-1023:

x = 50; // string slot 50
strcpy(x, "hello ");
strcat(x, "world");
gfx_drawstr(x);

This mode is useful if you need to build or load a table of strings.

You can use # to get an instance of a temporary string:

x = #;
strcpy(x, "hello ");
strcat(x, "world");
gfx_drawstr(x);

Note that the scope of these temporary instances is very limited and unpredictable, and their initial values are
undefined.

Finally, you can use named strings, which are the equivalent of normal variables:
x = #myString;
strcpy(x, "hello world");

The value of named strings is defined to be empty at script load, and to persist throughout the life of your script.
There is also a shortcut to assign/append to named strings:
#myString = "hello "; // same as strcpy(#myString, "hello ");
#myString += "world"; // same as strcat(#myString, "world");

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]
OSCII-bot code reference

Function List
while   memcpy     strlen     eval     gfx_init     gfx_printf    
 
loop   memset     strcpy     tcp_listen     gfx_quit     gfx_blurto    
 
sin     mem_get_values     strcat     tcp_listen_end gfx_aaaaa     gfx_blit    
   
cos     mem_set_values     strcmp     tcp_connect     gfx_getchar     gfx_blit    
tan     stack_push     stricmp     tcp_send     gfx_showmenu     gfx_blitext    
sqrt   stack_pop     strncmp     tcp_recv     gfx_setcursor   gfx_getimgdim    
   
log     stack_peek     strnicmp     tcp_set_block   gfx_lineto     gfx_setimgdim    
 
log10   stack_exch     strncpy     tcp_close     gfx_line     gfx_loadimg    
 
asin   rand     strncat     fopen     gfx_rectto     gfx_gradrect    
 
acos   midisend     strcpy_from   fclose     gfx_rect     gfx_muladdrect    
   
atan   midisend_str     strcpy_substr fread     gfx_setpixel     gfx_deltablit    
     
atan2   oscsend     str_getchar   fgets     gfx_getpixel     gfx_transformblit  
     
exp     oscmatch     str_setchar   fgetc     gfx_drawnumber   gfx_circle    
   
abs     oscparm     str_setlen    
fwrite     gfx_drawchar     gfx_triangle    
get_device_open_time
sqr         str_delsub     fprintf     gfx_drawstr     gfx_roundrect    

min     printf     str_insert     fseek     gfx_measurestr   gfx_arc    

 
max     sprintf     sleep     ftell     gfx_measurechar gfx_set    
   
sign   matchi     time     feof     gfx_setfont      gfx_clienttoscreen
   
floor   match     time_precise   fflush     gfx_screentoclient
gfx_getfont        
   
ceil   strlen     eval    
 

while(expression)

Executes expression until expression evaluates to zero, or until 1048576iterations occur. An alternate and more useful
syntax is while (expression) ( statements ), which evaluates statements after every non-zero evaluation of expression.

loop(count,expression)

Evaluates count once, and then executes expression count, but not more than 1048576, times.

sin(angle)

Returns the sine of the angle specified (specified in radians -- to convert from degrees to radians, multiply by $pi/180, or
0.017453).

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]
OSCII-bot code reference

cos(angle)

Returns the cosine of the angle specified (specified in radians).

tan(angle)

Returns the tangent of the angle specified (specified in radians).

sqrt(value)

Returns the square root of the parameter. If the parameter is negative, the return value is undefined.

log(value)

Returns the natural logarithm (base e) of the parameter. If the value is not greater than 0, the return value is undefined.

log10(value)

Returns the base-10 logarithm of the parameter. If the value is not greater than 0, the return value is undefined.

asin(value)

Returns the arc sine of the value specified (return value is in radians). If the parameter is not between -1.0 and 1.0
inclusive, the return value is undefined.

acos(value)

Returns the arc cosine of the value specified (return value is in radians). If the parameter is not between -1.0 and 1.0
inclusive, the return value is undefined.

atan(value)

Returns the arc tangent of the value specified (return value is in radians). If the parameter is not between -1.0 and 1.0
inclusive, the return value is undefined.

atan2(numerator,denominator)

Returns the arc tangent of the numerator divided by the denominator, allowing the denominator to be 0, and using their
signs to produce a more meaningful result.

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]
OSCII-bot code reference

exp(exponent)

Returns the number e ($e, approximately 2.718) raised to the parameter-th power. This function is significantly faster
than pow() or the ^ operator.

abs(value)

Returns the absolute value of the parameter.

sqr(value)

Returns the square of the parameter (similar to value*value, but only evaluating value once).

min(&value,&value)

Returns (by reference) the minimum value of the two parameters. Since min() returns by reference, expressions such as
min(x,y) = 5 are possible.

max(&value,&value)

Returns (by reference) the maximum value of the two parameters. Since max() returns by reference, expressions such as
max(x,y) = 5 are possible.

sign(value)

Returns 1.0 if the parameter is greater than 0, -1.0 if the parameter is less than 0, or 0 if the parameter is 0.

floor(value)

Returns the value rounded to the next lowest integer (floor(3.9)==3, floor(-3.1)==-4).

ceil(value)

Returns the value rounded to the next highest integer (ceil(3.1)==4, ceil(-3.9)==-3).

invsqrt(value)

Returns a fast inverse square root (1/sqrt(x)) approximation of the parameter.

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]
OSCII-bot code reference

freembuf(address)

Hints the runtime that memory above the address specified may no longer be used. The runtime may, at its leisure,
choose to lose the contents of memory above the address specified.

memcpy(dest,src,length)

Copies length items of memory from src to dest. Regions are permitted to overlap.

memset(offset,value,length)

Sets length items of memory at offset to value.

mem_get_values(offset, ...)

Reads values from memory starting at offset into variables specified. Slower than regular memory reads for less than a
few variables, faster for more than a few. Undefined behavior if used with more than 32767 variables.

mem_set_values(offset, ...)

Writes values to memory starting at offset from variables specified. Slower than regular memory writes for less than a
few variables, faster for more than a few. Undefined behavior if used with more than 32767 variables.

stack_push(&value)

Pushes value onto the user stack, returns a reference to the parameter.

stack_pop(&value)

Pops a value from the user stack into value, or into a temporary buffer if value is not specified, and returns a reference to
where the stack was popped. Note that no checking is done to determine if the stack is empty, and as such stack_pop()
will never fail.

stack_peek(index)

Returns a reference to the item on the top of the stack (if index is 0), or to the Nth item on the stack if index is greater
than 0.

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]
OSCII-bot code reference

stack_exch(&value)

Exchanges a value with the top of the stack, and returns a reference to the parameter (with the new value).

rand([max])

Returns a psuedorandom real number between 0 and the parameter, inclusive. If the parameter is omitted or less than
1.0, 1.0 is used as a maximum instead.

midisend(device_index)

Sends a MIDI event (specified by variables msg1,msg2,msg3) to the device specified by device_index.

device_index can be -100 to send to all outputs opened by application, -1 to send to all outputs opened by script.

midisend_str(device_index,"string")

(v0.5+) Sends a MIDI event (specified by the contents of a string) to the device specified by device_index.

device_index can be -100 to send to all outputs opened by application, -1 to send to all outputs opened by script. Can be
used to send SysEx, for example: midisend_str(midiout, "\xF0\x00\x01\x02\xF7").

oscsend(device_index,"string"[,value,...])

Sends an OSC event (specified by "string" and one or more parameters specifying values) to device specified by
device_index.

device_index can be -100 to send to all outputs opened by application, -1 to send to all outputs opened by script.

"string" is OSC message, and can have a prefix specifying type and count of values.

Additional parameters (after values) will be used as parameters to any format specifiers in "string".

Prefixes are one or more characters of 'f' (float), 'i' (integer), 'b' (bool), 's' (string), which specify an OSC value of that
type.

oscmatch("string"[,format-output])

Matches the current OSC event against "string" (see match()), and puts any matched specifiers (%s, %d, etc) into
parameters specified (or fmt0..fmtX if not specified).

oscmatch() is the equivalent of match("string",oscstr)

oscparm(parm_idx[,type,#string])

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]
OSCII-bot code reference

Gets the parameter value for the current OSC message.

If type is specified, it will be set to the type of the parameter ('f', 's', etc).

If #string is specified and type is 's', #string will be set to the OSC parameter string.

get_device_open_time(device_index)

Returns the timestamp (similar to time_precise()) of the last time this device was opened/re-opened, can be used to
detect device reconnection.

printf("format"[, ...])

Output formatted string to system-specific destination, see sprintf() for more information

sprintf(#dest,"format"[, ...])

Formats a string and stores it in #dest. Format specifiers begin with %, and may include:

%% = %
%s = string from parameter
%d = parameter as integer
%i = parameter as integer
%u = parameter as unsigned integer
%x = parameter as hex (lowercase) integer
%X = parameter as hex (uppercase) integer
%c = parameter as character
%f = parameter as floating point
%e = parameter as floating point (scientific notation, lowercase)
%E = parameter as floating point (scientific notation, uppercase)
%g = parameter as floating point (shortest representation, lowercase)
%G = parameter as floating point (shortest representation, uppercase)

Many standard C printf() modifiers can be used, including:

%.10s = string, but only print up to 10 characters

%-10s = string, left justified to 10 characters
%10s = string, right justified to 10 characters
%+f = floating point, always show sign
%.4f = floating point, minimum of 4 digits after decimal point
%10d = integer, minimum of 10 digits (space padded)
%010f = integer, minimum of 10 digits (zero padded)

Values for format specifiers can be specified as additional parameters to sprintf, or within {} in the format specifier

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]
OSCII-bot code reference

(such as %{varname}d, in that case a global variable is always used).

matchi("needle","haystack"[, ...])

Case-insensitive version of match().

match("needle","haystack"[, ...])

Searches for the first parameter in the second parameter, using a simplified regular expression syntax.

* = match 0 or more characters

*? = match 0 or more characters, lazy
+ = match 1 or more characters
+? = match 1 or more characters, lazy
? = match one character

You can also use format specifiers to match certain types of data, and optionally put that into a variable:

%s means 1 or more chars

%0s means 0 or more chars
%5s means exactly 5 chars
%5-s means 5 or more chars
%-10s means 1-10 chars
%3-5s means 3-5 chars
%0-5s means 0-5 chars
%x, %d, %u, and %f are available for use similarly
%c can be used, but can't take any length modifiers
Use uppercase (%S, %D, etc) for lazy matching

See also sprintf() for other notes, including specifying direct variable references via {}.

strlen("str")

Returns the length of the string passed as a parameter

strcpy(#str,"srcstr")

Copies the contents of srcstr to #str, and returns #str

strcat(#str,"srcstr")

Appends srcstr to #str, and returns #str

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]
OSCII-bot code reference

strcmp("str","str2")

Compares strings, returning 0 if equal

stricmp("str","str2")

Compares strings ignoring case, returning 0 if equal

strncmp("str","str2",maxlen)

Compares strings giving up after maxlen characters, returning 0 if equal

strnicmp("str","str2",maxlen)

Compares strings giving up after maxlen characters, ignoring case, returning 0 if equal

strncpy(#str,"srcstr",maxlen)

Copies srcstr to #str, stopping after maxlen characters. Returns #str.

strncat(#str,"srcstr",maxlen)

Appends srcstr to #str, stopping after maxlen characters of srcstr. Returns #str.

strcpy_from(#str,"srcstr",offset)

Copies srcstr to #str, but starts reading srcstr at offset offset

strcpy_substr(#str,"srcstr",offs,ml))

PHP-style (start at offs, offs<0 means from end, ml for maxlen, ml<0 = reduce length by this amt)

str_getchar("str",offset[,type])

Returns the data at byte-offset offset of str. If offset is negative, position is relative to end of string.type defaults to
signed char, but can be specified to read raw binary data in other formats (note the single quotes, these are single/multi-
byte characters):

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]
OSCII-bot code reference

'c' - signed char

'cu' - unsigned char
's' - signed short
'S' - signed short, big endian
'su' - unsigned short
'Su' - unsigned short, big endian
'i' - signed int
'I' - signed int, big endian
'iu' - unsigned int
'Iu' - unsigned int, big endian
'f' - float
'F' - float, big endian
'd' - double
'D' - double, big endian

str_setchar(#str,offset,val[,type]))

Sets value at offset offset, type optional. offset may be negative to refer to offset relative to end of string, or between 0
and length, inclusive, and if set to length it will lengthen string. see str_getchar() for more information on types.

str_setlen(#str,len)

Sets length of #str (if increasing, will be space-padded), and returns #str.

str_delsub(#str,pos,len)

Deletes len characters at offset pos from #str, and returns #str.

str_insert(#str,"srcstr",pos)

Inserts srcstr into #str at offset pos. Returns #str

sleep(ms)

Yields the CPU for the millisecond count specified, calling Sleep() on Windows or usleep() on other platforms.

time([&val])

Sets the parameter (or a temporary buffer if omitted) to the number of seconds since January 1, 1970, and returns a
reference to that value. The granularity of the value returned is 1 second.

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]
OSCII-bot code reference

time_precise([&val])

Sets the parameter (or a temporary buffer if omitted) to a system-local timestamp in seconds, and returns a reference to
that value. The granularity of the value returned is system defined (but generally significantly smaller than one second).

eval("code")

Executes code passed in. Code can use functions, but functions created in code can't be used elsewhere.

tcp_listen(port[,"interface",#ip_out])

Listens on port specified. Returns less than 0 if could not listen, 0 if no new connection available, or greater than 0 (as a
TCP connection ID) if a new connection was made. If a connection made and #ip_out specified, it will be set to the
remote IP. interface can be empty for all interfaces, otherwise an interface IP as a string.

tcp_listen_end(port)

Ends listening on port specified.

tcp_connect("address",port[,block])

Create a new TCP connection to address:port. If block is specified and 0, connection will be made nonblocking. Returns
TCP connection ID greater than 0 on success.

tcp_send(connection,"str"[,len])

Sends a string to connection. Returns -1 on error, 0 if connection is non-blocking and would block, otherwise returns
length sent. If len is specified and not less than 1, only the first len bytes of the string parameter will be sent.

tcp_recv(connection,#str[,maxlen])

Receives data from a connection to #str. If maxlen is specified, no more than maxlen bytes will be received. If non-
blocking, 0 will be returned if would block. Returns less than 0 if error.

tcp_set_block(connection,block)

Sets whether a connection blocks.

tcp_close(connection)

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]
OSCII-bot code reference

Closes a TCP connection created by tcp_listen() or tcp_connect().

fopen("fn","mode")

Opens a file "fn" with mode "mode". For read, use "r" or "rb", write "w" or "wb". Returns a positive integer on success.

fclose(fp)

Closes a file previously opened with fopen().

fread(fp,#str,length)

Reads from file fp into #str, up to length bytes. Returns actual length read, or negative if error.

fgets(fp,#str)

Reads a line from file fp into #str. Returns length of #str read.

fgetc(fp)

Reads a character from file fp, returns -1 if EOF.

fwrite(fp,#str,len)

Writes up to len characters of #str to file fp. If len is less than 1, the full contents of #str will be written. Returns the
number of bytes written to file.

fprintf(fp,"format"[,...])

Formats a string and writes it to file fp. For more information on format specifiers, see sprintf(). Returns bytes written to
file.

fseek(fp,offset,whence)

Seeks file fp, offset bytes from whence reference. Whence negative specifies start of file, positive whence specifies end
of file, and zero whence specifies current file position.

ftell(fp)

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]
OSCII-bot code reference

Retunrs the current file position.

feof(fp)

Returns nonzero if the file fp is at the end of file.

fflush(fp)

If file fp is open for writing, flushes out any buffered data to disk.

gfx_init("name"[,width,height,xpos,ypos])

Initializes the graphics window with title name. Suggested width and height can be specified.

Once the graphics window is open, gfx_update() should be called periodically.

gfx_quit()

Closes the graphics window.

gfx_aaaaa()

The following global variables are special and will be used by the graphics system:

gfx_r, gfx_g, gfx_b, gfx_a - These represent the current red, green, blue, and alpha components used by drawing
operations (0.0..1.0).
gfx_w, gfx_h - These are set to the current width and height of the UI framebuffer.
gfx_x, gfx_y - These set the "current" graphics position in x,y. You can set these yourselves, and many of the
drawing functions update them as well.
gfx_mode - Set to 0 for default options. Add 1.0 for additive blend mode (if you wish to do subtractive, set gfx_a
to negative and use gfx_mode as additive). Add 2.0 to disable source alpha for gfx_blit(). Add 4.0 to disable
filtering for gfx_blit().
gfx_clear - If set to a value greater than -1.0, this will result in the framebuffer being cleared to that color. the
color for this one is packed RGB (0..255), i.e. red+green*256+blue*65536. The default is 0 (black).
gfx_dest - Defaults to -1, set to 0..127 to have drawing operations go to an offscreen buffer (or loaded image).
gfx_texth - Set to the height of a line of text in the current font. Do not modify this variable.
gfx_ext_retina - If set to 1.0 on initialization, will be updated to 2.0 if high resolution display is supported, and if
so gfx_w/gfx_h/etc will be doubled.
mouse_x, mouse_y - mouse_x and mouse_y are set to the coordinates of the mouse relative to the graphics
window.
mouse_wheel, mouse_hwheel - mouse wheel (and horizontal wheel) positions. These will change typically by 120
or a multiple thereof, the caller should clear the state to 0 after reading it.
mouse_cap is a bitfield of mouse and keyboard modifier state.
1: left mouse button

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]
OSCII-bot code reference

2: right mouse button

4: Control key
8: Shift key
16: Alt key
32: Windows key
64: middle mouse button

gfx_getchar([char])

If char is 0 or omitted, returns a character from the keyboard queue, or 0 if no character is available, or -1 if the graphics
window is not open. If char is specified and nonzero, that character's status will be checked, and the function will return
greater than 0 if it is pressed.

Common values are standard ASCII, such as 'a', 'A', '=' and '1', but for many keys multi-byte values are used, including
'home', 'up', 'down', 'left', 'rght', 'f1'.. 'f12', 'pgup', 'pgdn', 'ins', and 'del'.

Modified and special keys can also be returned, including:

Ctrl/Cmd+A..Ctrl+Z as 1..26
Ctrl/Cmd+Alt+A..Z as 257..282
Alt+A..Z as 'A'+256..'Z'+256
27 for ESC
13 for Enter
' ' for space

gfx_showmenu("str")

Shows a popup menu at gfx_x,gfx_y. str is a list of fields separated by | characters. Each field represents a menu item.
Fields can start with special characters:

# : grayed out
! : checked
> : this menu item shows a submenu
< : last item in the current submenu

An empty field will appear as a separator in the menu. gfx_showmenu returns 0 if the user selected nothing from the
menu, 1 if the first field is selected, etc.
Example:

gfx_showmenu("first item, followed by separator||!second item, checked|>third item which spawns a submenu|#first
item in submenu, grayed out|<second and last item in submenu|fourth item in top menu")

gfx_setcursor(resource_id)

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]
OSCII-bot code reference

Sets the mouse cursor. resource_id is a value like 32512 (for an arrow cursor).

gfx_lineto(x,y[,aa])

Draws a line from gfx_x,gfx_y to x,y. If aa is 0.5 or greater, then antialiasing is used. Updates gfx_x and gfx_y to x,y.

gfx_line(x,y,x2,y2[,aa])

Draws a line from x,y to x2,y2, and if aa is not specified or 0.5 or greater, it will be antialiased.

gfx_rectto(x,y)

Fills a rectangle from gfx_x,gfx_y to x,y. Updates gfx_x,gfx_y to x,y.

gfx_rect(x,y,w,h[,filled])

Fills a rectangle at x,y, w,h pixels in dimension, filled by default.

gfx_setpixel(r,g,b)

Writes a pixel of r,g,b to gfx_x,gfx_y.

gfx_getpixel(r,g,b)

Gets the value of the pixel at gfx_x,gfx_y into r,g,b.

gfx_drawnumber(n,ndigits)

Draws the number n with ndigits of precision to gfx_x, gfx_y, and updates gfx_x to the right side of the drawing. The
text height is gfx_texth.

gfx_drawchar(char)

Draws the character (can be a numeric ASCII code as well), to gfx_x, gfx_y, and moves gfx_x over by the size of the
character.

gfx_drawstr("str"[,flags,right,bottom])

Draws a string at gfx_x, gfx_y, and updates gfx_x/gfx_y so that subsequent draws will occur in a similar place.

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]
OSCII-bot code reference

If flags, right ,bottom passed in:

flags&1: center horizontally
flags&2: right justify
flags&4: center vertically
flags&8: bottom justify
flags&256: ignore right/bottom, otherwise text is clipped to (gfx_x, gfx_y, right, bottom)

gfx_measurestr("str",&w,&h)

Measures the drawing dimensions of a string with the current font (as set by gfx_setfont).

gfx_measurechar(character,&w,&h)

Measures the drawing dimensions of a character with the current font (as set by gfx_setfont).

gfx_setfont(idx[,"fontface", sz, flags])

Can select a font and optionally configure it. idx=0 for default bitmapped font, no configuration is possible for this font.
idx=1..16 for a configurable font, specify fontface such as "Arial", sz of 8-100, and optionally specify flags, which is a
multibyte character, which can include 'i' for italics, 'u' for underline, or 'b' for bold. These flags may or may not be
supported depending on the font and OS. After calling gfx_setfont(), gfx_texth may be updated to reflect the new
average line height.

gfx_getfont([#str])

Returns current font index. If a string is passed, it will receive the actual font face used by this font, if available.

gfx_printf("format"[, ...])

Formats and draws a string at gfx_x, gfx_y, and updates gfx_x/gfx_y accordingly (the latter only if the formatted string
contains newline). For more information on format strings, see sprintf()

gfx_blurto(x,y)

Blurs the region of the screen between gfx_x,gfx_y and x,y, and updates gfx_x,gfx_y to x,y.

gfx_blit(source,scale,rotation)

If three parameters are specified, copies the entirity of the source bitmap to gfx_x,gfx_y using current opacity and copy
mode (set with gfx_a, gfx_mode). You can specify scale (1.0 is unscaled) and rotation (0.0 is not rotated, angles are in
radians).

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]
OSCII-bot code reference

For the "source" parameter specify -1 to use the main framebuffer as source, or an image index (see gfx_loadimg()).

gfx_blit(source, scale, rotation[, srcx, srcy, srcw, srch, destx, desty, destw, desth, rotxoffs,
rotyoffs])

srcx/srcy/srcw/srch specify the source rectangle (if omitted srcw/srch default to image size), destx/desty/destw/desth
specify dest rectangle (if not specified, these will default to reasonable defaults -- destw/desth default to srcw/srch *
scale).

gfx_blitext(source,coordinatelist,rotation)

Deprecated, use gfx_blit instead.

gfx_getimgdim(image,w,h)

Retreives the dimensions of image (representing a filename: index number) into w and h. Sets these values to 0 if an
image failed loading (or if the filename index is invalid).

gfx_setimgdim(image,w,h)

Resize image referenced by index 0..127, width and height must be 0-2048. The contents of the image will be undefined
after the resize.

gfx_loadimg(image,"filename")

Load image from filename into slot 0..127 specified by image. Returns the image index if success, otherwise -1 if
failure. The image will be resized to the dimensions of the image file.

gfx_gradrect(x,y,w,h, r,g,b,a[, drdx, dgdx, dbdx, dadx, drdy, dgdy, dbdy, dady])

Fills a gradient rectangle with the color and alpha specified. drdx-dadx reflect the adjustment (per-pixel) applied for
each pixel moved to the right, drdy-dady are the adjustment applied for each pixel moved toward the bottom. Normally
drdx=adjustamount/w, drdy=adjustamount/h, etc.

gfx_muladdrect(x,y,w,h,mul_r,mul_g,mul_b[,mul_a,add_r,add_g,add_b,add_a])

Multiplies each pixel by mul_* and adds add_*, and updates in-place. Useful for changing brightness/contrast, or other
effects.

gfx_deltablit(srcimg,srcx,srcy,srcw,srch,destx,desty,destw,desth,dsdx,dtdx,dsdy,dtdy,dsdxdy,dtdxdy)

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]
OSCII-bot code reference

Blits from srcimg(srcx,srcy,srcw,srch) to destination (destx,desty,destw,desth). Source texture coordinates are s/t, dsdx
represents the change in s coordinate for each x pixel, dtdy represents the change in t coordinate for each y pixel, etc.
dsdxdy represents the change in dsdx for each line.

gfx_transformblit(srcimg,destx,desty,destw,desth,div_w,div_h,table)

Blits to destination at (destx,desty), size (destw,desth). div_w and div_h should be 2..64, and table should point to a
table of 2*div_w*div_h values (this table must not cross a 65536 item boundary). Each pair in the table represents a S,T
coordinate in the source image, and the table is treated as a left-right, top-bottom list of texture coordinates, which will
then be rendered to the destination.

gfx_circle(x,y,r[,fill,antialias])

Draws a circle, optionally filling/antialiasing.

gfx_triangle(x1,y1,x2,y2,x3,y3[x4,y4...])

Draws a filled triangle, or any convex polygon.

gfx_roundrect(x,y,w,h,radius[,antialias])

Draws a rectangle with rounded corners.

gfx_arc(x,y,r,ang1,ang2[,antialias])

Draws an arc of the circle centered at x,y, with ang1/ang2 being specified in radians.

gfx_set(r[,g,b,a,mode,dest])

Sets gfx_r/gfx_g/gfx_b/gfx_a/gfx_mode, sets gfx_dest if final parameter specified

gfx_clienttoscreen(x,y)

Converts client coordinates x,y to screen coordinates.

gfx_screentoclient(x,y)

Converts screen coordinates x,y to client coordinates.

https://cockos.com/oscii-bot/oscii-bot-doc.html[24/11/2022 09:50:46]