Jump to:

- Core Functionality
- Game Engine
- Music Language
- Tutorial

# BooBoo Core Functionality

The following describe the core functions of BooBoo. All of this can be used from the CLI version as well as the game engine.

Many or most operators/functions support multiple parameters, e.g. (+ 1 2 3 4 5) is 15.

Sections:

- Core
- Flow Control
- Strings
- Math
- Vectors
- Maps
- Files
- Configuration Functions
- JSON Functions
- CPA Functions
- Audio Functions
- Other
- Constants

## Core Functions

### var

    	declare a variable or variables
    	e.g. var x y z

### const

    	Declare one or more constants. You must set a value for every constant.
    	e.g. const var1 val1 var2 val2

### reset

    	load a different BooBoo script
    	This is seamless and more or less instant. If you start drawing
    	the same thing in the next script, the player may not know the
    	script changed. It's useful for different game modes, menus,
    	high scores etc... state information can be passed between scripts
    	using the configuration API.
    	e.g. reset "next_slide.boo"

### exit

    	Exit the app with a return code to the environment
    	e.g. exit 0

### return

    	Return a value from a function
    	e.g. return 1
    	or just return if the function doesn't return a value

### include

    	Include a BooBoo file at this point in the code
    	e.g. include "my_functions.inc"

### :

    	Define a label
    	e.g. :jump_here

### ;

    	Define a comment
    	e.g. = x 1 ; assign 1 to x

### /* */

    	A multiline comment
    	e.g. call foo bar /* foo bar */ baz

### " "

    	a string
    	e.g. = name "Pelvis Johnson"

### function

    	define a function
    	References can be defined by prefixing a parameter name by a tilde (~)
    	e.g. function foo param1 param2 ~param3 { ... }

### (typeof)

    	Returns a string respresentation of the type of the second parameter
    	e.g. = type_string (typeof my_var)

### ()

    	an expression
    	e.g. (+ x (* y (* z w 2))) in C would be x+(y*(z*w*2))
    	Supported operators are: + - * / % && || > < >= <= == != ! | ^ & << >>
    	The boolean operators return 1 or 0
    	Your own functions can be supplied as operators

### []

    	Vector/map indexing operator
    	e.g. = x [v [m "key"]] in C++ would be x = v[m["key"]]
    	Can be used anywhere a variable is expected.
    	You can use multiple indexes
    	e.g. [v 3 2 1 0] is like v[3][2][1][0] in C.

### #

    	Start a hexadecimal number
    	e.g. #FF is equivalent to 255

### ' '

    	A character. The character between quotes is turned to a
    	number between 0 and 255.
    	e.g. print "%(c)\n" 'a'

### ~

    	A reference. Function parameters preceded by a ~ can be modified
    	by a function
    	e.g. function foo a b ~c d ~e { ... } ; c and e can be modified

### @

    	The address operator
    	e.g. = my_pointer (@ my_var)
    	or
    	call foo (@ bar) ; where foo is expecting a pointer

### `

    	Dereference operator. This is used to get/set the value pointed
    	to by a pointer
    	e.g. = p (@ some_num)
    	e.g. = `p 10 ; some_num is now 10

### (toptr)

    	You can do some basic "reflection" using toptr to get a pointer
    	to the variable with the name in a string.
    	e.g. var foo
    	e.g. = number 10
    	e.g. var bar
    	e.g. = bar "foo"
    	e.g. = `(toptr bar) 1000 ; foo is now 1000
    	You can use this to script BooBoo with function names/etc in a text file.
    	Returns NULL if the variable isn't found

### =

    	assign
    	e.g. = x 1

### (number)

    	Cast to a number
    	e.g. = n (number str)

### (string)

    	Cast to a string
    	e.g. = str (string num)

### (vector)

    	Cast to a vector
    	e.g. var foo
    	e.g. = foo (vector foo)

### (map)

    	Cast to a map
    	e.g. var foo
    	e.g. = foo (map foo)

### (function)

    	Cast to a function
    	e.g. var foo
    	e.g. = foo (function foo)

### (label)

    	Cast to a label
    	e.g. var foo
    	e.g. = foo (label foo)

### (pointer)

    	Cast to a pointer
    	e.g. var foo
    	e.g. = foo (pointer foo)

## Flow Control

