SUGAR v0.0.0d
by Remy Devaux // @trasevol_dog // remy@trasevol.dog

  Welcome to SUGAR!
  SUGAR is a 2D game engine designed for making small neo-retro games and programs.


-------------------------------
	core
- - - - - - - - - - - - - - - -

	These are some basic functions for using the engine.


load	filepath
	Loads a lua file to run.

run
	Runs the loaded lua file, then calls _init if it is defined, then starts calling _update and _draw every frame.

stop
	Stops the running program.

resume
	Resumes the program.

step
	Advances the program by one frame, calling _update and _draw.

execute	lua_code
	Executes the code in the string lua_code.

reset
	Closes all non-tool windows, deletes surfaces, unloads assets, erases controls.


-------------------------------
	manual
- - - - - - - - - - - - - - - -

	To help you get a grip on SUGAR.
	It is recommended use mantxt at least once to skim through the whole manual and see what functions are available.


help
	Prints out some helpful indications in the console.

man	[function]
man	[category]
	Prints out an explainer in the console.
	'man' without parameters to list categories.
	'man [category]' to list functions in that category.

mantxt
	Saves the whole manual to manual.txt.


-------------------------------
	misc
- - - - - - - - - - - - - - - -

	These functions don't quite fit any other categories.


sysbat
	Gets info about the battery.
	Returns the percentage of charged battery, whether the machine is operating on battery, and how many seconds are left until the battery runs out.
		pctg, on_bat, secs = sysbat()

url	link
	Opens 'link' in the OS's default browser.


-------------------------------
	string
- - - - - - - - - - - - - - - -

	SUGAR provides these functions for manipulating Lua strings.


type	v
	Returns the type of v as a string.

sub	str pos1 [pos2]
	Returns a portion of the string str, starting at pos1 and up to pos2 if set, or to the end of str.
		sub("hello!", 2,4) --> "ell"
		sub("hello!", 3)   --> "llo!"

ord	str [i]
	Returns the character value of the character at 'i' in the string, or the first character in the string if 'i' isn't set.
		ord("ABCD")    --> 65, for 'A'
		ord("ABCD", 2) --> 66, for 'B'

chr	a [...]
	Returns the character corresponding to 'a' as a character value.
	If more arguments are passed, returns a string made up of the characters corresponding from each argument.
		chr(65)       --> 'A'
		chr(65,66,67) --> "ABC"


-------------------------------
	table
- - - - - - - - - - - - - - - -

	SUGAR provides these functions for manipulating Lua tables.


add	tbl v [index]
	Adds v at the end of the table tbl.
	If index is set, inserts v at that position instead.
		a = {}
		add(a, 3)    --> a={3}
		add(a, "hi") --> a={3, "hi"}

del	tbl v
	Deletes the first instance of v found in the table tbl.
	Moves back the following elements to close space.
	If v isn't found in tbl, nothing is done.
		a = {3,5,6}
		del(a, 5)  --> a={3,6}

deli	tbl i
	Deletes the element at position i in the table tbl.
	Moves back the following elements to close space.

foreach	tbl foo
	Calls the function foo with each item in the table tbl.
		a = {1,2,3}
		foreach(a, print)

all	tbl
	To use in 'for' loops, to iterate on the items in the table tbl.
	Will only iterate over elements linearly indexed, starting from 1.
		a = {1,2,3}
		for n in all(a) do
		  print(n)
		end

pairs	tbl
	To use in 'for' loops, iterates on all the items in tbl, providing every item's key and value.
	Will iterate over all items stored in tbl, regardless of indexing.
	Order cannot be predicted.
		t = {
		  [1] = "hi",
		  ["hey"] = "ok"
		}
		for k,v in pairs(t) do
		  print(k.." : "..v)
		end

ipairs	tbl
	Like 'pairs' but only iterates over elements linearly indexed, and following their order.

