lobster builtin functions:(file auto generated by compiler, do not modify)

builtin

print(x:string)output any value to the console (with linefeed).
string(x:string) -> stringconvert any value to string
set_print_depth(depth:int)for printing / string conversion: sets max vectors/objects recursion depth (default 10)
set_print_length(len:int)for printing / string conversion: sets max string length (default 100000)
set_print_quoted(quoted:bool)for printing / string conversion: if the top level value is a string, whether to convert it with escape codes and quotes (default false)
set_print_decimals(decimals:int)for printing / string conversion: number of decimals for any floating point output (default -1, meaning all)
set_print_indent(spaces:int)for printing / string conversion: number of spaces to indent with. default is 0: no indent / no multi-line
get_line() -> stringreads a string from the console if possible (followed by enter)
if(cond, then:function, else:function = nil) -> anyevaluates then or else depending on cond, else is optional
while(cond:function, do:function) -> anyevaluates body while cond (converted to a function) holds true, returns last body value
for(iter, do:function)iterates over int/vector/string, body may take [ element [ , index ] ] arguments
append(xs:[any], ys:[any]) -> [any]creates a new vector by appending all elements of 2 input vectors
vector_reserve(typeid:typeid, len:int) -> [any]creates a new empty vector much like [] would, except now ensures it will have space for len push() operations without having to reallocate. pass "typeof return" as typeid.
length(x:int) -> intlength of int (identity function, useful in combination with string/vector version)
length(s:string) -> intlength of string
length(xs:[any]) -> intlength of vector
equal(a, b) -> intstructural equality between any two values (recurses into vectors/objects, unlike == which is only true for vectors/objects if they are the same object)
push(xs:[any], x) -> [any]appends one element to a vector, returns existing vector
pop(xs:[any]) -> anyremoves last element from vector and returns it
top(xs:[any]) -> anyreturns last element from vector
insert(xs:[any], i:int, x) -> [any]inserts a value into a vector at index i, existing elements shift upward, returns original vector
remove(xs:[any], i:int, n:int = 0) -> anyremove element(s) at index i, following elements shift down. pass the number of elements to remove as an optional argument, default 1. returns the first element removed.
remove_obj(xs:[any], obj) -> anyremove all elements equal to obj (==), returns obj.
binary_search(xs:[int], key:int) -> int, intdoes a binary search for key in a sorted vector, returns as first return value how many matches were found, and as second the index in the array where the matches start (so you can read them, overwrite them, or remove them), or if none found, where the key could be inserted such that the vector stays sorted. This overload is for int vectors and keys.
binary_search(xs:[float], key:float) -> int, intfloat version.
binary_search(xs:[string], key:string) -> int, intstring version.
copy(xs) -> anymakes a shallow copy of any object.
slice(xs:[any], start:int, size:int) -> [any]returns a sub-vector of size elements from index start. size can be negative to indicate the rest of the vector.
any(xs:vec_i) -> intreturns wether any elements of the numeric struct are true values
any(xs:[any]) -> intreturns wether any elements of the vector are true values
all(xs:vec_i) -> intreturns wether all elements of the numeric struct are true values
all(xs:[any]) -> intreturns wether all elements of the vector are true values
substring(s:string, start:int, size:int) -> stringreturns a substring of size characters from index start. size can be negative to indicate the rest of the string.
string_to_int(s:string) -> int, intconverts a string to an int. returns 0 if no numeric data could be parsed.second return value is true if all characters of the string were parsed
string_to_float(s:string) -> floatconverts a string to a float. returns 0.0 if no numeric data could be parsed
tokenize(s:string, delimiters:string, whitespace:string) -> [string]splits a string into a vector of strings, by splitting into segments upon each dividing or terminating delimiter. Segments are stripped of leading and trailing whitespace. Example: "; A ; B C; " becomes [ "", "A", "B C" ] with ";" as delimiter and " " as whitespace.
unicode_to_string(us:[int]) -> stringconverts a vector of ints representing unicode values to a UTF-8 string.
string_to_unicode(s:string) -> [int]?converts a UTF-8 string into a vector of unicode values, or nil upon a decoding error
number_to_string(number:int, base:int, minchars:int) -> stringconverts the (unsigned version) of the input integer number to a string given the base (2..36, e.g. 16 for hex) and outputting a minimum of characters (padding with 0).
lowercase(s:string) -> stringconverts a UTF-8 string from any case to lower case, affecting only A-Z
uppercase(s:string) -> stringconverts a UTF-8 string from any case to upper case, affecting only a-z
escape_string(s:string, set:string, prefix:string, postfix:string) -> stringprefixes & postfixes any occurrences or characters in set in string s
concat_string(v:[string], sep:string) -> stringconcatenates all elements of the string vector, separated with sep.
repeat_string(s:string, n:int) -> stringreturns a string consisting of n copies of the input string.
pow(a:float, b:float) -> floata raised to the power of b
pow(a:int, b:int) -> inta raised to the power of b, for integers, using exponentiation by squaring
pow(a:vec_f, b:float) -> vec_fvector elements raised to the power of b
log(a:float) -> floatnatural logaritm of a
sqrt(f:float) -> floatsquare root
ceiling(f:float) -> intthe nearest int >= f
ceiling(v:vec_f) -> vec_ithe nearest ints >= each component of v
floor(f:float) -> intthe nearest int <= f
floor(v:vec_f) -> vec_ithe nearest ints <= each component of v
int(f:float) -> intconverts a float to an int by dropping the fraction
int(v:vec_f) -> vec_iconverts a vector of floats to ints by dropping the fraction
round(f:float) -> intconverts a float to the closest int. same as int(f + 0.5), so does not work well on negative numbers
round(v:vec_f) -> vec_iconverts a vector of floats to the closest ints
fraction(f:float) -> floatreturns the fractional part of a float: short for f - int(f)
fraction(v:vec_f) -> vec_freturns the fractional part of a vector of floats
float(i:int) -> floatconverts an int to float
float(v:vec_i) -> vec_fconverts a vector of ints to floats
sin(angle:float) -> floatthe y coordinate of the normalized vector indicated by angle (in degrees)
cos(angle:float) -> floatthe x coordinate of the normalized vector indicated by angle (in degrees)
tan(angle:float) -> floatthe tangent of an angle (in degrees)
sincos(angle:float) -> xy_fthe normalized vector indicated by angle (in degrees), same as xy { cos(angle), sin(angle) }
asin(y:float) -> floatthe angle (in degrees) indicated by the y coordinate projected to the unit circle
acos(x:float) -> floatthe angle (in degrees) indicated by the x coordinate projected to the unit circle
atan(x:float) -> floatthe angle (in degrees) indicated by the y coordinate of the tangent projected to the unit circle
radians(angle:float) -> floatconverts an angle in degrees to radians
degrees(angle:float) -> floatconverts an angle in radians to degrees
atan2(vec:vec_f) -> floatthe angle (in degrees) corresponding to a normalized 2D vector
radians(angle:float) -> floatconverts an angle in degrees to radians
degrees(angle:float) -> floatconverts an angle in radians to degrees
normalize(vec:vec_f) -> vec_freturns a vector of unit length
dot(a:vec_f, b:vec_f) -> floatthe length of vector a when projected onto b (or vice versa)
magnitude(v:vec_f) -> floatthe geometric length of a vector
manhattan(v:vec_i) -> intthe manhattan distance of a vector
cross(a:xyz_f, b:xyz_f) -> xyz_fa perpendicular vector to the 2D plane defined by a and b (swap a and b for its inverse)
rnd(max:int) -> inta random value [0..max).
rnd(max:vec_i) -> vec_ia random vector within the range of an input vector.
rnd_float() -> floata random float [0..1)
rnd_gaussian() -> floata random float in a gaussian distribution with mean 0 and stddev 1
rnd_seed(seed:int)explicitly set a random seed for reproducable randomness
div(a:int, b:int) -> floatforces two ints to be divided as floats
clamp(x:int, min:int, max:int) -> intforces an integer to be in the range between min and max (inclusive)
clamp(x:float, min:float, max:float) -> floatforces a float to be in the range between min and max (inclusive)
clamp(x:vec_i, min:vec_i, max:vec_i) -> vec_iforces an integer vector to be in the range between min and max (inclusive)
clamp(x:vec_f, min:vec_f, max:vec_f) -> vec_fforces a float vector to be in the range between min and max (inclusive)
in_range(x:int, range:int, bias:int = 0) -> intchecks if an integer is >= bias and < bias + range. Bias defaults to 0.
in_range(x:vec_i, range:vec_i, bias:vec_i = nil) -> intchecks if a 2d/3d integer vector is >= bias and < bias + range. Bias defaults to 0.
in_range(x:vec_f, range:vec_f, bias:vec_f = nil) -> intchecks if a 2d/3d float vector is >= bias and < bias + range. Bias defaults to 0.
abs(x:int) -> intabsolute value of an integer
abs(x:float) -> floatabsolute value of a float
abs(x:vec_i) -> vec_iabsolute value of an int vector
abs(x:vec_f) -> vec_fabsolute value of a float vector
sign(x:int) -> intsign (-1, 0, 1) of an integer
sign(x:float) -> intsign (-1, 0, 1) of a float
sign(x:vec_i) -> vec_isigns of an int vector
sign(x:vec_f) -> vec_isigns of a float vector
min(x:int, y:int) -> intsmallest of 2 integers.
min(x:float, y:float) -> floatsmallest of 2 floats.
min(x:vec_i, y:vec_i) -> vec_ismallest components of 2 int vectors
min(x:vec_f, y:vec_f) -> vec_fsmallest components of 2 float vectors
min(v:vec_i) -> intsmallest component of a int vector.
min(v:vec_f) -> floatsmallest component of a float vector.
min(v:[int]) -> intsmallest component of a int vector, or INT_MAX if length 0.
min(v:[float]) -> floatsmallest component of a float vector, or FLT_MAX if length 0.
max(x:int, y:int) -> intlargest of 2 integers.
max(x:float, y:float) -> floatlargest of 2 floats.
max(x:vec_i, y:vec_i) -> vec_ilargest components of 2 int vectors
max(x:vec_f, y:vec_f) -> vec_flargest components of 2 float vectors
max(v:vec_i) -> intlargest component of a int vector.
max(v:vec_f) -> floatlargest component of a float vector.
max(v:[int]) -> intlargest component of a int vector, or INT_MIN if length 0.
max(v:[float]) -> floatlargest component of a float vector, or FLT_MIN if length 0.
lerp(x:float, y:float, f:float) -> floatlinearly interpolates between x and y with factor f [0..1]
lerp(a:vec_f, b:vec_f, f:float) -> vec_flinearly interpolates between a and b vectors with factor f [0..1]
cardinal_spline(z:vec_f, a:vec_f, b:vec_f, c:vec_f, f:float, tension:float) -> xyz_fcomputes the position between a and b with factor f [0..1], using z (before a) and c (after b) to form a cardinal spline (tension at 0.5 is a good default)
line_intersect(line1a:xy_f, line1b:xy_f, line2a:xy_f, line2b:xy_f) -> int, xy_fcomputes if there is an intersection point between 2 line segments, with the point as second return value
circles_within_range(dist:float, positions:[xy_f], radiuses:[float], prefilter:[int]) -> [[int]]given a vector of 2D positions (an same size vectors of radiuses and pre-filter), returns a vector of vectors of indices of the circles that are within dist of eachothers radius. pre-filter indicates objects that should appear in the inner vectors.
wave_function_collapse(tilemap:[string], size:xy_i) -> [string], intreturns a tilemap of given size modelled after the possible shapes in the input tilemap. Tilemap should consist of chars in the 0..127 range. Second return value the number of failed neighbor matches, this should ideally be 0, but can be non-0 for larger maps. Simply call this function repeatedly until it is 0
resume(coroutine:coroutine, return_value:any = nil) -> coroutine?resumes execution of a coroutine, passing a value back or nil
return_value(coroutine:coroutine) -> anygets the last return value of a coroutine
active(coroutine:coroutine) -> intwether the given coroutine is still active
hash(x:function) -> inthashes a function value into an int
hash(x) -> inthashes any value into an int
program_name() -> stringreturns the name of the main program (e.g. "foo.lobster".
vm_compiled_mode() -> intreturns if the VM is running in compiled mode (Lobster -> C++).
seconds_elapsed() -> floatseconds since program start as a float, unlike gl_time() it is calculated every time it is called
assert(condition) -> anyhalts the program with an assertion failure if passed false. returns its input
trace_bytecode(on:bool, tail:bool)tracing shows each bytecode instruction as it is being executed, not very useful unless you are trying to isolate a compiler bug
set_max_stack_size(max:int)size in megabytes the stack can grow to before an overflow error occurs. defaults to 1
reference_count(val) -> intget the reference count of any value. for compiler debugging, mostly
set_console(on:bool)lets you turn on/off the console window (on Windows)
command_line_arguments() -> [string]
thread_information() -> int, intreturns the number of hardware threads, and the number of cores
is_worker_thread() -> intwether the current thread is a worker thread
start_worker_threads(numthreads:int)launch worker threads
stop_worker_threads()only needs to be called if you want to stop the worker threads before the end of the program, or if you want to call start_worker_threads again. workers_alive will become false inside the workers, which should then exit.
workers_alive() -> intwether workers should continue doing work. returns false after stop_worker_threads() has been called.
thread_write(struct)put this struct in the thread queue
thread_read(type:typeid) -> any?get a struct from the thread queue. pass the typeof struct. blocks if no suchstructs available. returns struct, or nil if stop_worker_threads() was called

compiler

compile_run_code(code:string, args:[string]) -> string, string?compiles and runs lobster source, sandboxed from the current program (in its own VM). the argument is a string of code. returns the return value of the program as a string, with an error string as second return value, or nil if none. using parse_data(), two program can communicate more complex data structures even if they don't have the same version of struct definitions.
compile_run_file(filename:string, args:[string]) -> string, string?same as compile_run_code(), only now you pass a filename.

file

scan_folder(folder:string, divisor:int) -> [string]?, [int]?returns two vectors representing all elements in a folder, the first vector containing all names, the second vector containing sizes (or -1 if a directory). Specify 1 as divisor to get sizes in bytes, 1024 for kb etc. Values > 0x7FFFFFFF will be clamped in 32-bit builds. Returns nil if folder couldn't be scanned.
read_file(file:string, textmode:int = 0) -> string?returns the contents of a file as a string, or nil if the file can't be found. you may use either \ or / as path separators
write_file(file:string, contents:string, textmode:int = 0) -> intcreates a file with the contents of a string, returns false if writing wasn't possible
ensure_size(string:string, size:int, char:int, extra:int = 0) -> stringensures a string is at least size characters. if it is, just returns the existing string, otherwise returns a new string of that size (with optionally extra bytes added), with any new characters set to char. You can specify a negative size to mean relative to the end, i.e. new characters will be added at the start.
write_int64_le(string:string, i:int, val:int) -> string, intwrites a value as little endian to a string at location i. Uses ensure_size to make the string twice as long (with extra 0 bytes) if no space. Returns new string if resized, and the index of the location right after where the value was written. The _back version writes relative to the end (and writes before the index)
write_int32_le(string:string, i:int, val:int) -> string, int(see write_int64_le)
write_int16_le(string:string, i:int, val:int) -> string, int(see write_int64_le)
write_int8_le(string:string, i:int, val:int) -> string, int(see write_int64_le)
write_float64_le(string:string, i:int, val:float) -> string, int(see write_int64_le)
write_float32_le(string:string, i:int, val:float) -> string, int(see write_int64_le)
write_int64_le_back(string:string, i:int, val:int) -> string, int(see write_int64_le)
write_int32_le_back(string:string, i:int, val:int) -> string, int(see write_int64_le)
write_int16_le_back(string:string, i:int, val:int) -> string, int(see write_int64_le)
write_int8_le_back(string:string, i:int, val:int) -> string, int(see write_int64_le)
write_float64_le_back(string:string, i:int, val:float) -> string, int(see write_int64_le)
write_float32_le_back(string:string, i:int, val:float) -> string, int(see write_int64_le)
write_substring(string:string, i:int, substr:string, nullterm:int) -> string, intwrites a substring into another string at i (see also write_int64_le)
write_substring_back(string:string, i:int, substr:string, nullterm:int) -> string, int
compare_substring(string_a:string, i_a:int, string_b:string, i_b:int, len:int) -> intreturns if the two substrings are equal (0), or a < b (-1) or a > b (1).
read_int64_le(string:string, i:int) -> int, intreads a value as little endian from a string at location i. The value must be within bounds of the string. Returns the value, and the index of the location right after where the value was read. The _back version reads relative to the end (and reads before the index)
read_int32_le(string:string, i:int) -> int, int(see read_int64_le)
read_int16_le(string:string, i:int) -> int, int(see read_int64_le)
read_int8_le(string:string, i:int) -> int, int(see read_int64_le)
read_float64_le(string:string, i:int) -> float, int(see read_int64_le)
read_float32_le(string:string, i:int) -> float, int(see read_int64_le)
read_int64_le_back(string:string, i:int) -> int, int(see read_int64_le)
read_int32_le_back(string:string, i:int) -> int, int(see read_int64_le)
read_int16_le_back(string:string, i:int) -> int, int(see read_int64_le)
read_int8_le_back(string:string, i:int) -> int, int(see read_int64_le)
read_float64_le_back(string:string, i:int) -> float, int(see read_int64_le)
read_float32_le_back(string:string, i:int) -> float, int(see read_int64_le)
flatbuffers_field_int64(string:string, tablei:int, vo:int, def:int) -> intreads a flatbuffers field from a string at table location tablei, field vtable offset vo, and default value def. The value must be within bounds of the string. Returns the value (or default if the field was not present)
flatbuffers_field_int32(string:string, tablei:int, vo:int, def:int) -> int(see flatbuffers_field_int64)
flatbuffers_field_int16(string:string, tablei:int, vo:int, def:int) -> int(see flatbuffers_field_int64)
flatbuffers_field_int8(string:string, tablei:int, vo:int, def:int) -> int(see flatbuffers_field_int64)
flatbuffers_field_float64(string:string, tablei:int, vo:int, def:float) -> float(see flatbuffers_field_int64)
flatbuffers_field_float32(string:string, tablei:int, vo:int, def:float) -> float(see flatbuffers_field_int64)
flatbuffers_field_string(string:string, tablei:int, vo:int) -> stringreads a flatbuffer string field, returns "" if not present
flatbuffers_field_vector_len(string:string, tablei:int, vo:int) -> intreads a flatbuffer vector field length, or 0 if not present
flatbuffers_field_vector(string:string, tablei:int, vo:int) -> intreturns a flatbuffer vector field element start, or 0 if not present
flatbuffers_field_table(string:string, tablei:int, vo:int) -> intreturns a flatbuffer table field start, or 0 if not present
flatbuffers_field_struct(string:string, tablei:int, vo:int) -> intreturns a flatbuffer struct field start, or 0 if not present
flatbuffers_indirect(string:string, index:int) -> intreturns a flatbuffer offset at index relative to itself
flatbuffers_string(string:string, index:int) -> stringreturns a flatbuffer string whose offset is at given index
flatbuffers_binary_to_json(schemas:string, binary:string, includedirs:[string]) -> string, string?returns a JSON string generated from the given binary and corresponding schema.if there was an error parsing the schema, the error will be in the second returnvalue, or nil for no error
flatbuffers_json_to_binary(schema:string, json:string, includedirs:[string]) -> string, string?returns a binary flatbuffer generated from the given json and corresponding schema.if there was an error parsing the schema, the error will be in the second returnvalue, or nil for no error

parsedata

parse_data(typeid:typeid, stringdata:string) -> any?, string?parses a string containing a data structure in lobster syntax (what you get if you convert an arbitrary data structure to a string) back into a data structure. supports int/float/string/vector and classes. classes will be forced to be compatible with their current definitions, i.e. too many elements will be truncated, missing elements will be set to 0/nil if possible. useful for simple file formats. returns the value and an error string as second return value (or nil if no error)

graphics

gl_window(title:string, xs:int, ys:int, fullscreen:int = 0, novsync:int = 0, samples:int = 0) -> string?opens a window for OpenGL rendering. returns error string if any problems, nil otherwise.
gl_require_version(major:int, minor:int)Call this before gl_window to request a certain version of OpenGL context. Currently only works on win/nix, minimum is 3.2.
gl_load_materials(materialdefs:string, inline:int = 0) -> string?loads an additional materials file (data/shaders/default.materials is already loaded by default by gl_window()). if inline is true, materialdefs is not a filename, but the actual materials. returns error string if any problems, nil otherwise.
gl_frame() -> intadvances rendering by one frame, swaps buffers, and collects new input events. returns true if the closebutton on the window was pressed
gl_log_frame(delta:float)call this function instead of gl_frame() to simulate a frame based program from non-graphical code. does not require gl_window(). manages frame log state much like gl_frame(). allows gl_time and gl_delta_time to work. pass a desired delta time, e.g. 1.0/60.0
gl_shutdown()shuts down the OpenGL window. you only need to call this function if you wish to close it before the end of the program
gl_window_title(title:string) -> stringchanges the window title.
gl_window_min_max(dir:int)>0 to maximize, <0 to minimize or 0 to restore.
gl_visible() -> intchecks if the window is currently visible (not minimized, or on mobile devices, in the foreground). If false, you should not render anything, nor run the frame's code.
gl_cursor(on:bool) -> intdefault the cursor is visible, turn off for implementing FPS like control schemes. return wether it's on.
gl_grab(on:bool) -> intgrabs the mouse when the window is active. return wether it's on.
gl_button(name:string) -> intreturns the state of a key/mousebutton/finger. isdown: >= 1, wentdown: == 1, wentup: == 0, isup: <= 0. (pass a string like mouse1/mouse2/mouse3/escape/space/up/down/a/b/f1 etc. mouse11 and on are additional fingers)
gl_touchscreen() -> intwether a you're getting input from a touch screen (as opposed to mouse & keyboard)
gl_dpi(screen:int) -> intthe DPI of the screen. always returns a value for screen 0, any other screens may return 0 to indicate the screen doesn't exist
gl_window_size() -> xy_ia vector representing the size (in pixels) of the window, changes when the user resizes
gl_mouse_pos(i:int) -> xy_ithe current mouse/finger position in pixels, pass a value other than 0 to read additional fingers (for touch screens only if the corresponding gl_isdown is true)
gl_mouse_delta(i:int) -> xy_inumber of pixels the mouse/finger has moved since the last frame. use this instead of substracting positions to correctly deal with lifted fingers and FPS mode (gl_cursor(0))
gl_local_mouse_pos(i:int) -> xy_fthe current mouse/finger position local to the current transform (gl_translate etc) (for touch screens only if the corresponding gl_isdown is true)
gl_last_pos(name:string, down:int) -> xy_iposition (in pixels) key/mousebutton/finger last went down (true) or up (false)
gl_local_last_pos(name:string, down:int) -> xy_fposition (local to the current transform) key/mousebutton/finger last went down (true) or up (false)
gl_mousewheel_delta() -> intamount the mousewheel scrolled this frame, in number of notches
gl_joy_axis(i:int) -> floatthe current joystick orientation for axis i, as -1 to 1 value
gl_delta_time() -> floatseconds since the last frame, updated only once per frame
gl_time() -> floatseconds since the start of the OpenGL subsystem, updated only once per frame (use seconds_elapsed() for continuous timing)
gl_last_time(name:string, down:int) -> floattime key/mousebutton/finger last went down (true) or up (false)
gl_clear(col:xyzw_f)clears the framebuffer (and depth buffer) to the given color
gl_color(col:xyzw_f, body:function = nil)sets the current color. when a body is given, restores the previous color afterwards
gl_polygon(vertlist:[vec_f])renders a polygon using the list of points given. warning: gl_polygon creates a new mesh every time, gl_new_poly/gl_render_mesh is faster.
gl_circle(radius:float, segments:int)renders a circle
gl_open_circle(radius:float, segments:int, thickness:float)renders a circle that is open on the inside. thickness is the fraction of the radius that is filled, try e.g. 0.2
gl_unit_cube(insideout:int = 0)renders a unit cube (0,0,0) - (1,1,1). optionally pass true to have it rendered inside out
gl_rotate_x(vector:xy_f, body:function = nil)rotates the yz plane around the x axis, using a 2D vector normalized vector as angle. when a body is given, restores the previous transform afterwards
gl_rotate_y(angle:xy_f, body:function = nil)rotates the xz plane around the y axis, using a 2D vector normalized vector as angle. when a body is given, restores the previous transform afterwards
gl_rotate_z(angle:xy_f, body:function = nil)rotates the xy plane around the z axis (used in 2D), using a 2D vector normalized vector as angle. when a body is given, restores the previous transform afterwards
gl_translate(vec:vec_f, body:function = nil)translates the current coordinate system along a vector. when a body is given, restores the previous transform afterwards
gl_scale(factor:float, body:function = nil)scales the current coordinate system using a numerical factor. when a body is given, restores the previous transform afterwards
gl_scale(factor:vec_f, body:function = nil)scales the current coordinate system using a vector. when a body is given, restores the previous transform afterwards
gl_origin() -> xy_freturns a vector representing the current transform origin in pixels. only makes sense in 2D mode (no gl_perspective called).
gl_scaling() -> xy_freturns a vector representing the current transform scale in pixels. only makes sense in 2D mode (no gl_perspective called).
gl_model_view_projection() -> [float]returns a vector representing the current model view projection matrix (16 elements)
gl_point_scale(factor:float)sets the current scaling factor for point sprites. this can be what the current gl_scale is, or different, depending on the desired visuals. the ideal size may also be FOV dependent.
gl_line_mode(on:int, body:function)set line mode (true == on). when a body is given, restores the previous mode afterwards
gl_hit(vec:vec_f, i:int) -> intwether the mouse/finger is inside of the rectangle specified in terms of the current transform (for touch screens only if the corresponding gl_isdown is true). Only true if the last rectangle for which gl_hit was true last frame is of the same size as this one (allows you to safely test in most cases of overlapping rendering)
gl_rect(size:xy_f, centered:int = 0)renders a rectangle (0,0)..(1,1) (or (-1,-1)..(1,1) when centered), scaled by the given size.
gl_rect_tc_col(size:xy_f, tc:xy_f, tcsize:xy_f, cols:[xyzw_f])Like gl_rect renders a sized quad, but allows you to specify texture coordinates and optionally colors (empty list for all white). Slow.
gl_unit_square(centered:int = 0)renders a square (0,0)..(1,1) (or (-1,-1)..(1,1) when centered)
gl_line(start:vec_f, end:vec_f, thickness:float)renders a line with the given thickness
gl_perspective(fovy:float, znear:float, zfar:float)changes from 2D mode (default) to 3D right handed perspective mode with vertical fov (try 60), far plane (furthest you want to be able to render, try 1000) and near plane (try 1)
gl_ortho(rh:int = 0, depth:int = 0)changes back to 2D mode rendering with a coordinate system from (0,0) top-left to the screen size in pixels bottom right. this is the default at the start of a frame, use this call to get back to that after gl_perspective. Pass true to rh have (0,0) bottom-left instead. Pass true to depth to have depth testing/writing on.
gl_ortho3d(center:vec_f, extends:vec_f)sets a custom ortho projection as 3D projection.
gl_new_poly(positions:[vec_f]) -> resourcecreates a mesh out of a loop of points, much like gl_polygon. gl_line_mode determines how this gets drawn (fan or loop). returns mesh id
gl_new_mesh(format:string, positions:[xyz_f], colors:[xyzw_f], normals:[xyz_f], texcoords1:[xy_f], texcoords2:[xy_f], indices:[int] = nil) -> resourcecreates a new vertex buffer and returns an integer id (1..) for it. format must be made up of characters P (position), C (color), T (texcoord), N (normal). indices may be []. positions is obligatory. you may specify [] for any of the other attributes if not required by format, or to get defaults for colors (white) / texcoords (position x & y) / normals (generated from adjacent triangles).
gl_new_mesh_iqm(filename:string) -> resource?load a .iqm file into a mesh, returns mesh or nil on failure to load.
gl_mesh_parts(m:resource) -> [string]returns an array of names of all parts of mesh m (names may be empty)
gl_mesh_size(m:resource) -> intreturns the number of verts in this mesh
gl_animate_mesh(m:resource, frame:float)set the frame for animated mesh m
gl_render_mesh(m:resource)renders the specified mesh
gl_save_mesh(m:resource, name:string) -> intsaves the specified mesh to a file in the PLY format. useful if the mesh was generated procedurally. returns false if the file could not be written
gl_set_shader(shader:string)changes the current shader. shaders must reside in the shaders folder, builtin ones are: color / textured / phong
gl_set_uniform(name:string, value:vec_f, ignore_errors:int = 0) -> intset a uniform on the current shader. size of float vector must match size of uniform in the shader.
gl_set_uniform(name:string, value:float, ignore_errors:int = 0) -> intset a uniform on the current shader. uniform in the shader must be a single float.
gl_set_uniform_array(name:string, value:[xyzw_f]) -> intset a uniform on the current shader. uniform in the shader must be an array of vec4. returns false on error.
gl_set_uniform_matrix(name:string, value:[float]) -> intset a uniform on the current shader. pass a vector of 4/9/12/16 floats to set a mat2/mat3/mat3x4/mat4 respectively. returns false on error.
gl_uniform_buffer_object(name:string, value:[xyzw_f], ssbo:int) -> intcreates a uniform buffer object, and attaches it to the current shader at the given uniform block name. uniforms in the shader must be all vec4s, or an array of them. ssbo indicates if you want a shader storage block instead. returns buffer id or 0 on error.
gl_uniform_buffer_object(name:string, value:string, ssbo:int) -> intcreates a uniform buffer object, and attaches it to the current shader at the given uniform block name. uniforms in the shader can be any type, as long as it matches the data layout in the string buffer. ssbo indicates if you want a shader storage block instead. returns buffer id or 0 on error.
gl_delete_buffer_object(id:int)deletes a buffer objects, e.g. one allocated by gl_uniform_buffer_object().
gl_bind_mesh_to_compute(mesh:resource, binding:int)Bind the vertex data of a mesh to a SSBO binding of a compute shader. Pass a nil mesh to unbind.
gl_dispatch_compute(groups:xyz_i)dispatches the currently set compute shader in groups of sizes of the specified x/y/z values.
gl_dump_shader(filename:string, stripnonascii:bool) -> intDumps the compiled (binary) version of the current shader to a file. Contents are driver dependent. On Nvidia hardware it contains the assembly version of the shader as text, pass true for stripnonascii if you're only interested in that part.
gl_blend(on:int, body:function = nil)changes the blending mode (use blending constants from color.lobster). when a body is given, restores the previous mode afterwards
gl_load_texture(name:string, textureformat:int = 0) -> resource?returns texture if succesfully loaded from file name, otherwise nil. see color.lobster for texture format. Uses stb_image internally (see http://nothings.org/), loads JPEG Baseline, subsets of PNG, TGA, BMP, PSD, GIF, HDR, PIC.
gl_set_primitive_texture(i:int, tex:resource, textureformat:int = 0)sets texture unit i to texture (for use with rect/circle/polygon/line)
gl_set_mesh_texture(mesh:resource, part:int, i:int, texture:resource)sets texture unit i to texture for a mesh and part (0 if not a multi-part mesh)
gl_set_image_texture(i:int, tex:resource, textureformat:int)sets image unit i to texture (for use with compute). texture format must be the same as what you specified in gl_load_texture / gl_create_texture, with optionally writeonly/readwrite flags.
gl_create_texture(matrix:[[xyzw_f]], textureformat:int = 0) -> resourcecreates a texture from a 2d array of color vectors. see texture.lobster for texture format
gl_create_blank_texture(size:xy_i, color:xyzw_f, textureformat:int = 0) -> resourcecreates a blank texture (for use as frame buffer or with compute shaders). see texture.lobster for texture format
gl_texture_size(tex:resource) -> xy_ireturns the size of a texture
gl_read_texture(tex:resource) -> string?read back RGBA texture data into a string or nil on failure
gl_switch_to_framebuffer(tex:resource = nil, hasdepth:int = 0, textureformat:int = 0, resolvetex:resource = nil, depthtex:resource = nil) -> intswitches to a new framebuffer, that renders into the given texture. also allocates a depth buffer for it if depth is true. pass the textureformat that was used for this texture. pass a resolve texture if the base texture is multisample. pass your own depth texture if desired. pass a nil texture to switch back to the original framebuffer. performance note: do not recreate texture passed in unless necessary.
gl_light(pos:xyz_f, params:xy_f)sets up a light at the given position for this frame. make sure to call this after your camera transforms but before any object transforms (i.e. defined in "worldspace"). params contains specular exponent in x (try 32/64/128 for different material looks) and the specular scale in y (try 1 for full intensity)
gl_render_tiles(positions:[xy_f], tilecoords:[xy_i], mapsize:xy_i)Renders a list of tiles from a tilemap. Each tile rendered is 1x1 in size. Positions may be anywhere. Tile coordinates are inside the texture map, map size is the amount of tiles in the texture. Tiles may overlap, they are drawn in order. Before calling this, make sure to have the texture set and a textured shader
gl_debug_grid(num:xyz_i, dist:xyz_f, thickness:float)renders a grid in space for debugging purposes. num is the number of lines in all 3 directions, and dist their spacing. thickness of the lines in the same units
gl_screenshot(filename:string) -> intsaves a screenshot in .png format, returns true if succesful

font

gl_set_font_name(filename:string) -> intsets a freetype/OTF/TTF font as current (and loads it from disk the first time). returns true if success.
gl_set_font_size(size:int, outlinesize:float = 0) -> intsets the font for rendering into this fontsize (in pixels). caches into a texture first time this size is used, flushes from cache if this size is not used an entire frame. font rendering will look best if using 1:1 pixels (careful with gl_scale/gl_translate). an optional outlinesize will give the font a black outline. returns true if success
gl_set_max_font_size(size:int)sets the max font size to render to bitmaps. any sizes specified over that by setfontsize will still work but cause scaled rendering. default 128
gl_get_font_size() -> intthe current font size
gl_get_outline_size() -> floatthe current font size
gl_text(text:string) -> stringrenders a text with the current font (at the current coordinate origin)
gl_text_size(text:string) -> xy_ithe x/y size in pixels the given text would need
gl_get_glyph_name(i:int) -> stringthe name of a glyph index, or empty string if the font doesn't have names
gl_get_char_code(name:string) -> intthe char code of a glyph by specifying its name, or 0 if it can not be found (or if the font doesn't have names)

sound

play_wav(filename:string, volume:int = 0) -> intplays a sound defined by a wav file (RAW or MS-ADPCM, any bitrate other than 22050hz 16bit will automatically be converted on first load). volume in range 1..128, or omit for max. returns false on error
play_sfxr(filename:string, volume:int = 0) -> intplays a synth sound defined by a .sfs file (use http://www.drpetter.se/project_sfxr.html to generate these). volume in range 1..128, or omit for max. returns false on error

physics

ph_initialize(gravityvector:xy_f)initializes or resets the physical world, gravity typically [0, -10].
ph_create_box(position:xy_f, size:xy_f, offset:xy_f = nil, rotation:float = 0, attachto:resource = nil) -> resourcecreates a physical box shape in the world at position, with size the half-extends around the center, offset from the center if needed, at a particular rotation (in degrees). attachto is a previous physical object to attach this one to, to become a combined physical body.
ph_create_circle(position:xy_f, radius:float, offset:xy_f = nil, attachto:resource = nil) -> resourcecreates a physical circle shape in the world at position, with the given radius, offset from the center if needed. attachto is a previous physical object to attach this one to, to become a combined physical body.
ph_create_polygon(position:xy_f, vertices:[xy_f], attachto:resource = nil) -> resourcecreates a polygon circle shape in the world at position, with the given list of vertices. attachto is a previous physical object to attach this one to, to become a combined physical body.
ph_dynamic(shape:resource, on:bool)makes a shape dynamic (on = true) or not.
ph_set_color(id:resource, color:xyzw_f)sets a shape (or nil for particles) to be rendered with a particular color.
ph_set_shader(id:resource, shadername:string)sets a shape (or nil for particles) to be rendered with a particular shader.
ph_set_texture(id:resource, tex:resource, texunit:int = 0)sets a shape (or nil for particles) to be rendered with a particular texture (assigned to a texture unit, default 0).
ph_get_position(id:resource) -> xy_fgets a shape's position.
ph_create_particle(position:xy_f, velocity:xy_f, color:xyzw_f, flags:int = 0) -> intcreates an individual particle. For flags, see include/physics.lobster
ph_create_particle_circle(position:xy_f, radius:float, color:xyzw_f, flags:int = 0)creates a circle filled with particles. For flags, see include/physics.lobster
ph_initialize_particles(radius:float)initializes the particle system with a given particle radius.
ph_step(seconds:float, viter:int, piter:int)simulates the physical world for the given period (try: gl_delta_time()). You can specify the amount of velocity/position iterations per step, more means more accurate but also more expensive computationally (try 8 and 3).
ph_particle_contacts(id:resource) -> [int]gets the particle indices that are currently contacting a giving physics object. Call after step(). Indices may be invalid after next step().
ph_raycast(p1:xy_f, p2:xy_f, n:int) -> [int]returns a vector of the first n particle ids that intersect a ray from p1 to p2, not including particles that overlap p1.
ph_delete_particle(i:int)deletes given particle. Deleting particles causes indices to be invalidated at next step().
ph_getparticle_position(i:int) -> xy_fgets a particle's position.
ph_render()renders all rigid body objects.
ph_render_particles(scale:float)render all particles, with the given scale.

noise

simplex(pos:vec_f, octaves:int, scale:float, persistence:float) -> floatreturns a simplex noise value [-1..1] given a 2D/3D or 4D location, the number of octaves (try 8), a scale (try 1), and persistence from one octave to the next (try 0.5)

meshgen

mg_sphere(radius:float)a sphere
mg_cube(extents:xyz_f)a cube (extents are size from center)
mg_cylinder(radius:float, height:float)a unit cylinder (height is from center)
mg_tapered_cylinder(bot:float, top:float, height:float)a cyclinder where you specify the top and bottom radius (height is from center)
mg_superquadric(exponents:xyz_f, scale:xyz_f)a super quadric. specify an exponent of 2 for spherical, higher values for rounded squares
mg_superquadric_non_uniform(posexponents:xyz_f, negexponents:xyz_f, posscale:xyz_f, negscale:xyz_f)a superquadric that allows you to specify exponents and sizes in all 6 directions independently for maximum modelling possibilities
mg_supertoroid(R:float, exponents:xyz_f)a super toroid. R is the distance from the origin to the center of the ring.
mg_landscape(zscale:float, xyscale:float)a simplex landscape of unit size
mg_set_polygon_reduction(polyreductionpasses:int, epsilon:float, maxtricornerdot:float)controls the polygon reduction algorithm. set polyreductionpasses to 0 for off, 100 for max compression, or low values for generation speed or to keep the mesh uniform. epsilon determines how flat adjacent triangles must be to be reduced, use 0.98 as a good tradeoff, lower to get more compression. maxtricornerdot avoid very thin triangles, use 0.95 as a good tradeoff, up to 0.99 to get more compression
mg_set_color_noise(noiseintensity:float, noisestretch:float)applies simplex noise to the colors of the model. try 0.3 for intensity. stretch scales the pattern over the model
mg_set_vertex_randomize(factor:float)randomizes all verts produced to give a more organic look and to hide the inherent messy polygons produced by the algorithm. try 0.15. note that any setting other than 0 will likely counteract the polygon reduction algorithm
mg_set_point_mode(on:bool)generates a point mesh instead of polygons
mg_polygonize(subdiv:int) -> resourcereturns a generated mesh from past mg_ commands. subdiv determines detail and number of polygons (relative to the largest dimension of the model), try 30.. 300 depending on the subject. values much higher than that will likely make you run out of memory (or take very long).
mg_translate(vec:xyz_f, body:function = nil)translates the current coordinate system along a vector. when a body is given, restores the previous transform afterwards
mg_scale(f:float, body:function = nil)scales the current coordinate system by the given factor. when a body is given, restores the previous transform afterwards
mg_scale_vec(vec:xyz_f, body:function = nil)non-unimformly scales the current coordinate system using individual factors per axis. when a body is given, restores the previous transform afterwards
mg_rotate(axis:xyz_f, angle:float, body:function = nil)rotates using axis/angle. when a body is given, restores the previous transform afterwards
mg_color(color:xyzw_f, body:function = nil)sets the color, where an alpha of 1 means to add shapes to the scene (union), and 0 substracts them (carves). when a body is given, restores the previous color afterwards.
mg_smooth(smooth:float, body:function = nil)sets the smoothness in terms of the range of distance from the shape smoothing happens. when a body is given, restores the previous value afterwards.

cubegen

cg_init(size:xyz_i) -> resourceinitializes a new, empty 3D cube block. 1 byte per cell, careful with big sizes :) returns the block
cg_size(block:resource) -> xyz_ireturns the current block size
cg_set(block:resource, pos:xyz_i, size:xyz_i, paletteindex:int)sets a range of cubes to palette index. index 0 is considered empty space.Coordinates automatically clipped to the size of the grid
cg_copy(block:resource, pos:xyz_i, size:xyz_i, dest:xyz_i, flip:xyz_i)copy a range of cubes from pos to dest. flip can be 1 (regular copy), or -1 (mirror)for each component, indicating the step from dest. Coordinates automatically clipped to the size of the grid
cg_color_to_palette(block:resource, color:xyzw_f) -> intconverts a color to a palette index. alpha < 0.5 is considered empty space. note: this is fast for the default palette, slow otherwise.
cg_palette_to_color(block:resource, paletteindex:int) -> xyzw_fconverts a palette index to a color. empty space (index 0) will have 0 alpha
cg_copy_palette(fromworld:resource, toworld:resource)
cg_resample_half(fromworld:resource)
cg_create_mesh(block:resource) -> resourceconverts block to a mesh
cg_create_3d_texture(block:resource, textureformat:int, monochrome:int = 0) -> resourcereturns the new texture, for format, pass flags you want in addition to 3d|single_channel|has_mips
cg_load_vox(name:string) -> resource?loads a file in the .vox format (MagicaVoxel). returns block or nil if file failed to load
cg_save_vox(block:resource, name:string) -> intsaves a file in the .vox format (MagicaVoxel). returns false if file failed to save. this format can only save blocks < 256^3, will fail if bigger
cg_get_buf(block:resource) -> stringreturns the data as a string of all palette indices, in z-major order
cg_average_surface_color(world:resource) -> xyzw_f
cg_rotate(block:resource, n:int) -> resourcereturns a new block rotated by n 90 degree steps from the input

octree

oc_world_bits(octree:resource) -> int
oc_buf(octree:resource) -> string
oc_load(name:string) -> resource?
oc_save(octree:resource, name:string) -> int
oc_new(bits:int) -> resource
oc_set(octree:resource, pos:xyz_i, val:int)
oc_get(octree:resource, pos:xyz_i) -> int

vr

vr_init() -> intinitializes VR mode. returns true if a hmd was found and initialized
vr_start_eye(isright:int, znear:float, zfar:float)starts rendering for an eye. call for each eye, followed by drawing the world as normal. replaces gl_perspective
vr_start()starts VR by updating hmd & controller poses
vr_finish()finishes vr rendering by compositing (and distorting) both eye renders to the screen
vr_set_eye_texture(unit:int, isright:int)sets the texture for an eye (like gl_set_primitive_texture). call after vr_finish. can be used to render the non-VR display
vr_num_motion_controllers() -> intreturns the number of motion controllers in the system
vr_motioncontrollerstracking(n:int) -> intreturns if motion controller n is tracking
vr_motion_controller(n:int, body:function = nil)sets up the transform ready to render controller n. when a body is given, restores the previous transform afterwards. if there is no controller n (or it is currently not tracking) the identity transform is used
vr_create_motion_controller_mesh(n:int) -> resource?returns the mesh for motion controller n, or nil if not available
vr_motion_controller_button(n:int, button:string) -> intreturns the button state for motion controller n. isdown: >= 1, wentdown: == 1, wentup: == 0, isup: <= 0. buttons are: system, menu, grip, trigger, touchpad
vr_motion_controller_vec(n:int, i:int) -> xyz_freturns one of the vectors for motion controller n. 0 = left, 1 = up, 2 = fwd, 4 = pos. These are in Y up space.
vr_hmd_vec(i:int) -> xyz_freturns one of the vectors for hmd pose. 0 = left, 1 = up, 2 = fwd, 4 = pos. These are in Y up space.

steam

steam_init(appid:int, allowscreenshots:bool) -> intinitializes SteamWorks. returns 1 if succesful, 0 on failure. Specify a non-0 appid if you want to restart from steam if this wasn't started from steam (the return value in this case will be -1 to indicate you should terminate this instance). If you don't specify an appid here or in steam_appid.txt, init will likely fail. The other functions can still be called even if steam isn't active. allowscreenshots automatically uploads screenshots to steam (triggered by steam).
steam_overlay() -> intreturns true if the steam overlay is currently on (you may want to auto-pause if so)
steam_username() -> stringreturns the name of the steam user, or empty string if not available.
steam_unlock_achievement(achievementname:string) -> intUnlocks an achievement and shows the achievement overlay if not already achieved before. Will also Q-up saving achievement to Steam. Returns true if succesful.
steam_write_file(file:string, contents:string) -> intwrites a file with the contents of a string to the steam cloud, or local storage if that fails, returns false if writing wasn't possible at all
steam_read_file(file:string) -> string?returns the contents of a file as a string from the steam cloud if available, or otherwise from local storage, or nil if the file can't be found at all.

imgui

im_init(dark_style:bool = 0)
im_add_font(font_path:string, size:float) -> int
im_frame(body:function)
im_window_demo() -> int
im_window(title:string, flags:int, body:function)
im_button(label:string, body:function)
im_same_line()
im_separator()
im_text(label:string)
im_tooltip(label:string)
im_checkbox(label:string, bool:int) -> int
im_input_text(label:string, str:string) -> string
im_radio(labels:[string], active:int, horiz:int) -> int
im_combo(label:string, labels:[string], active:int) -> int
im_listbox(label:string, labels:[string], active:int, height:int) -> int
im_sliderint(label:string, i:int, min:int, max:int) -> int
im_sliderfloat(label:string, f:float, min:float, max:float) -> float
im_coloredit(label:string, color:vec_f) -> any
im_treenode(label:string, body:function)
im_group(label:string, body:function)an invisble group around some widgets, useful to ensure these widgets are unique (if they have the same label as widgets in another group that has a different group label)
im_edit_anything(value, label:string = nil) -> anycreates a UI for any lobster reference value, and returns the edited version
im_graph(label:string, values:[float], ishistogram:int)
im_show_vars()shows an automatic editing UI for each global variable in your program
im_show_engine_stats()