### goto

    	jump to a label
    	e.g. goto next_loop

### ?

    	Comparison
    	e.g. ? x 1
    	You can also evaluate an expression
    	? 1 (&& (> a b) (< x y)) je true jne false

### je

    	Jumps like this one are based on the last comparison. If it was equal,
    	this will jump, if not, it won't
    	e.g. je process_x_equals_1

### jne

    	Jump if not equal
    	e.g. jne process_x_not_1

### jl

    	Jump if less
    	e.g. jl my_label

### jle

    	Jump if less or equal
    	e.g. jle my_label

### jg

    	Jump if greater
    	e.g. jg my_label

### jge

    	Jump if greater or equal
    	e.g. jge my_label

### call

    	Call a function that doesn't return anything
    	e.g. call my_func param1 param2 param2

### call_result

    	Call a function that returns a value
    	e.g. call_result result my_func param1 param2

### if

    	compare and jump
    	e.g. if (expr1) the_if (expr2) elseif1 (expr3) elseif2 the_else
    		; expr1 true code
    	:the_if
    		; expr2 true code
    	:elseif1
    		; expr3 true code
    	:elseif2
    		; else code
    	:the_else

    	the_if elseif1 elseif2 and the_else are labels that are the bottom of
    	their code blocks. The else block is optional. Labels need to be in
    	order of appearance in the if statement or behaviour is undefined.

### for

    	A for loop
    	e.g. for i start (expression) increment end_label
    		; your loop code here
    	:end_label
    	i is initialised to "start" then gets incremented
    	by increment each loop until expression returns
    	FALSE.
    	break and continue work in loops

### while

    	A while loop
    	break and continue work in loops
    	e.g. while (< i 10) loop /* code here */ :loop

### do_while

    	A do/while loop
    	The expression is first evaluated after the body is run, despite
    	it being at the top...
    	break and continue work in loops
    	e.g. do_while (< i 10) loop /* code here */ :loop

## String Functions

### (string_format)

    	format strings with replacements
    	e.g. = dest (string_format "I'm % years old" age)
    	printf-equivalent formating options are available with %(...) for
    	example %(3.16g)

### (string_char_at)

    	Get the value of character at index in a string
    	This function is UTF8 compliant
    	e.g. = dest (string_char_at str index)

### string_set_char_at

    	Set character at position in string
    	This is UTF8 compliant
    	e.g. string_set_char_at s pos value

### (string_length)

    	Get the length of a string
    	This function is UTF8 compliant
    	e.g. = dest (string_length str)

### (string_from_number)

    	Turns the ascii value into a one character length string
    	This function is UTF8 compliant
    	e.g. = str (string_from_number 97) ; creates "a"

### (string_substr)

    	Create a substring of a string
    	e.g. = s (string_substr s start end)
    	End is optional, if not specified it will cut from start till the
    	end of the string.
    	This is UTF8 compliant

### (string_trim)

    	Trim leading and trailing whitespace from a string
    	The trim functions are UTF8 compliant
    	e.g. = s (string_trim s)

### (string_ltrim)

    	Trim leading whitespace from a string
    	The trim functions are UTF8 compliant
    	e.g. = s (string_trim s)

### (string_rtrim)

    	Trim trailing whitespace from a string
    	The trim functions are UTF8 compliant
    	e.g. = s (string_trim s)

### (string_uppercase)

    	Make a string uppercase
    	e.g. = s (string_uppercase s)

### (string_lowercase)

    	Make a string lowercase
    	e.g. = s (string_lowercase s)

### (string_replace)

    	regex replacement
    	Default is case sensitive
    	e.g. = str (string_replace str regex replacement ^ ignore_case)

### (string_match)

    	Extract sub-strings from a string
    	Default is case sensitive
    	e.g. = out_vector (string_match str regex ^ ignorecase)

### (string_matches)

    	Check if a string matches a regex
    	Default is case sensitive
    	e.g. = yesno (string_matches str regex ^ ignorecase)

## Math Functions

### (fmod)

    	floating point modulus
    	e.g. = x (fmod x 1.5)

### (sin)

    	trigonometry functions
    	e.g. = n (sin n)

### (cos)

    	trigonometry functions
    	e.g. = n (cos n)

### (tan)

    	trigonometry functions
    	e.g. = n (tan n)