unpack	tbl
	Syntaxically extracts elements of a table.
		a,b,c = unpack({1,2,3})
		--> a=1  b=2  b=3
		function foo(d,e,f) end
		t = {4,5,6}
		foo(unpack(t))
		--> foo(4,5,6)


-------------------------------
	debug
- - - - - - - - - - - - - - - -

	SUGAR features a simple debug log system with a distinction between informational logs, warnings, and errors. Those logs are stored in log.txt in the project.


log	str
wlog	str
rlog	str
	Adds str to the logs as informational, a warning, or an error, respectively.

hex	num
	Returns the number num as a string in hexadecimal format.

assert	bool str
	If bool fails, aborts the program and adds str to the logs as an error.

abort	[str]
	Aborts the program. If str is set, it is added to the logs as an error.

clipboard	[str]
	If str is set, writes it to the clipboard.
	If it isn't, returns the clipboard's content.


-------------------------------
	files
- - - - - - - - - - - - - - - -

	These functions allow for basic file browsing.
	'cd' and 'ls' are mainly intended to be used in the console.


cd	[path]
	Changes Directory.
	Use ".." as path to go to parent directory.

ls	[path]
	Lists the files in the current directory or in the folder at 'path' if it is set.

file	filepath [str]
	If str is set, writes it as the filepath file.
	If it isn't, returns the content of the filepath file as a string.


-------------------------------
	time
- - - - - - - - - - - - - - - -

	You can limit the frequency of calling _update() and _draw() using fpslimit.
	You can check for your program's performance with aft. (Average Frame Time) This performance does depend on the machine and the other processes running on it.


t
time
	Returns the time since the last call to 'run' in seconds.
	Alternatively you may call time() for the same result.

dt
delta
	Both return the time between the current frame and the last in seconds.

fpslimit	[n]
	If n is set, limits the number of times _update and _draw are called in a second to n.
	Otherwise, removes the fps limit.
	By default, SUGAR starts with 60 as fps limit.

sleep	n
freeze	n
	Waits n seconds before continuing with the program.
	With sleep, the waited time will be added to dt/delta for the next frame.
	With freeze, the waited time will be ignored by dt/delta.
	If you're not sure which to use, prefer freeze.

fps
	Returns the current number of frames per second, as averaged across 64 frames.
	The result will not go above the current fps limit if it is set.

aft
	Returns the Average Frame Time, across the last 64 frames.
	This ignores the fps limit and gives you the average time needed to process each frame instead.
	A lower number means your program is more performant.

ltime
gtime
	Returns the local time for ltime, or the GMT/UTC time for gtime, as follows:
		 second, minute, hour, day, month, year, weekday = ltime()


-------------------------------
	graphics
- - - - - - - - - - - - - - - -

	This category encompasses graphical operation parameters, palette operations, and graphical surfaces.
	'man drawing' for drawing shapes.
	'man sprites' for using sprites.
	'man text' for rendering text.


camera	[x y]
	Sets a coordinate offset of -x;-y for all drawing operations until this function is called again.
	camera() to reset the offset back to 0.

tcamera	[x y]
	Adds -x;-y the camera offset.

clip	[x y w h]
	Sets a clipping region delimiting all drawing operations' area of effect, until this function is called again.
	clip() to reset.

color	[c0 [c1]]
	Sets the colors to be used by drawing operations.
	(*technical) If c1 isn't defined, it takes the value from the second lower byte of c0's integer value.
	c0 defaults to 0.

pal	[ca cb [scr_lvl]]
pal	[tbl [scr_lvl]]
	Swaps the color ca for the color cb.
	pal() to reset.
	If scr_lvl isn't set (or is false), this affects drawing operations directly.
	If scr_lvl is set and true, this doesn't affect drawing operations, but will swap the colors rendered to physical screen instead.
	When the first parameter is a table, it is used to map palette swaps.
		pal {[3]=5, [7]=8}
		pal(3, 5) pal(7, 8)

