Jump to:
There are 3 optional functions taking/returning no parameters called from the app:
There are also GUI callbacks for events and drawing, and a callback for generic input events, which are described in the GUI and events sections.
At startup, global code is run. Then the above mentioned callbacks get called at intervals or shutdown.
The screen is 640x360 by default, stretched to the window size appropriately. F11 toggles between fullscreen/windowed mode. F12 exits.
There are loads of command line switches you can use which come from Shim. A switch starting with + enables and a - disables things, but here are a few of them:
Some of the demo games will auto-play by an AI if a joystick isn't connected. I'll leave it as an exercise if you want to play them with keyboard.
Lots of the demos and examples use a simple Z/X key to A/B button mapping, so the keys are Z/X and arrows if you're using a keyboard. Most but not all included examples support the keyboard as well as joysticks.
The file shim5.json can be put in your data/ directory to supply some extra parameters and info such as window title and other things.
All colours use premultiplied alpha.
The following sections describe the API:
print a value in a popup for debugging e.g. inspect x
delay an amount of milliseconds e.g. delay 1000
Get milliseconds since BooBoo interpreter launch e.g. get_ticks ticks
random integers between two numbers inclusive e.g. rand r 0 99
Populate a vector with strings of the command line arguments e.g. args v
Query the logic rate (default 60) e.g. get_logic_rate r
Change the logic rate. Values between 1 and 1000 inclusive are supported. e.g. set_logic_rate 144
Get a list of files in the data/ directory or data.cpa e.g. file_list vec
clear the screen The screen is cleared to black (RGB 0, 0, 0) before draw is called. e.g. clear r g b
flip the backbuffer to the screen Normally you don't need this, as a flip is done after draw returns, but there are some situations where it's useful. e.g. flip
resize the drawing area projection e.g. resize 240 160
Get the actual (unscaled) size of the screen/window e.g. get_screen_size scr_w scr_h
Get the size of the drawing area projection. This is what "resize" changes and it starts at 640x360. e.g. get_buffer_size bw bh
The BooBoo window is managed in a way that resizing the screen in any way produces a working game with a correct image. Sometimes this requires "black bars". screen_offset gives you the position of the top left of the drawing given any black bars. This is mainly useful for some shaders. e.g. get_screen_offset ox oy
Retrieve the scale of the projection. BooBoo starts in a 1280x720 window with a 640x360 buffer, so e.g. the scale would be 2 to start and would change based on window size and buffer size. e.g. get_scale s
Apply a screen shake effect Currently only works with 2d projection, not after set_3d e.g. screen_shake amount_in_pixels duration_in_millis
Find out if the screen is currently fullscreen e.g. is_fullscreen onoff
Change from fullscreen to windows or vice versa depending on the current windowed/fullscreen state. e.g. toggle_fullscreen
Add a popup notification in the top right of the screen that goes away after a few seconds. This uses the default font named font.ttf. e.g. add_notification "You won!"
Query the refresh rate e.g. get_refresh_rate r
Set a scissor rectangle. This is based on the projection you're using, not actual pixel coordinates to make it easier. Anything drawn outside of this will not be drawn. e.g. set_scissor x y w h
Undo a set_scissor, reverting the scissor rectangle to fullscreen. e.g. unset_scissor
batch primitives for speed e.g. start_primitives
batch primitives for speed e.g. end_primitives
draw a line e.g. line r g b a x1 y1 x2 y2 thickness
Draw an outline triangle e.g. triangle r g b a x1 y1 x2 y2 x3 y3 thickness
draw a filled triangle with 3 colours e.g. filled_triangle r1 g1 b1 a1 r2 g2 b2 a2 r3 g3 b3 a3 x1 y1 x2 y2 x3 y3
draw a outline rectangle e.g. rectangle r g b a x y w h thickness
draw a filled rectangle e.g. filled_rectangle r1 g1 b1 a1 r2 g2 b2 a2 r2 g3 b3 a3 r4 g4 b4 a4 x y w h
draw a outline ellipse with give number of pie slices (-1 for auto) e.g. ellipse r g b a x y radius_x radius_y thickness sections
draw a filled ellipse with given number of pie slices (-1 for auto) e.g. filled_ellipse r g b a x y radius_x radius_y sections
draw a outline circle with given number of pie slices (-1 for auto) e.g. circle r g b a x y radius thickness sections
draw a filled circle with give number of pie slices (-1 for auto) e.g. filled_circle r g b a x y radius sections
create a render target e.g. image_create dest w h
Set the render target. This only works with images created with image_create. e.g. set_target img
Set the render target to the backbuffer e.g. set_target_backbuffer
load an image e.g. image_load dest filename
draw an image e.g. image_draw img tint_r tint_g tint_b tint_a x y flip_h flip_v
draw a region of an image and maybe stretch it e.g. image_stretch_region image r g b a source_x source_y source_w source_h dest_x dest_y dest_w dest_h flip_h flip_v
draw an image with rotation and scale e.g. image_draw_rotated_scaled img tint_r tint_g tint_b tint_a pivot_x pivot_y x y angle scale_x scale_y flip_h flip_v
Draw an image as a 9patch (9 equal chunks, 3x3 with the edges outlining and the centre filled with the centre chunk) e.g. image_draw_9patch img tint_r tint_g tint_b tint_a x y w h
start a batch of images for speed (must be same image) e.g. image_start img
end a batch of images e.g. image_end img
get image width/height e.g. image_size img w h
Free an image e.g. image_destroy img
Load a sprite. Please see the example for the format of a sprite. Basically, each animation in a sprite is a sprite sheet exported from Aseprite. Then there is a sprite.json which has a list of animation names. e.g. sprite_load sprite "my_sprite"
Set the current animation. You can optionally add a callback which will be called when the animation is finished. The callback takes 1 parameter which will be the sprite (number) that set_animation was called on. e.g. sprite_set_animation sprite "punch" my_function
Like sprite_set_animation but forces nothing if the same animation has already been set. Cannot take callbacks e.g. sprite_set_animation_lazy sprite "run"
Returns the name of the current animation e.g. sprite_get_animation sprite anim_name
Returns the name of the previous animation e.g. sprite_get_previous_animation sprite anim_name
Returns the total length in milliseconds of the current animation e.g. sprite_length sprite l
Returns the current frame number e.g. sprite_current_frame sprite n
Gets the number of frames in the current animation e.g. sprite_num_frames sprite nf
Returns the size of the current frame's image e.g. sprite_current_frame_size sprite w h
Start a sprite's animation (if stopped) e.g. sprite_start sprite
Stop a sprite's animation e.g. sprite_stop sprite
Reset a sprite's animation to the beginning e.g. sprite_reset sprite
Returns the top left/bottom rightmost opaque pixels in the sprite e.g. sprite_bounds sprite x1 y1 x2 y2
Get the number of milliseconds of elapsed time of the current animation e.g. sprite_elapsed sprite n
Get a vector of numbers which are the duration of each frame in the sprite in milliseconds e.g. sprite_frame_times sprite v
Check if a sprite is started or not e.g. sprite_is_started sprite onoff
Free a sprite e.g. sprite_destroy s
load a TTF font All of the font functions support UTF8 e.g. font_load font "DejaVuSans.ttf" px_size smooth_flag
draw text. Colour codes can be used if you supply a data/gfx/palettes/palette.gpl with a GIMP palette. Colour codes use |## where ## is a hex number referencing a palette entry. Up to 256 extra glyphs can be added with font_add_extra_glyph. Those use @##. e.g. font_draw font r g b a "HELLO" x y
get width of a string given a font e.g. font_width font dest "FOOBARBAZ"
get the height of a font e.g. font_height font dest
You can add up to 256 extra glyphs (0 to 255.) The can be used with @## with font_draw. e.g. font_add_extra_glyph font #00 my_image
Free a font e.g. font_destroy f
You should call this to set a (square) tile size before tilemap_load unless your tiles are the default, 16 pixels in size. e.g. set_tile_size 32
Load a tilemap from data/misc/maps. Tiles should be located in data/gfx/images/tiles and named tiles0.png, tiles1.png and so on (.tga is also supported.) See AshEdit for more details on maps and creating them. e.g. tilemap_load a_number "map.wm2"
Draw a selection of tilemap layers This automatically crops (doesn't draw) tiles outside the screen e.g. tilemap_draw tilemap start_layer_inclusive end_layer_inclusive x y
Get the number of layers in a tilemap e.g. tilemap_num_layers tilemap nl
Get the size of a tilemap in tiles e.g. tilemap_size tilemap w h
Check if a tile is walkable e.g. tilemap_is_solid tilemap solid x y
Get group info about groups in a tilemap e.g. tilemap_get_groups tilemap vec The vector be stuffed with type/x/y/w/h vectors
Tile groups can be animated. The delay is in milliseconds. Width and height are the width and height of the area to animate. Then the vector contains the topleft tile position of each frame of animation (should be width by height) as a vector of vectors of 2 numbers each (x/y) e.g. tilemap_set_animated_tiles tilemap delay w h anim_data
A* pathfinding using the tilemap solids and your own supplied points. The path returned is a vector of vectors of x/y values e.g. tilemap_find_path tilemap path extra start_x start_y end_x end_y path will be empty if no path is found
Set the solid flag of a tile e.g. tilemap_set_solid tilemap x y onoff
Change a tile in the tilemap to the tile x/y given e.g. tilemap_set_tile tilemap layer posx posy tile_x tile_y solid
Get tile x/y and solid flag of layer/position in tilemap e.g. tilemap_get_tile tilemap out_tx out_ty out_solid layer x y out_tx/ty refers to x/y position within the tile sheet.
Free a tilemap e.g. tilemap_destroy tilemap
Load a shader e.g. shader_load n "my_vert" "my_frag" When running on OpenGL this will load from data/gfx/shaders/glsl/my_vert.txt. D3D will load data/gfx/shaders/hlsl/my_vert.shader
Use a shader e.g. shader_use shader
Use the default shader e.g. shader_use_default
Set a boolean value in a shader e.g. shader_set_bool shader "b" 0
Set an integer value in a shader e.g. shader_set_int shader "i" 1298
Set a float value in a shader e.g. shader_set_float shader "f" 10.1
Set a colour value in a shader e.g. shader_set_colour shader "c" r g b a
Set a texture value in a shader e.g. shader_set_texture shader "tex" my_img
Set a matrix uniform value in a shader e.g. shader_set_matrix shader "mymat" m
Set a float vector uniform in a shader e.g. shader_set_float_vector shader "myvec" vec
Free a shader e.g. shader_destroy shader
Load a model with an optional armature an animations from .x file e.g. model_load model_id "filename.x"
Draw a model with its transforms applied e.g. model_draw model r_tint g_tint b_tint a_tint
Revert back to 2d drawing e.g. set_2d
Enable 3d rendering and projection e.g. set_3d
Set model transform to identity e.g. model_identity model
Alter the scale of a model. It starts at 1 across the board. These numbers get added to that. e.g. model_scale model add_sx add_sy add_sz
Alter the rotation of a model. These numbers are angles about each axis and get added to the default of 0 and accumulate with each call. e.g. model_rotate model angle axisx axisy axisz
Translate (move) a model. This sticks like rotation and scaling. The numbers you supply get added to the current position of the model. e.g. model_translate model add_x add_y add_z
Retrieve the models current position e.g. model_get_translate model x y z
Set the modelview matrix to the identity matrix e.g. identity_3d
Scale the modelview matrix e.g. scale_3d sx sy sz
Rotate the modelview matrix e.g. rotate_3d rx ry rz
Translate the modelview matrix e.g. translate_3d x y z
Set the animation to the one named. You can optionally pass a BooBoo function that takes and returns no arguments that will be called when the animation finishes. e.g. model_set_animation model "attack" done_attack
Stop a models animation e.g. model_stop model
Reset a models animation e.g. model_reset model
Get the dimensions of a model e.g. model_size model szx szy szz
Draw arbitrary 3d geometry All vectors are vectors of numbers e.g., one vertex is 3 numbers, one face is 3 numbers, one colour is 4 faces are vertex indices colours are per-face-vertex empty colour vector = white empty normal vector = 0.0 e.g. draw_3d vert_vec face_vec colour_vec normal_vec num_triangles
Draw arbitrary 3d geometry textured All vectors are vectors of numbers e.g., one vertex is 3 numbers, one face is 3 numbers, one colour is 4 faces are vertex indices colours are per-face-vertex empty colour vector = white empty normal vector = 0.0 e.g. draw_3d_textured tex vert_vec face_vec colour_vec normal_vec texcoord_vec num_triangles
Create a billboard e.g. billboard_create result image x y z w h
Create a billboard backed by a sprite unit is the number of pixels that spans 1 3D unit e.g. billboard_from_sprite result sprite x y z w h unit
Draw a tinted billboard e.g. billboard_draw billboard r g b a
Move a billboard e.g. billboard_translate b x y z
Scale a billboard e.g. billboard_scale b sx sy
Free a model e.g. model_destroy model
Free a billboard e.g. billboard_destroy b
Widgets are generic rectangles with a userdata attached to them to supply their properties.
Two callbacks get called for every GUI event/drawing operation:
gui_event widget_id type a b c d x y w h focussed ~userdata
gui_draw widget_id x y w h focussed ~userdata
(note the ~, which is quite handy if you want to store state info in userdata)
a, b, c and d are the same as for the global 'event' callback, described in Events. x, y, w and h are the calculated position and size of the widget in pixels.
Create a widget Sizes less than 1 are taken as a percentage of the remaining size e.g. widget_create result w h userdata
Create a widget that fits remaining size on one dimension Constants FIT_X and FIT_Y are used for the first parameter The other dimension is then specified as the second parameter, which can be less than 1 to use a percentage size e.g. widget_create_fit result FIT_X h userdata
Create a widget that fits the remaining size on X and Y e.g. widget_create_fit_both result userdata
Widget hierarchy is important. You want to have one root widget and add everything (perhaps in multiple containers) to it e.g. widget_set_parent child parent
Similar to float left in CSS e.g. widget_set_float_left widget onoff
Similar to float right in CSS e.g. widget_set_float_right widget onoff
Similar to float bottom in CSS e.g. widget_set_float_bottom widget onoff
Centre a widget horizontally e.g. widget_set_centre_x widget onoff
Centre a widget vertically e.g. widget_set_centre_y widget onoff
Tell a widget to clear past widgets floating horizontally e.g. widget_set_clear_float_x widget onoff
Tell a widget to clear past widgets floating vertically e.g. widget_set_clear_float_y widget onoff
Start a new row for this widget e.g. widget_set_break_line widget onoff
Allow a widget to accept the input focus or not e.g. widget_set_accepts_focus widget onoff
Set left padding e.g. widget_set_padding_left widget px
Set right padding e.g. widget_set_padding_right widget px
Set top padding e.g. widget_set_padding_top widget px
Set bottom padding e.g. widget_set_padding_bottom widget px
Hint at the widget to the left of this one for focus changes with keyboard/gamepad e.g. widget_set_left_widget widget left_widget
Hint at the widget to the right of this one for focus changes with keyboard/gamepad e.g. widget_set_right_widget widget right_widget
Hint at the widget to the up of this one for focus changes with keyboard/gamepad e.g. widget_set_up_widget widget up_widget
Hint at the widget to the down of this one for focus changes with keyboard/gamepad e.g. widget_set_down_widget widget down_widget
Start executing a gui e.g. gui_start root_widget
Close the toplevel GUI and destroy widgets e.g. gui_exit
Check if a point is inside a model The model must be closed for this to work properly e.g. cd_model_point result model x y z
Check if a line segment intersects or is contained in a model If result is TRUE, outx/outy/outz will have the intersection point e.g. cd_model_line_segment result model x y z x2 y2 z2 outx outy outz
Check if two sphere intersect e.g. cd_sphere_sphere result x y z r x2 y2 z2 r2
create an MML from a string e.g. mml_create dest "A @TYPE1 abcdefg"
load an MML from file e.g. mml_load dest "sfx/blast.mml"
play a sound e.g. mml_play blast volume loop
stop a looping sound e.g. mml_stop blast
load a sample e.g. sample_load s "example.wav"
play a sample e.g. sample_play s volume loop
Stop a looping sample e.g. sample_stop s
Free an MML e.g. mml_destroy mml
Destroy a sample e.g. sample_destroy sample
poll a joystick for input e.g. joystick_poll joystick_number x1 y1 x2 y2 x3 y3 l r u d a b x y lb rb ls rs back start
get number of connected joysticks e.g. joystick_count num_joysticks
Rumble the joysticks e.g. rumble duration_in_ms
Get the mouse position scaled relative to the projection The full window starts mapped to 640x360. e.g. mouse_get_position mx my
Get the mouse button state Wheel will be 1 (forward) 0 (not moved) or -1 (backward) e.g. mouse_get_buttons left middle right wheel
Get the mouse delta movement since last call The first time this is called, the values will be set to 0 and return 0 e.g. mouse_get_delta dx dy
Keep the mouse in the window and use relative coordinates e.g. mouse_set_relative bonoff
Read if a key is pressed or not. Please use or modify keycodes.inc From the 'keys' example for keycode constants. e.g. key_get dest KEY_SPACE
Load a JSON file e.g. json_load j "file.json"
Read a string from JSON You can dig down into the file by separating keys with ">" "[0]" "[1]" etc can be used to access arrays. e.g. json_get_string json s "settings>profile>name"
Read a number from JSON You can dig down into the file by separating keys with ">" "[0]" "[1]" etc can be used to access arrays. e.g. json_get_number json n "settings>mouse>sensitivity"
Free a JSON object e.g. json_destroy json
load a config file e.g. cfg_load cfg "com.illnorth.example"
save a config file e.g. cfg_save cfg ret_bool_success "com.illnorth.example"
read a number from config. Doesn't touch dest if the named value doesn't exist e.g. cfg_get_number cfg dest "x"
Doesn't touch dest if the named value doesn't exist read a string from config e.g. cfg_get_string cfg dest "name"
set a value to be saved in a config file e.g. cfg_set_number cfg "x" 1
set a string value in a config file e.g. cfg_set_string cfg "name" "Trent"
check if a value exists in a config file e.g. cfg_exists cfg exists "x"
Erase a value in a config file e.g. cfg_erase cfg "example"
Free a configuration object e.g. cfg_destroy cfg
Note: these values are not read-only (so not technically constant...)
The following keyboard constants are used with key_get:
Event types:
Joystick buttons for events:
GUI constants:
You can receive events so you're sure you don't miss anything. Define a function called event with 5 arguments:
function event type a b c d { ... }
type will be one of the EVENT_* constants listed in the Constants section. The parameters depend on the event type. Unused parameters are undefined for an event that doesn't supply them. The parameters for each event type are:
a - the key constant b - TRUE if this is a repeat event
a - the key constant
a - the button constant in constants b - TRUE if it is a repeat event
a - the joystick button constant
a - the axis index b - the value from -1 to 1
a - the button b - TRUE if it is a repeat event c - mouse x d - mouse y
a - the button
a - the x window coordinate b - the y window coordinate c - the delta x movement d - the delta y movement
a - the horizontal wheel movement b - the vertical wheel movement