### (asin)

    	trigonometry functions
    	e.g. = n (asin n)

### (acos)

    	trigonometry functions
    	e.g. = n (acos n)

### (atan)

    	trigonometry functions
    	e.g. = n (atan n)

### (atan2)

    	trigonometry functions
    	e.g. = n (atan2 y x)

### (abs)

    	absolute value
    	e.g. = n (abs value)

### (pow)

    	exponentiation
    	e.g. = n (pow x 2)

### (sqrt)

    	square root
    	e.g. = n (sqrt x)

### (hypot)

    	Calculate hypotenuse of a and b
    	e.g. = n (hypot a b)

### (floor)

    	Drop the fractional part of a number
    	e.g. = n (floor x)

### (ceil)

    	Round to the next highest integer
    	e.g. = n (ceil x)

### (neg)

    	Invert the sign of a number
    	e.g. = n (neg x)

### (sign)

    	Returns the sign of a number
    	e.g. = n (sign x)

### (exp)

    	Calculate the value of e
    	e.g. = n (exp x)

### (log)

    	Logarithm function
    	e.g. = n (log x)

### (log10)

    	Base 10 logarithm
    	e.g. = n (log10 x)

### (min)

    	Get the minimum number in a list of values
    	e.g. = n (min a b c d e f g)

### (max)

    	Get the max number in a list of values
    	e.g. = n (max a b)

### Vector and matrix math

    	Some vector and matrix math is available through expression
    	operators. Supported are: mul, identity, scale, rotate,
    	translate, length, dot, angle, cross, normalize, add, sub,
    	inverse, transpose, frustum, perspective, ortho
    	Most of these behave as you'd expect. identity takes 1 argument,
    	the size of the matrix. scale, rotate and translate produce
    	transformation matrices to be multiplied by another matrix
    	(scale and translate take 3 parameters, rotate takes 4.)

## Vector Functions

### vector_add

    	push a value onto a vector
    	e.g. vector_add v 0

### (vector_size)

    	get the number of elements in a vector
    	e.g. = size (vector_size vec)

### vector_insert

    	insert a value in any position in a vector
    	e.g. vector_insert v index value

### vector_erase

    	remove from a vector
    	e.g. vector_erase v index

### vector_clear

    	empty a vector or vectors
    	e.g. vector_clear v1 v2

### vector_reserve

    	Allocate space for at least n elements to avoid reallocations
    	e.g. vector_reserve v n

### sort

    	Sort a vector
    	Takes a vector and a comparator function.
    	The comparator function should take 2 arguments and return
    	TRUE if the first is less than the second, otherwise FALSE.
    	e.g. sort vec y_sort

### unique

    	Remove all non-unique elements from a sorted vector
    	e.g. unique vec

### explode

    	Assign sequential vector elements to variables
    	e.g. var v
    	e.g. vector_init v 1 2 3 4 5
    	e.g. var a b c
    	e.g. explode v a b c ; 1 2 3 in a b c

## Map Functions

### map_erase

    	erase a key/value pair from a map
    	e.g. map_erase m "key"

### map_clear

    	clear a map or maps
    	e.g. map_clear m

### (map_keys)

    	Get the names of the keys from a map into a vector of strings
    	e.g. = v (map_keys m)

## File Functions