palette	[name]
palette	[tbl]
	Switches SUGAR's palette.
	If 'name' is a known palette, uses that palette.
	If 'name' ends in ".png", tries to load the file 'name' and makes a palette from it.
	If you use the function with a table, it will make the palette from the RGB values listed in the table. (0xRRGGBB)
	palette() returns the number of colors in the current palette.
		palette {0x000000, 0xffffff} -- sets the palette to black & white
		known palette names are: kirokaze_gb, gb_chocolate, black_zero_gb pokemon_gb blessing oil6 nyx8 equpix15 pico8 sweetie16 grunge_shift bubblegum16 mail24 arcade29 pico8+ ufo50 famicube aap_splendor128

rgb	r g b
	Returns the color rgb as 0xRRGGBB.
	r, g, b are taken to be within the 0-255 range.

hsv	h s v
	Converts and returns the hsv color to an 0xRRGGBB value.
	h, s, v are taken to be within the 0-255 range.

newsrf	w h [name [mem_adr]]
newsrf	w h [mem_adr]
newsrf	data [name [mem_adr]]
newsrf	data [mem_adr]
	Creates a new surface and returns its name.
	if name isn't set, a numerical name is automatically set.
	if mem_adr isn't set, free space is found in the memory.
	if data ends in ".png", loads it as a png file. Otherwise, attempts to parse data as an expsrf export.

delsrf	name
	frees the surface called 'name' created with newsrf.

target	[name]
	Sets the surface called 'name' as target for all operations.
	target() resets to the window's screen surface as target.

expsrf
	Returns the target surface's data as a text string.
	This returned string can be used as the 'data' argument for newsrf.

srfinfo
	Returns the current target surface's info in this order:
		name, mem_chunk, mem_adr, mem_len = srfinfo()

srfsize
	Returns the width and height of the current target surface.
		w, h = srfsize()

srfshot	scale filename
	Saves the current target surface as the png file 'filename'.
	scale defines every pixel's size in the saved file. (must be >=1)


-------------------------------
	drawing
- - - - - - - - - - - - - - - -

	This category groups the functions which draw primitive shapes.
	Those functions can be used on the screen or any created surface by using the 'target' function.


fillp	[ptrn [trsp]]
	Sets a 4x4 2-color tiling fill pattern for drawing shapes.
	This pattern is built from the bits of the ptrn value. See example below.
	If trsp is set and true, only one color will be drawn and the other will be transparent. Otherwise, the two colors from 'color' are used.
		fillp(0b 1010 0000 1010 0000) -- will give this pattern:
		 B a B a
		 a a a a
		 B a B a
		 a a a a

cls	[v]
	Clears the current target surface, setting all its pixels to 'c'.
	'v' defaults to 0.

rect	xa ya xb yb [col]
rectfill	xa ya xb yb [col]
	Draws a rectangle or filled rectangle between the points xa;ya and xb;yb.

circ	x y r [col]
circfill	x y r [col]
	Draws a circle or filled circle at x;y with radius r.
	(technical) If (r%1 < 0.5) the diameter of the circle will be even, if (r%1 >= 0.5) it will be odd.

tri	xa ya xb yb xc yc [col]

trifill	xa ya xb yb xc yc [col]
	Draws a triangle or filled triangle between the points xa;yb, xb;yb, and xc;yc.

line	xa ya xb yb [col]
	Draws a line between the points xa;ya and xb;yb.

pset	x y [col]
	Sets the color of the pixel at x;y.

pget	x y
	Returns the color of the pixel at x;y.


-------------------------------
	sprites
- - - - - - - - - - - - - - - -

	All the necessary functions for using spritesheets.
	You can have multiple spritesheets and switch between them using the 'spritesheet' function.
	The spritesheet surface is considered to be a grid of cells to pick from. The size of these cells is 8x8 by default, but that can be changed with 'sprgrid'.
	'palt' lets you set which colors are to be considered transparent in the spritesheet. By default only the color 0 is transparent.


spritesheet	surface_name
	Uses the surface named [surface_name] as spritesheet.
	The spritesheet surface needs to have been created before calling this function.

sprgrid	[tile_w tile_h]
	Sets the tile size to be used for drawing sprites.
	sprgrid() to reset to 8x8 tiles.

palt	col [trsp]
	Sets whether the color 'col' should be considered transparent when drawing sprite.
	If 'trsp' is true, the color 'col' will not be drawn when drawing sprites.
	'trsp' defaults to false.

spr	n x y [w h [flip_x flip_y]]
	Draws the n'th sprite in the spritesheet, on the target surface at x, y.
	w and h define how many tiles should be drawn in width and height. They are 1,1 by default, drawing just one tile.
	If flip_x is true, flips the sprite horizontally.
	If flip_y is true, flips the sprite vertically.

aspr	n x y a [w h [scale_x scale_y [anchor_x anchor_y]]]
	Draws the n'th sprite in the spritesheet, on the target surface at x, y, rotated by a.
	w and h define how many tiles should be drawn in width and height.
	scale_x and scale_y default to 1,1 and scale the sprite horizontally and vertically before rotation.
	anchor_x and anchor_y are pixel coordinates for the point in the sprite to rotate around. They default to the sprite's center.

sspr	sx sy sw sh dx dy [dw dh]
	Draws the rectangle (sx sy sw sh) from the spritesheet to the target surface at dx,dy, stretched to fit dw,dh.
	dw,dh default to sw,sh.

sset	x y c
	Sets the color of the pixel at x,y in the spritesheet.

sget	x y
	Returns the color of the pixel at x,y in the spritesheet.


-------------------------------
	text
- - - - - - - - - - - - - - - -

	SUGAR provides a default font but lets you load more as well.


newfnt	data [name [mem_adr]]
newfnt	data [mem_adr]
newfnt	file_png chars [name [mem_adr]]
newfnt	file_png chars [mem_adr]
	Loads a font into SUGAR. If no name is given, the function generates one and returns it.
	"data" should be a string made with the function 'expsrf'.
	If using a file, make sure to use the complete filename, including the ".png". The file should hold all the glyphs lined up horizontally with one empty column of pixels between every pair. The last horizontal line serves to define glyph continuity, leave it empty if you don't understand how to use it.
	If mem_adr is set, the font's data will be stored at that adress in the memory. If it isn't set, Sugar will find available space.

delfnt	name
	Deletes the font 'name' from memory.

font	[name]
	Sets the font to use for the next 'print' calls.
	font() resets to the default font.

expfnt
	Returns formatted data for the font currently in use.
	The result of this can be used in 'newfnt'.

fntinfo
	Returns the name of the font currently in use and the number of glyphs it holds.
		name, chars = fntinfo()

strwidth	str
	Returns how many pixels in width would the string str take if rendered with the current font.

print	str [x y [col]]
	If only the first parameter is provided, prints it on the console.
	Otherwise, prints str on the target surface at x,y.


-------------------------------
	window
- - - - - - - - - - - - - - - -

	You'll need to create at least one window for your program.


newwin	name w h [scale [window_mode [screen_mode [mem_adr]]]]
	Creates a new window named 'name'.
	w,h is the resolution of the screen surface for the window. It will be magnified by 'scale'.
	window_mode can be either of: resize, fullscreen, borderless, fixed. (default is resize)
	screen_mode can be either of: stretch, intscale, scale, fixed, resize. (default is intscale)
	If mem_adr is set, the window's screen data will be stored at that adress in the memory. If it isn't set, Sugar will find available space.

delwin	name
	Closes and deletes the 'name' window, frees its memory space.

window	name
	Targets the 'name' window for winspec and for drawing to screen.
	The graphical function target() without arguments will target the current target window's screen.

flip	[window_name]
	Displays the screen's contents on the window.
	If window_name isn't set, defaults to the current target window.
	This is called automatically after your _draw function.