### (file_open)

    	open a file, mode can be either "a" "r" or "w"
    	"a" means append, "w" means write (overwrite)
    	and "r" means read mode.
    	e.g. var f
    	e.g. = f (file_open "out.txt "w")
    	f will be -1 on failure

### (file_open_cpa)

    	open a file from CPA. These are read only. All file read operations are supported.
    	e.g. = f (file_open_cpa "foo.txt")

### file_close

    	You should always close files you open with this
    	e.g. file_close f

### (file_read)

    	Read a word from a file
    	Returns empty string on eof
    	e.g. = s (file_read f)

### (file_read_line)

    	Read a line from a file
    	Returns empty string (no newline) on eof
    	e.g. = s (file_read_line f)

### (file_read_byte)

    	Read a byte from a file. Returns a negative number on eof
    	e.g. = n (file_read_byte f)

### file_write_byte

    	Write a byte to a file
    	e.g. file_write_byte f 255

### file_write

    	Write a word to a file
    	e.g. file_write f "turkey"

### file_print

    	Print to a file. Behaves exactly like print but takes a file
    	e.g. file_print f "%(20s)%(20s)%(20s)" x y z

### (file_tell)

    	Return the current file offset
    	e.g. = o (file_tell f)

### file_seek

    	Seek within file. Uses SEEK_* constants.
    	e.g. file_seek f 0 SEEK_END

## Configuration Functions

### (cfg_load)

    	load a config file
    	These files are saved in Saved Games\BooBoo along with
    	every BooBoo app, so you should use a domain name or
    	unique name
    	e.g. = cfg (cfg_load "com.nooskewl.example")

### (cfg_save)

    	save a config file
    	e.g. = success (cfg_save cfg "com.nooskewl.example")

### (cfg_get_number)

    	read a number from config.
    	e.g. = dest (cfg_get_number cfg "x")

### (cfg_get_string)

    	read a string from config
    	e.g. = dest (cfg_get_string cfg "name")

### cfg_set_number

    	set a value to be saved in a config file
    	e.g. cfg_set_number cfg "x" 1

### cfg_set_string

    	set a string value in a config file
    	e.g. cfg_set_string cfg "name" "Trent"

### (cfg_exists)

    	check if a value exists in a config file
    	e.g. = exists (cfg_exists cfg "x")

### cfg_erase

    	Erase a value in a config file
    	e.g. cfg_erase cfg "example"

### cfg_destroy

    	Free a configuration object
    	e.g. cfg_destroy cfg

## JSON Functions

You can dig down into the file by separating keys with ">"

"[0]" "[1]" etc can be used to access arrays.

You can use NULL to access the shim5.json object.

### (json_load)

    	Load a JSON file. This loads from CPA unless lffs is TRUE.
    	e.g. = j (json_load "file.json" ^ lffs)
    	Returns -1 on fail

### (json_create)

    	Create a blank JSON file. Takes a boolean that creates the root
    	as either an array (TRUE) or hash (FALSE)
    	e.g. = j (json_create FALSE)
    	Returns -1 on fail

### (json_exists)

    	Check if a key exists in a JSON object
    	e.g. = yesno (json_exists json "foo>bar>baz")

### (json_typeof)

    	Return a string representation of JSON key type
    	e.g. = val (json_typeof json "foo>bar>baz")

### (json_size)

    	Return the number of children of a JSON key
    	e.g. = n (json_size json "foo>bar>baz")

### (json_get_string)

    	Read a string from JSON
    	e.g. = s (json_get_string json "settings>profile>name")

### (json_get_number)

    	Read a number from JSON
    	e.g. = n (json_get_number json "settings>mouse>sensitivity")

### (json_get_bool)

    	Read a boolean from JSON
    	e.g. = n (json_get_boolean json "settings>gfx>crt_filter")

### json_set_string

    	Set a string in a JSON object
    	e.g. json_set_string json "foo>bar>baz" "TURNIPS"

### json_set_number

    	Set a number in a JSON object
    	e.g. json_set_number json "foo>bar>baz" 762.4

### json_set_bool

    	Set a boolean in a JSON object
    	e.g. json_set_bool json "foo>bar>baz" TRUE

### json_add_array

    	Add an array element to a json object.
    	e.g. json_add_array json "foo>bar>baz"

### json_add_hash

    	Add a hash element to a json object.
    	e.g. json_add_array json "foo>bar>baz"

### json_remove

    	Remove a child from JSON tree
    	e.g. json_remove json "foo>bar>baz"

### (json_save)

    	Save a json object to json file
    	e.g. = succeeded (json_save json "foo.json")

### json_destroy

    	Free a JSON object
    	e.g. json_destroy json

### json_register_number

    	Register a number with DevSettings
    	You can access devsettings by running with +debug and pressing F9
    	A "game>" prefix is added automatically. The optional callback is
    	called with the key's name when the value is changed in devsettings
    	e.g. json_register_number n "foo>baz" readonly ^ callback

### json_register_string

    	Register a string with DevSettings
    	You can access devsettings by running with +debug and pressing F9
    	A "game>" prefix is added automatically. The optional callback is
    	called with the key's name when the value is changed in devsettings
    	e.g. json_register_string s "foo>baz" readonly ^ callback

## CPA Functions

CPAs are extra datafiles with the same structure as data.cpa.

### (cpa_load)

    	Load a CPA datafile.
    	e.g. = cpa (cpa_load "file.cpa" ^ lffs)
    	Returns -1 on fail

### cpa_set

    	Change the default CPA file. All functions that load from data/data.cpa will
    	now load from this CPA, until cpa_set_default is called.
    	e.g. cpa_set cpa

### cpa_set_default

    	Restore the default CPA datafile
    	e.g. cpa_set_default

### (file_list)

    	Get a list of files in the data/ directory or data.cpa (just the current
    	CPA in the CLI version)
    	e.g. = vec (file_list)

### cpa_destroy

    	Free a CPA datafile
    	e.g. cpa_destroy cpa

## Audio Functions

Supported sample types are wav, ogg and flac.

Since there is no engine loop in the CLI version, audio callbacks are called between statements in that version.

The _load functions load from CPA by default, so in CLI, you'll want to set TRUE for lffs (load from filesystem) unless you have set a CPA with cpa_set.

### (get_audio_properties)

    	Get device frequency/channels
    	e.g. explode (get_audio_properties) freq channels

### (mml_create)

    	create an MML from a string. See the Music documentation section.
    	e.g. = dest (mml_create "A @TYPE3 abcdefg")
    	; this plays a b c d e f g 16th notes with a sine wave generator
    	Returns -1 on fail

### (mml_load)

    	load an MML from file
    	e.g. = dest (mml_load "sfx/blast.mml" ^ lffs)
    	Returns -1 on fail

### (mml_play)

    	play a sound. Returns an instance that can be adjusted
    	e.g. = inst (mml_play blast ^ volume loop pan callback)

### mml_stop

    	stop an MML instance
    	e.g. mml_stop inst

### mml_set_volume

    	Set the volume of an MML instance
    	Set a specific track or -1 the default is all tracks
    	e.g. mml_set_volume inst 0.5 ^ track

### mml_set_pan

    	Set the pan of an MML instance
    	-1: left 0: center 1: right
    	Set a specific track or -1 the default is all tracks
    	e.g. mml_set_pan inst -1 ^ track

### mml_set_tempo

    	Set the tempo of all tracks of an MML. After this is called,
    	further 't's (in MML syntax) will be ignored
    	Set a specific track or -1 the default is all tracks
    	e.g. mml_set_tempo inst 120 ^ track

### (mml_get_volume)

    	Get the volume of a track. Track is mandatory. If you're just setting them all
    	at once, just use track 0 here.
    	= vol (mml_get_volume inst track)

### (mml_get_pan)

    	Get the pan of a track. Track is mandatory. If you're just setting them all
    	at once, just use track 0 here.
    	= pan (mml_get_pan inst track)

### (mml_get_tempo)

    	Get the tempo of a track. Track is mandatory. If you're just setting them all
    	at once, just use track 0 here.
    	= tempo (mml_get_tempo inst track)

### (mml_num_tracks)

    	Get the number of tracks in an MML file
    	e.g. = tracks (mml_num_tracks mml)

### mml_destroy

    	Free an MML
    	e.g. mml_destroy mml

### (sample_load)

    	load a sample
    	e.g. = s (sample_load "example.wav" ^ lffs)
    	Returns -1 on fail

### (sample_create)

    	Create a sample from vector of sample data
    	The vector contains S16LE (-32767 to 32768) interlaced for each channel
    	e.g. = samp (sample_create vec freq channels)

### sample_play

    	play a sample. Returns a sample instance that can be adjusted
    	An optional duration can be used otherwise it will playback
    	at normal speed
    	e.g. = inst (sample_play s ^ volume loop pan playtime_millis callback)

### sample_stop

    	Stop a sample instance
    	e.g. sample_stop inst

### sample_set_volume

    	Set the volume of a playing sample instance
    	e.g. sample_set_volume inst 0.5

### sample_set_pan

    	Set the pan of an MML instance
    	-1: left 0: center 1: right
    	e.g. sample_set_pan inst -1

### (sample_length)

    	Returns the length in milliseconds of a sample
    	e.g. = len (sample_length samp)

### (sample_elapsed)

    	Get elapsed time of sample in milliseconds
    	e.g. = millis (sample_elapsed samp)

### (sample_get_volume)

    	Get the volume of a sample instance
    	e.g. = vol (sample_get_volume inst)

### (sample_get_pan)

    	Get the pan of a sample instance
    	e.g. = pan (sample_get_pan inst)

### sample_seek

    	Seek to milliseconds position in sample
    	e.g. sample_seek inst 1000

### sample_destroy

    	Destroy a sample
    	e.g. sample_destroy sample

## Other

### (rand)

    	random integers between two numbers inclusive
    	This uses a Mersenne Twister algorithm
    	e.g. = r (rand 0 99)

### srand

    	Seed the random number generator
    	e.g. srand (time)

### (time)

    	Return time since epoch in seconds
    	e.g. = t (time)

### print

    	print a string (like string_format)
    	e.g. print "Hello, I'm % and I like % and %" name like1 like2
    	printf-equivalent formating options are available with %(...) for
    	example %(3.16g)

### (input)

    	Read a word from stdin
    	e.g. = str (input)

### (getenv)

    	Get an environment variable
    	e.g. = dest (getenv "HOME")

### mkdir

    	Create a directory
    	e.g. mkdir my_string_path

### (list_directory)

    	List files and directories in a glob
    	e.g. explode (list_directory "/home/Pelvis/*") filenames is_dir_flags

### (get_system_language)

    	Returns the user interface language of the system
    	e.g. = lang (get_system_language)
    	lang will be in Steam format e.g. "french", "brazilian" etc
    	Currently supported are:
    		arabic
    		bulgarian
    		schinese
    		tchinese
    		czech
    		danish
    		dutch
    		english
    		finnish
    		french
    		german
    		greek
    		hungarian
    		indonesian
    		italian
    		japanese
    		korean
    		norwegian
    		polish
    		portuguese
    		brazilian
    		romanian
    		russian
    		spanish
    		latam
    		swedish
    		thai
    		turkish
    		ukrainian
    		vietnamese

### (list_drives)

    	Get a list of active drive letters in a vector (e.g. "A", "C", ...)
    	e.g. = v (list_drives)

### (get_full_path)

    	Convert a pathname to a fully qualified pathname
    	e.g. = filename (get_full_path filename)

### (get_args)

    	Populate a vector with strings of the command line arguments
    	e.g. = v (get_args)

### (get_savedgames_path)

    	Returns the path to the Saved Games folder
    	e.g. = s (get_savedgames_path)

### inspect

    	print a value in a popup for debugging
    	e.g. inspect x

### delay

    	delay an amount of milliseconds
    	e.g. delay 1000

### (get_ticks)

    	Get milliseconds since BooBoo interpreter launch
    	e.g. = ticks (get_ticks)

### text_fore

    	Change the text foreground colour. See constants for colours.
    	Each colour has a bright version toggleable by a boolean.
    	e.g. text_fore RED TRUE

### text_back

    	Change the text background colour. See constants for colours.
    	Each colour has a bright version toggleable by a boolean.
    	e.g. text_back WHITE FALSE

### text_reset

    	Reset the text colour
    	e.g. text_reset

### text_clear

    	Clear the screen
    	e.g. text_clear

### (getch)

    	Input a single character from the terminal, not waiting for newline
    	e.g. = input_number (getch)

### (kbhit)

    	Allows non-blocking use of getch. Returns nonzero if a key awaits in the buffer else FALSE.
    	e.g. :loop
    	e.g. call redraw_ascii_anim
    	e.g. ? FALSE (kbhit)
    	e.g. je loop
    	e.g. = key (getch)
    	; Note, while/for loops are considered one instruction, so audio callbacks won't be
    	; received unless you use jumps like above (because audio callbacks are called between
    	; instructions...) This is referencing callbacks passed to sample_play etc. If you're
    	; not using them, audio will play just fine if you use a while loop here.

## Constants

- TRUE - 1
- FALSE - 0
- PI - it's pi
- E - It's e
- NULL - a NULL pointer

VOID is a generic non-constant variable you can use for example to ignore returns values from expression handlers:

    	= VOID (sample_play samp)

These are used with text_fore/text_back:

- BLACK
- BLUE
- GREEN
- CYAN
- RED
- PURPLE
- YELLOW
- WHITE

Used with file_seek:

- SEEK_SET
- SEEK_CUR
- SEEK_END