winspec	param [...]
	winspec("wmode") winspec("wmode", new_mode): get/set the window mode.
	winspec("smode") winspec("smode", new_mode): get/set the screen mode.
	winspec("screen") winspec("screen", w, h): get/set the screen's size.
	winspec("title") winspec("title", new_title): get/set the title.
	winspec("top") winspec("top", stay_on_top): get/set whether to stay on top of other windows.
	winspec("trsp") winspec("trsp", col, make_trsp): get/set a transparent color.
	winspec("lay") winspec("lay", x, y, w, h): get/set the window's position and size in desktop coordinates.
	winspec("focus") winspec("focus", grab): get/set the whether window is in focus.
	winspec("name"): get the window's name.
	winspec("on_close", foo): set a function to be called on closing the window.


-------------------------------
	audio
- - - - - - - - - - - - - - - -

	Load your sound effects with 'newsfx' and your music tracks with 'newmus', and play them with 'sfx' and 'music'.


newsfx	file [id [volume]]
newmus	file [id [volume]]
	Loads a new sound effect (sfx) or music (mus) from file.
	Only supports .WAV and .MP3 filetypes.
	Returns the id on success, returns an empty string on failure.
	If id isn't set, a new unused id is found and assigned to the sfx or music.
	volume should be within 0-1 range and defaults to 1.

delsfx	id
delmus	id
	Deletes the sound effect / music.

sfxvol	[v [sfx]]
	If sfxvol() is called with no argument, returns the current volume multiplier for sound effects.
	Otherwise if sfx is set, sets the volume for that specific sfx to v.
	If not, sets the volume multiplier for all sound effects to v.
	If set, v should be within 0-1 range.

musvol	[v]
	If v is set, sets the volume multiplier for musics to v.
	musvol() returns the current volume multiplier for musics.

sfx	id
	Plays the sound effect 'id'.

music	id
	Plays the music 'id'.


-------------------------------
	input
- - - - - - - - - - - - - - - -

	You can set up your inputs with 'controls', and you can set up a a way for the user to rebind the controls, by using 'getinp' and 'defbtn'.


quit
	Quits SUGAR, closing all windows.

controls	[str [p_id]]
	If str isn't set, returns the current control scheme as a string.
	If str is set, defines the controls for player p_id. (0 by default)
	Your call to controls should look like this:
	controls([[
	  left > k:left, c:dpad:left
	  right> k:right,c:dpad:right
	  up   > k:up,   c:dpad:up
	  down > k:down, c:dpad:down
	  a    > k:z, k:c, c:a
	  b    > k:x, c:b, c:x
	]])
	(please refer to 'input_codes' in manual.txt for input codes)

defbtn	btn_name p_id new_def
defbtn	btn_name [p_id]
	If all 3 arguments are passed, (re)defines the button btn_name for player p_id, with the string of input codes new_def.
	Otherwise, returns the current definition for btn_name, for player p_id. (0 by default)
		defbtn("btn_X", 0, "k:x, c:x")
		print(defbtn("btn_X"))
		--> "k:x,c:x"

btn	id [p_id]
btnp	id [p_id]
btnr	id [p_id]
btnv	id [p_id]
	All observe the button 'id' for player p_id. (player 0 by default)
	btn returns a boolean state. (true/false)
	btnp (p for press) returns true only if the button started being active and wasn't during the last frame.
	btnr (r for release) returns true only if the button stopped being active but was active during the last frame.
	btnv returns the value for the button, useful for mouse positions and controller axes.
	id must be the name of a button defined with 'controls' or 'defbtn'.
	id CANNOT be a input code directly.

getinp	[foo]
	The function foo will be called on new inputs with their input code as parameter.
	Useful for letting the user rebind the controls.
	getinp() to reset, your function will not be called anymore.
		function f(inp)
		  print(inp)
		end
		getinp(f)

txtinp	[foo]
	The function foo will be called on text inputs, with the input as parameter, as a string.
	txtinp() to reset, your function will not be called anymore.
		function g(txt)
		  print(txt)
		end
		txtinp(g)

mouse	param [...]
	mouse("lock", enable) mouse("lock"): set/get mouse position lock.
	mouse("global", enable) mouse("global"): set/get global mode, mouse inputs react even when outside the window.
	mouse("show", enable) mouse("show"): set/get whether the cursor should be visible.
	mouse("setpos", x, y): set the mouse's position.

ctrlr	param [...]
	ctrlr("count"): returns how many controllers are connected.
	ctrlr("list"): returns a table listing the connected controllers' indexes.
	ctrlr("name", c_id): returns the name of the controller c_id.
	ctrlr("which", p_id): returns the controller index assigned to player p_id.
	ctrlr("assign", c_id, p_id): assigns controller c_id to player p_id.

input_codes
	This isn't a function, but rather an explainer of the input codes format.
	A code denotes a precise input to listen for. These codes are used for 'controls', 'defbtn' and 'getinp'.
	A code is always a string built out of a first particle, a second, and sometimes third, all separated by ':'. 
	 
	In the case of a keyboard key, the code must be "k:" and then one of these:
	0 1 2 3 4 5 6 7 8 9
	a b c d e f g h i j k l m n o p q r s t u v w x y z
	down left right up
	apostrophe backslash backspace capslock comma copy delete displayswitch eject end equals escape execute f1 f10 f11 f12 f13 f14 f15 f16 f17 f18 f19 f2 f20 f21 f22 f23 f24 f3 f4 f5 f6 f7 f8 f9 home insert lalt lctrl leftbracket lgui lshift pagedown pageup period ralt rctrl return return2 rgui rightbracket rshift semicolon separator slash space tab
	ac_back ac_bookmarks ac_forward ac_home ac_refresh ac_search ac_stop again alterase application audiomute audionext audioplay audioprev audiostop brightnessdown brightnessup calculator cancel clear clearagain computer crsel currencysubunit currencyunit cut decimalseparator exsel find grave help kbdillumdown kbdillumtoggle kbdillumup mail mediaselect menu minus mode mute numlockclear oper out paste pause power printscreen prior scrolllock select sleep stop sysreq thousandsseparator undo unknown volumedown volumeup www
	kp_0 kp_00 kp_000 kp_1 kp_2 kp_3 kp_4 kp_5 kp_6 kp_7 kp_8 kp_9 kp_a kp_ampersand kp_at kp_b kp_backspace kp_binary kp_c kp_clear kp_clearentry kp_colon kp_comma kp_d kp_dblampersand kp_dblverticalbar kp_decimal kp_divide kp_e kp_enter kp_equals kp_equalsas400 kp_exclam kp_f kp_greater kp_hash kp_hexadecimal kp_leftbrace kp_leftparen kp_less kp_memadd kp_memclear kp_memdivide kp_memmultiply kp_memrecall kp_memstore kp_memsubtract kp_minus kp_multiply kp_octal kp_percent kp_period kp_plus kp_plusminus kp_power kp_rightbrace kp_rightparen kp_space kp_tab kp_verticalbar kp_xor
	 
	In the case of a mouse input, the code must be "m:" and then one of these:
	Positions    ->  x y dx dy
	Buttons      ->  lb rb mb xb1 xb2
	Scroll wheel ->  scroll:left scroll:right scroll:up scroll:down
	
	For controller inputs, the code must be "c:" and then one of these:
	Buttons  ->  a b x y back guide start lstickb rstickb lshoulder rshoulder
	D-pad    ->  dpad:up dpad:down dpad:left dpad:right
	Triggers ->  ltrigger rtrigger 
	Axes     ->  lstick:left lstick:right lstick:up lstick:down rstick:left rstick:right rstick:up rstick:down
	
	If you're viewing this in the console, sorry it's probably too long to fit the screen. We recommend finding "input_codes" in the manual.txt file instead.


-------------------------------
	maths
- - - - - - - - - - - - - - - -

	Those are the maths functions available in SUGAR.
	For cos, sin and atan2, angles are turn-based, meaning the value 1 indicates a full turn, while 0.25 indicates a quarter turn (90 degrees or pi/2).


cos	a
	Returns the cosine of 'a' as a turn-based angle.

sin	a
	Returns the sine of 'a' as a turn-based angle.

atan2	dx dy
	Returns an angle-based angle from the vector dx, dy.

twv	x
	Returns y coordinate corresponding to x on triangle wave.
		twv(0)    -> -1
		twv(0.25) ->  0
		twv(0.5)  -> +1
		twv(0.75) ->  0
		twv(1)    -> -1

warp	a b [c]
	Returns the circular difference between a and b with the smallest absolute value, considering c as a full circle unit.
	If c isn't set, defaults to 1.
		warp(1,9,10) -> -2

dist	x y [xb yb]
	If xb and yb are set, returns the distance between x, y and xb, yb.
	Otherwise, returns the distance between 0,0 and x,y.

sqrdist	x y [xb yb]
	If xb and yb are set, returns the squared distance between x, y and xb, yb.
	Otherwise, returns the squared distance between 0,0 and x,y.
	This function is faster than dist.

lerp	a b i
	Returns the linear interpolation between a and b at i.
		lerp(2, 6, 0)   -> 2
		lerp(2, 6, 0.5) -> 4
		lerp(2, 6, 1)   -> 6

sqr	a
	Returns a*a.

cub	a
	Returns a*a*a.

pow	a b
	Returns a to the power of b.
	This function is considerably slower than sqr or cub.

sqrt	a
	Returns the square root of a.

flr	a
	Returns the closest integer below or equal to a.

round	a
	Returns the closest integer to a.

ceil	a
	Returns the closest integer above or equal to a.

abs	a
	Returns the absolute (positive) value of a.

sgn	a
	Returns -1 if a is negative, returns 1 if a is positive.

min	a b
	Returns the smaller value between a and b.

max	a b
	Returns the bigger value between a and b.

mid	a b c
	Returns the middle value between a and b and c.
	mid(3,1,2) -> 2 because 1 < 2 < 3

rnd	a
	Returns a random number n where 0 <= n < a.

irnd	a
	Returns a random integer n where 0 <= n < a.

srand	a
	Sets the seed for the random number generation, making it consistent.


-------------------------------
	memory
- - - - - - - - - - - - - - - -

	SUGAR lets you modify the memory that it uses at runtime. This memory is used for surface pixels and font glyphs, which will be visibly affected.
	When creating new surfaces and fonts, you can either tell Sugar where to store them in the memory, or let Sugar automatically find some available space.
	If you do use custom memory addresses, you can have the elements' data overlap, and so their memory will be shared and operations on one may affect the other.
	If you don't use custom addresses, you can see what the automatic addresses are by checking the debug logs.


wipe	[v]
	Wipes memory, filling it with v.
	v should be an integer within the 0 <= v < 256 range.
	v defaults to 0.

write	adr data [halfbytes]
	Writes the string of hexadecimal numbers 'data' to memory at 'adr'.
	'data' should be a continuous string of hexadecimal digits like this: "00019a4f6c88bb". Every pair of digits will define 1 byte in the memory...
	...Unless halfbytes is set to true, in which case every digit will each define 1 byte.

read	adr len [halfbytes]
	Returns a string of hexadecimal digits representing 'len' bytes of the memory at 'adr'.
	Each byte will be represented by a pair of digit, unless 'halfbytes' is set to true. Then each byte will be represented by a single digit, limited to 0-15 values instead of 0-255.

memcpy	dst src len
	Copies the values of 'len' bytes starting at the 'src' address, to the bytes starting at the 'adr' address.

memset	adr len v
	Sets 'len' bytes starting at 'adr' to the value 'v'.

peek	adr
peek2	adr
peek4	adr
	Returns the 8-bit / 16-bit / 32-bit value at 'adr' in the memory.

poke	adr v
poke2	adr v
poke4	adr v
	Sets the 1/2/4 bytes at 'adr' to 'v' as an 8-bit / 16-bit / 32-bit value.