allegro.js  4.2.2

allegro.js File Reference

CONFIGURATION ROUTINES

function install_allegro ()
 Installs allegro. More...
 
function allegro_init ()
 Wrapper for install_allegro.
 
function allegro_init_all (id, w, h, menu, enable_keys)
 Inits Allegro and installs all subsystems. More...
 
function END_OF_MAIN ()
 Macro to be placed after the end of main() Calls main()
 

MOUSE ROUTINES

var mouse_b = 0
 Mouse button bitmask. More...
 
var mouse_pressed = 0
 Same as mouse_b but only checks if a button was pressed last frame Note that this only works inside loop()
 
var mouse_released = 0
 Same as mouse_b but only checks if a button was released last frame Note that this only works inside loop()
 
var mouse_x = -1
 Mouse X position within the canvas.
 
var mouse_y = -1
 Mouse Y position within the canvas.
 
var mouse_z = -1
 Mouse wheel position. More...
 
var mouse_mx = 0
 Mouse mickey, X position since last loop(). More...
 
var mouse_my = 0
 Mouse mickey, Y position since last loop(). More...
 
var mouse_mz = 0
 Mouse mickey, wheel position since last loop(). More...
 
function install_mouse (menu)
 Installs mouse handlers. More...
 
function remove_mouse ()
 Removes mouse handlers.
 
function show_mouse ()
 Enables showing system mouse cursor over canvas.
 
function hide_mouse ()
 Disables system mouse cursor over canvas. More...
 

TIMER ROUTINES

function SECS_TO_TIMER (secs)
 Converts seconds to install_int_ex interval units. More...
 
function MSEC_TO_TIMER (msec)
 Converts milliseconds to install_int_ex interval units. More...
 
function BPS_TO_TIMER (bps)
 Converts beats-per-second to install_int_ex interval units. More...
 
function BPM_TO_TIMER (bpm)
 Converts beats-per-minute to install_int_ex interval units. More...
 
function install_timer ()
 Does nothing.
 
function time ()
 Unix time stamp! Returns number of milliseconds since 1970 started. More...
 
function install_int (procedure, msec)
 Installs interrupt function. More...
 
function install_int_ex (procedure, speed)
 Installs interrupt function. More...
 
function loop (procedure, speed)
 Game loop interrupt Loop is the same as interrupt, except, it cannot be stopped once it's started. More...
 
function loading_bar (progress)
 Default loading bar rendering This function is used by ready() to display a simple loading bar on screen. More...
 
function ready (procedure, bar)
 Installs a handler to check if everything has downloaded. More...
 
function remove_int (procedure)
 Removes interrupt. More...
 
function remove_all_ints ()
 Removes all interrupts.
 

KEYBOARD ROUTINES

var key = []
 Array of flags indicating state of each key. More...
 
var pressed = []
 Array of flags indicating in a key was just pressed since last loop() Note that this will only work inside loop()
 
var released = []
 Array of flags indicating in a key was just released since last loop() Note that this will only work inside loop()
 
function install_keyboard (enable_keys)
 Installs keyboard handlers Unlike mouse, keyboard can be installed before initialising graphics, and the handlers will function over the entire website, as opposed to canvas only. More...
 
function remove_keyboard ()
 Uninstalls keyboard.
 

BITMAP OBJECTS

function BITMAP_OBJECT (w, h, canvas, context, ready, type)
 Bitmap object, This is not a function. More...
 
function create_bitmap (width, height)
 Creates empty bitmap. More...
 
function load_bitmap (filename)
 Loads bitmap from file Loads image from file asynchronously. More...
 
function load_bmp (filename)
 Wrapper for load_bitmap.
 

GRAPHICS MODES

var canvas
 Screen bitmap This is the bitmap object representing the main drawing canvas. More...
 
var SCREEN_W = 0
 Screen bitmap width in pixels.
 
var SCREEN_H = 0
 Screen bitmap height in pixels.
 
var font
 default font
 
function set_gfx_mode (canvas_id, width, height)
 Enables graphics. More...
 

DRAWING PRIMITIVES

var PI = 3.14159265
 Pi.
 
var PI2 = 2*3.14159265
 Pi * 2.
 
var PI_2 = 3.14159265/2
 Pi / 2.
 
var PI_3 = 3.14159265/3
 Pi / 3.
 
var PI_4 = 3.14159265/4
 Pi / 4.
 
function RAD (d)
 Converts degrees to radians. More...
 
function DEG (r)
 Converts radians to degrees. More...
 
function makecol (r, g, b, a)
 Creates a 0xAARRGGBB from values Overdrive is not permitted, so values over 255 (0xff) will get clipped. More...
 
function makecolf (r, g, b, a)
 Creates 0xAARRGGBB from values This is a float version of makecol, where all components should be in 0.0-1.0 range. More...
 
function getr (colour)
 Gets red bits from 0xRRGGBB This one does clip. More...
 
function getg (colour)
 Gets red bits from 0xRRGGBB This one too. More...
 
function getb (colour)
 Gets red bits from 0xRRGGBB This one clips as well. More...
 
function geta (colour)
 Gets alpha bits from 0xAARRGGBB This one doesn't. More...
 
function getrf (colour)
 Float (0.0-1.0) version of getr() More...
 
function getgf (colour)
 Float (0.0-1.0) version of getg() More...
 
function getbf (colour)
 Float (0.0-1.0) version of getb() More...
 
function getaf (colour)
 Float (0.0-1.0) version of geta() More...
 
function getpixel (bitmap, x, y)
 Gets pixel colour from bitmap Reads pixel from bitmap at given coordinates. More...
 
function putpixel (bitmap, x, y, colour)
 Gets pixel colour from bitmap Reads pixel from bitmap at given coordinates. More...
 
function clear_bitmap (bitmap)
 Clears bitmap to transparent black. More...
 
function clear_to_color (bitmap, colour)
 Clears bitmap to specified colour. More...
 
function line (bitmap, x1, y1, x2, y2, colour, width)
 Draws a line. More...
 
function vline (bitmap, x, y1, y2, colour, width)
 Draws a vertical line. More...
 
function hline (bitmap, x1, y, x2, colour, width)
 Draws a horizontal line. More...
 
function triangle (bitmap, x1, y1, x2, y2, x3, y3, colour, width)
 Draws a triangle. More...
 
function trianglefill (bitmap, x1, y1, x2, y2, x3, y3, colour)
 Draws a triangle. More...
 
function polygon (bitmap, vertices, points, colour, width)
 Draws a polygon. More...
 
function polygonfill (bitmap, vertices, points, colour)
 Draws a polygon. More...
 
function rect (bitmap, x1, y1, w, h, colour, width)
 Draws a rectangle. More...
 
function rectfill (bitmap, x1, y1, w, h, colour)
 Draws a rectangle. More...
 
function circle (bitmap, x, y, radius, colour, width)
 Draws a circle. More...
 
function circlefill (bitmap, x, y, radius, colour)
 Draws a circle. More...
 
function arc (bitmap, x, y, ang1, ang2, r, colour, width)
 Draws a arc. More...
 
function arcfill (bitmap, x, y, ang1, ang2, r, colour)
 Draws a arc. More...
 

BLITTING AND SPRITES

function draw_sprite (bmp, sprite, x, y)
 Draws a sprite This is probably the fastest method to get images on screen. More...
 
function scaled_sprite (bmp, sprite, x, y, sx, sy)
 Draws a stretched sprite Draws a sprite stretching it to given width and height. More...
 
function rotate_sprite (bmp, sprite, x, y, angle)
 Draws a rotated sprite Draws a sprite rotating it around its centre point. More...
 
function pivot_sprite (bmp, sprite, x, y, cx, cy, angle)
 Draws a sprite rotated around an arbitrary point Draws a sprite rotating it around a given point. More...
 
function rotate_scaled_sprite (bmp, sprite, x, y, angle, sx, sy)
 Draws a rotated sprite and scales it Draws a sprite rotating it around its centre point. More...
 
function pivot_scaled_sprite (bmp, sprite, x, y, cx, cy, angle, sx, sy)
 Draws a sprite rotated around an arbitrary point and scaled Draws a sprite rotating it around a given point. More...
 
function blit (source, dest, sx, sy, dx, dy, w, h)
 Blit This is how you draw backgrounds and stuff. More...
 
function simple_blit (source, dest, x, y)
 Simple Blit Simplified version of blit, works pretty much like draw_sprite but draws from the corner. More...
 
function stretch_blit (source, dest, sx, sy, sw, sh, dx, dy, dw, dh)
 Scaled blit Draws a scaled chunk of an image on a bitmap. More...
 

TEXT OUTPUT

function FONT_OBJECT (element, file, name, type)
 Font object, this is not a function. More...
 
function load_base64_font (data)
 Loads font from file. More...
 
function load_font (filename)
 Loads font from file. More...
 
function create_font (family)
 Creates a font objects from font-family This creates a font element using an existing font-family name. More...
 
function textout (bitmap, f, s, x, y, size, colour, outline, width)
 Draws text on bitmap. More...
 
function textout_centre (bitmap, f, s, x, y, size, colour, outline, width)
 Draws centred text on bitmap. More...
 
function textout_right (bitmap, f, s, x, y, size, colour, outline, width)
 Draws right-aligned text on bitmap. More...
 

SOUND ROUTINES

function SAMPLE_OBJECT (element, file, volume, ready, type)
 Sample object, this is not a function. More...
 
function install_sound ()
 Install sound. More...
 
function set_volume (volume)
 Sets global volume.
 
function get_volume ()
 Gets global volume.
 
function load_sample (filename)
 Loads a sample from file Loads a sample from file and returns it. More...
 
function destroy_sample (filename)
 Does nothing. More...
 
function play_sample (sample, vol, freq, loop)
 Plays given sample. More...
 
function adjust_sample (sample, vol, freq, loop)
 Adjust sample during playback Adjusts sample data Note how pan is left out, as it doesn't seem to have a js counterpart. More...
 
function stop_sample (sample)
 Stops playing Also resets position. More...
 
function pause_sample (sample)
 Pauses playing Also doesn't reset position. More...
 

HELPER MATH FUNCTIONS

function rand ()
 Returns a random number from 0 to 65535 Result is always integer. More...
 
function rand32 ()
 Returns a random number from -2147483648 to 2147483647 Result is always integer. More...
 
function frand ()
 Returns a random number from 0.0 to 1.0 This one is float. More...
 
function abs (a)
 Returns absolute value of a Removes minus sign from the value, should there be any. More...
 
function length (x, y)
 Returns length of a vector. More...
 
function distance (x1, y1, x2, y2)
 Calculates distance between two points. More...
 
function distance2 (x1, y1, x2, y2)
 Calculates squared distance between two points This version is just a tad faster. More...
 
function linedist (ex1, ey1, ex2, ey2, x, y)
 Distance between a point and a line segment. More...
 
function lerp (from, to, progress)
 Linear interpolation between two values Returns a value midway between from and to specified by progress. More...
 
function dot (x1, y1, x2, y2)
 Returns a dot product of two vectors Dot product is equal to cosine of angle between two vectors times their lengths. More...
 
function sgn (a)
 Returns sign of value Will return -1 if it's negative, 1 if positive and 0 if zero. More...
 
function angle (x1, y1, x2, y2)
 Returns an angle between two vectors. More...
 
function anglediff (a, b)
 Returns a difference between angles. More...
 
function clamp (value, min, max)
 Clamps a value Min doesn't really have to be smaller than max. More...
 
function scale (value, min, max, min2, max2)
 Scales a value from one range to another. More...
 
function scaleclamp (value, min, max, min2, max2)
 Scales value from one range to another and clamps it down. More...
 

DEBUG FUNCTIONS

var ALLEGRO_CONSOLE = false
 Set this to true if you want to debug to browser console. More...
 
function enable_debug (id)
 Enables debugging to a console. More...
 
function log (string)
 Logs to console Only works after enable_debug() has been called. More...
 
function wipe_log ()
 Wipes the debug console Clears the debug element of any text. More...
 

Function Documentation

function abs (   a)

Returns absolute value of a Removes minus sign from the value, should there be any.

Parameters
avalue to be absoluted
Returns
absolute value of a
function adjust_sample (   sample,
  vol,
  freq,
  loop 
)

Adjust sample during playback Adjusts sample data Note how pan is left out, as it doesn't seem to have a js counterpart.

freq will probably not work everywhere too!

Parameters
samplesample
volplayback volume
freqspeed, 1.0 is normal
looploop or not to loop
function allegro_init_all (   id,
  w,
  h,
  menu,
  enable_keys 
)

Inits Allegro and installs all subsystems.

Calls install_allegro(), install_mouse(), install_timer(), install_keyboard(), install_sound() and set_gfx_mode() with provided parameters

Parameters
iddrawing canvas id
wscreen width in pixels
hscreen height in pixels
menuset this to true to enable context menu
function angle (   x1,
  y1,
  x2,
  y2 
)

Returns an angle between two vectors.

Parameters
x1,y1vector one
x2,y2vector two
Returns
angle in degrees, snapped to 0-360
function anglediff (   a,
  b 
)

Returns a difference between angles.

Parameters
a,b,angles
Returns
angle difference, in -180 to 180 range
function arc (   bitmap,
  x,
  y,
  ang1,
  ang2,
  r,
  colour,
  width 
)

Draws a arc.

Draws a circle at specified centre point and radius. The arc is not filled

Parameters
bitmapto be drawn to
x,ycentre point coordinates
ang1,ang2angles to draw the arc between measured anticlockwise from the positive x axis in degrees
rradius
colourcolour in 0xAARRGGBB format
widthline width
function arcfill (   bitmap,
  x,
  y,
  ang1,
  ang2,
  r,
  colour 
)

Draws a arc.

Draws a circle at specified centre point and radius. The arc is filled

Parameters
bitmapto be drawn to
x,ycentre point coordinates
ang1,ang2angles to draw the arc between measured anticlockwise from the positive x axis in degrees
rradius
colourcolour in 0xAARRGGBB format
function BITMAP_OBJECT (   w,
  h,
  canvas,
  context,
  ready,
  type 
)

Bitmap object, This is not a function.

This is not a function, it's the structure of bitmap object returned from load_bitmap() and create_bitmap(). For every bitmap laoded or created, a canvas element is created. Loaded images are then drawn onto the canvas, so that you can easily manipulate images and everything is consistent. You can also load a single file two times and modify it differently for each instance.

Parameters
wbitmap width
hbitmap height
canvasunderlying canvas element, used to draw the bitmap onto stuff
contextcanvas' rendering context, used to draw stuff onto this bitmap
readyflags whether loading of the bitmap is complete
typeobject type, "bmp" in this case
function blit (   source,
  dest,
  sx,
  sy,
  dx,
  dy,
  w,
  h 
)

Blit This is how you draw backgrounds and stuff.

masked_ versions are omitted, since everything is 32-bit RGBA anyways. The source and dest parameters are swapped compared to draw_sprite for historical, 20 year old reasons that must stay the same no matter what.

Parameters
sourcesource bitmap
destdestination bitmap
sx,sysource origin
dx,dytop-left bitmap corner coordinates in target bitmap
w,hblit size
Todo:

make rotated versions of this

tell everyone that blitting to itself is slower than the other thing (requires copy?)

function BPM_TO_TIMER (   bpm)

Converts beats-per-minute to install_int_ex interval units.

Parameters
bpmnumber of beats per minute
Returns
value converted to milliseconds
function BPS_TO_TIMER (   bps)

Converts beats-per-second to install_int_ex interval units.

Parameters
bpsnumber of beats per second
Returns
value converted to milliseconds
function circle (   bitmap,
  x,
  y,
  radius,
  colour,
  width 
)

Draws a circle.

Draws a circle at specified centre point and radius. The circle is not filled

Parameters
bitmapto be drawn to
x,ycentre point coordinates
rcircle radius
colourcolour in 0xAARRGGBB format
widthline width
function circlefill (   bitmap,
  x,
  y,
  radius,
  colour 
)

Draws a circle.

Draws a circle at specified centre point and radius. The circle is filled

Parameters
bitmapto be drawn to
x,ycentre point coordinates
rcircle radius
colourcolour in 0xAARRGGBB format
function clamp (   value,
  min,
  max 
)

Clamps a value Min doesn't really have to be smaller than max.

Parameters
valuevalue to be clamped
min,maxvalues to clam between
Returns
clamped value
function clear_bitmap (   bitmap)

Clears bitmap to transparent black.

Fills the entire bitmap with 0 value, which represents transparent black.

Parameters
bitmapbitmap to be cleared
function clear_to_color (   bitmap,
  colour 
)

Clears bitmap to specified colour.

Fills the entire bitmap with colour value.

Parameters
bitmapbitmap to be cleared
colourcolour in 0xAARRGGBB format
function create_bitmap (   width,
  height 
)

Creates empty bitmap.

Creates a bitmap object of given dimensions and returns it.

Parameters
widthbitmap width
heightbitmap height
Returns
bitmap object
function create_font (   family)

Creates a font objects from font-family This creates a font element using an existing font-family name.

Parameters
familyfont-family property, can be 'serif', 'sans-serif' or anything else that works
Returns
font object
function DEG (   r)

Converts radians to degrees.

Also, changes anticlockwise to clockwise.

Parameters
rvalue in radians to be converted
Returns
-r*180.0f/PI
function destroy_sample (   filename)

Does nothing.

Todo:
: something that happens here
function distance (   x1,
  y1,
  x2,
  y2 
)

Calculates distance between two points.

Parameters
x1,x2first point
x2,y2second point
Returns
distance between the points
function distance2 (   x1,
  y1,
  x2,
  y2 
)

Calculates squared distance between two points This version is just a tad faster.

Parameters
x1,x2first point
x2,y2second point
Returns
distance between the points
function dot (   x1,
  y1,
  x2,
  y2 
)

Returns a dot product of two vectors Dot product is equal to cosine of angle between two vectors times their lengths.

With normalised, length 1.0, vectors, the value would be 1.0 if vectors are the same, 0.0 if they are perpendicular, and -1.0 if they point the opposite direction. It helps to determine angle differences.

Parameters
x1,y1vector one, won't be normalised
x2,y2vector two, won't be normalised
Returns
dot product of the vectors
function draw_sprite (   bmp,
  sprite,
  x,
  y 
)

Draws a sprite This is probably the fastest method to get images on screen.

The image will be centered. Opposed to traditional allegro approach, sprite is drawn centered.

Parameters
bmptarget bitmap
spritesprite bitmap
x,ycoordinates of the top left corder of the image center
function enable_debug (   id)

Enables debugging to a console.

'console' can be any html element that can accept text, preferably a

Parameters
idid of the element to be the console
function FONT_OBJECT (   element,
  file,
  name,
  type 
)

Font object, this is not a function.

This is not a function but a reference entry for font object returned by load_font() and create_cont().

Parameters
element<style> element containing the font-face declaration. Not available for create_font() fonts and default font object.
filefont file name, empty string for default font and create_font() typefaces.
namefont-family name
typeobject type, "fnt" in this case
function frand ( )

Returns a random number from 0.0 to 1.0 This one is float.

Use multiply (*) operator to get higher values. i.e. frand()*10 will return a value from 0.0 to 10.0

Returns
a random floating point value from 0.0 to 1.0
function geta (   colour)

Gets alpha bits from 0xAARRGGBB This one doesn't.

Parameters
colourcolour in 0xAARRGGBB format
Returns
alpha component in 0-255 range
function getaf (   colour)

Float (0.0-1.0) version of geta()

Parameters
colourcolour in 0xAARRGGBB format
Returns
alpha component in 0.0-1.0 range
function getb (   colour)

Gets red bits from 0xRRGGBB This one clips as well.

Parameters
colourcolour in 0xAARRGGBB format
Returns
blue component in 0-255 range
function getbf (   colour)

Float (0.0-1.0) version of getb()

Parameters
colourcolour in 0xAARRGGBB format
Returns
blue component in 0.0-1.0 range
function getg (   colour)

Gets red bits from 0xRRGGBB This one too.

Parameters
colourcolour in 0xAARRGGBB format
Returns
green component in 0-255 range
function getgf (   colour)

Float (0.0-1.0) version of getg()

Parameters
colourcolour in 0xAARRGGBB format
Returns
green component in 0.0-1.0 range
function getpixel (   bitmap,
  x,
  y 
)

Gets pixel colour from bitmap Reads pixel from bitmap at given coordinates.

This is probably super slow, and shouldn't be used inside loops.

Parameters
bitmapbitmap object to poll
xx coordinate of pixel
yy coordinate of pixel
Returns
colour in 0xAARRGGBB format
function getr (   colour)

Gets red bits from 0xRRGGBB This one does clip.

Parameters
colourcolour in 0xAARRGGBB format
Returns
red component in 0-255 range
function getrf (   colour)

Float (0.0-1.0) version of getr()

Parameters
colourcolour in 0xAARRGGBB format
Returns
red component in 0.0-1.0 range
function hide_mouse ( )

Disables system mouse cursor over canvas.

Use this if you would like to provide your own cursor bitmap

function hline (   bitmap,
  x1,
  y,
  x2,
  colour,
  width 
)

Draws a horizontal line.

Draws a horizontal line from one point to another using given colour. Probably slightly faster than line() method, since this one uses rectfill() to draw the line.

Parameters
bitmapto be drawn to
yrow to draw the line to
x1,x2line endpoints
colourcolour in 0xAARRGGBB format
widthline width (defaults to 1)
function install_allegro ( )

Installs allegro.

This function must be called before anything else. It makes sure Date.now() exists.

function install_int (   procedure,
  msec 
)

Installs interrupt function.

Installs a user timer handler, with the speed given as the number of milliseconds between ticks. This is the same thing as install_int_ex(proc, MSEC_TO_TIMER(speed)). Calling again this routine with the same timer handler as parameter allows you to adjust its speed.

Parameters
procedurefunction to be called
speedexecution interval in msec
function install_int_ex (   procedure,
  speed 
)

Installs interrupt function.

With this one, you must use helper functions to set the interval in the second argument. The lowest interval is 1 msec, but you probably don't want to go below 17 msec. Suggested values are BPS_TO_TIMER(30) or BPS_TO_TIMER(60). It cannot be used to alter previously installed interrupt function as well.

  • SECS_TO_TIMER(secs) - seconds
  • MSEC_TO_TIMER(msec) - milliseconds (1/1000th)
  • BPS_TO_TIMER(bps) - beats per second
  • BPM_TO_TIMER(bpm) - beats per minute
    Parameters
    procedurefunction to be called
    speedexecution interval
function install_keyboard (   enable_keys)

Installs keyboard handlers Unlike mouse, keyboard can be installed before initialising graphics, and the handlers will function over the entire website, as opposed to canvas only.

After this call, the key[] array can be used to check state of each key. All keys will have their default action disabled, unless specified in the enable_keys array. This means that i.e. backspace won't go back, arrows won't scroll. By default, function keys (KEY_F1..KEY_F12) are the only ones not suppressed

Parameters
enable_keysarray of keys that are not going to have their default action prevented, i.e. [KEY_F5] will enable reloading the website. By default, if this is omitted, function keys are the only ones on the list.
function install_mouse (   menu)

Installs mouse handlers.

Must be called after set_gfx_mode() to be able to determine mouse position within the given canvas!

Parameters
menuIf true, context menu will be available on right click on canvas. Default is false.
function install_sound ( )

Install sound.

Todo:
: stuff here? AudioContext? compatibility first!
function length (   x,
  y 
)

Returns length of a vector.

Parameters
x,yvector coordinates
Returns
length of the vector
function lerp (   from,
  to,
  progress 
)

Linear interpolation between two values Returns a value midway between from and to specified by progress.

Parameters
fromnumber to lerp from
tonumber to lerp to
progressamount of lerp
Returns
lerped value
function line (   bitmap,
  x1,
  y1,
  x2,
  y2,
  colour,
  width 
)

Draws a line.

Draws a line from one point to another using given colour.

Parameters
bitmapto be drawn to
x1,y1start point coordinates
x2,y2end point coordinates
colourcolour in 0xAARRGGBB format
widthline width
function linedist (   ex1,
  ey1,
  ex2,
  ey2,
  x,
  y 
)

Distance between a point and a line segment.

Parameters
ex1,ey1first end of line segment
ex2,ey2second end of line segment
x,ypoint coordinates
Returns
distance of point x,y from line ex1,ey1-ex2,ey2
function load_base64_font (   data)

Loads font from file.

This actually creates a style element, puts code inside and appends it to class. I heard it works all the time most of the time. AS ready() won't wait for fonts to load, this will allow you to have a font straight away with base64 data. Data should be WOFF converted to base64 without line breaks.

Parameters
database64 string of a WOFF file
Returns
font object
function load_bitmap (   filename)

Loads bitmap from file Loads image from file asynchronously.

This means that the execution won't stall for the image, and it's data won't be accessible right off the start. You can check for bitmap object's 'ready' member to see if it has loaded, but you probably should avoid stalling execution for that, as JS doesn't really like that.

Parameters
filenameURL of image
Returns
bitmap object, or -1 on error
function load_font (   filename)

Loads font from file.

This actually creates a style element, puts code inside and appends it to class. I heard it works all the time most of the time. Note that this function won't make ready() wait, as it's not possible to consistently tell if a font has been loaded in js, thus load your fonts first thing, and everything should be fine.

Parameters
filenameFont file URL
Returns
font object
function load_sample (   filename)

Loads a sample from file Loads a sample from file and returns it.

Doesn't stall for loading, use ready() to make sure your samples are loaded! Note that big files, such as music jingles, will most probably get streamed instead of being fully loaded into memory, meta data should be accessible tho.

Parameters
filenamename of the audio file
Returns
sample object
function loading_bar (   progress)

Default loading bar rendering This function is used by ready() to display a simple loading bar on screen.

You need to manually specify a dummy function if you don't want loading screen.

Parameters
progressloading progress in 0.0 - 1.0 range
function log (   string)

Logs to console Only works after enable_debug() has been called.

Will append
newline tag. You can use html inside your logs too.

Parameters
stringtext to log
function loop (   procedure,
  speed 
)

Game loop interrupt Loop is the same as interrupt, except, it cannot be stopped once it's started.

It's meant for game loop. remove_int() and remove_all_ints() have no effect on this. Since JS can't have blocking (continuously executing) code and realise on events and timers, you cannot have your game loop inside a while or for argument. Instead, you should use this to create your game loop to be called at given interval. There should only be one loop() function! Note that mouse mickeys (mouse_mx, etc.), and pressed indicators (pressed[] and mouse_pressed) will only work inside loop()

Parameters
procedurefunction to be looped, preferably inline, but let's not talk coding styles here
speedspeed in the same format as install_int_ex()
function makecol (   r,
  g,
  b,
  a 
)

Creates a 0xAARRGGBB from values Overdrive is not permitted, so values over 255 (0xff) will get clipped.

Parameters
rred component in 0-255 range
ggreen component in 0-255 range
bblue component in 0-255 range
aalpha component in 0-255 range, defaults to 255 (fully opaque)
Returns
colour in 0xAARRGGBB format
function makecolf (   r,
  g,
  b,
  a 
)

Creates 0xAARRGGBB from values This is a float version of makecol, where all components should be in 0.0-1.0 range.

Parameters
rred component in 0.0-1.0 range
ggreen component in 0.0-1.0 range
bblue component in 0.0-1.0 range
aalpha component in 0.0-1.0 range, defaults to 1.0 (fully opaque)
Returns
colour in 0xAARRGGBB format
function MSEC_TO_TIMER (   msec)

Converts milliseconds to install_int_ex interval units.

Parameters
msecnumber of milliseconds
Returns
value converted to milliseconds
function pause_sample (   sample)

Pauses playing Also doesn't reset position.

Use play_sample() to resume.

Parameters
samplesample to be stopped
function pivot_scaled_sprite (   bmp,
  sprite,
  x,
  y,
  cx,
  cy,
  angle,
  sx,
  sy 
)

Draws a sprite rotated around an arbitrary point and scaled Draws a sprite rotating it around a given point.

The sprite is also scaled. Sprite is drawn centered to the pivot point. The pivot point is relative to top-left corner of the image before scaling. You can omit sy value for uniform scaling. You can use negative scale for flipping.

Parameters
bmptarget bitmap
spritesprite bitmap
x,ytarget coordinates of the pivot point
cx,cypivot point coordinates
angleangle of rotation in degrees
sxhorizontal scale , 1.0 is unscaled
syvertical scale (defaults to sx)
function pivot_sprite (   bmp,
  sprite,
  x,
  y,
  cx,
  cy,
  angle 
)

Draws a sprite rotated around an arbitrary point Draws a sprite rotating it around a given point.

Sprite is drawn centered to the pivot point. The pivot point is relative to top-left corner of the image.

Parameters
bmptarget bitmap
spritesprite bitmap
x,ytarget coordinates of the pivot point
cx,cypivot point coordinates
angleangle of rotation in degrees
function play_sample (   sample,
  vol,
  freq,
  loop 
)

Plays given sample.

Plays a sample object using given values. Note how pan is left out, as it doesn't seem to have a js counterpart. Freq will probably not work everywhere too!

Parameters
samplesample to be played
volplayback volume
freqspeed, 1.0 is normal
looploop or not to loop
function polygon (   bitmap,
  vertices,
  points,
  colour,
  width 
)

Draws a polygon.

Draws a polygon using three coordinates. The polygon is not filled.

Parameters
bitmapto be drawn to
verticesnumber of vertices to draw
pointsarray containing vertices*2 elements of polygon coordinates in [x1,y1,x2,y2,x3...] format
colourcolour in 0xAARRGGBB format
widthline width
function polygonfill (   bitmap,
  vertices,
  points,
  colour 
)

Draws a polygon.

Draws a polygon using three coordinates. The polygon is filled.

Parameters
bitmapto be drawn to
verticesnumber of vertices to draw
pointsarray containing vertices*2 elements of polygon coordinates in [x1,y1,x2,y2,x3...] format
colourcolour in 0xAARRGGBB format
function putpixel (   bitmap,
  x,
  y,
  colour 
)

Gets pixel colour from bitmap Reads pixel from bitmap at given coordinates.

This is probably super slow, and shouldn't be used inside loops.

Parameters
bitmapbitmap object to update
xx coordinate of pixel
yy coordinate of pixel
colourcolour in 0xAARRGGBB format
function RAD (   d)

Converts degrees to radians.

Also, changes clockwise to anticlockwise.

Parameters
dvalue in degrees to be converted
Returns
-d*PI/180.0f
function rand ( )

Returns a random number from 0 to 65535 Result is always integer.

Use modulo (%) operator to create smaller values i.e. rand()%256 will return a random number from 0 to 255 inclusive.

Returns
a random number in 0-65535 inclusive range
function rand32 ( )

Returns a random number from -2147483648 to 2147483647 Result is always integer.

Use abs() if you only want positive values.

Returns
a random number in -2147483648-2147483648 inclusive range
function ready (   procedure,
  bar 
)

Installs a handler to check if everything has downloaded.

You should always wrap your loop() function around it, unless there is nothing external you need. load_bitmap() and load_sample() all require some time to process and the execution cannot be stalled for that, so all code you wrap in this hander will only get executed after everything has loaded making sure you can access bitmap properties and data and play samples right away. Note that load_font() does not affect ready(), so you should always load your fonts first.

Parameters
procedurefunction to be called when everything has loaded.
barloading bar callback function, if omitted, equals to loading_bar() and renders a simple loading bar. it must accept one parameter, that is loading progress in 0.0-1.0 range.
function rect (   bitmap,
  x1,
  y1,
  w,
  h,
  colour,
  width 
)

Draws a rectangle.

Draws a rectangle from one point to another using given colour. The rectangle is not filled. Opposed to traditional allegro approach, width and height have to be provided, not an end point.

Parameters
bitmapto be drawn to
x1,y1start point coordinates
w,hwidth and height
colourcolour in 0xAARRGGBB format
widthline width
function rectfill (   bitmap,
  x1,
  y1,
  w,
  h,
  colour 
)

Draws a rectangle.

Draws a rectangle from one point to another using given colour. The rectangle is filled. Opposed to traditional allegro approach, width and height have to be provided, not an end point.

Parameters
bitmapto be drawn to
x1,y1start point coordinates
w,hwidth and height
colourcolour in 0xAARRGGBB format
function remove_int (   procedure)

Removes interrupt.

Parameters
procedureinterrupt procedure to be removed
function rotate_scaled_sprite (   bmp,
  sprite,
  x,
  y,
  angle,
  sx,
  sy 
)

Draws a rotated sprite and scales it Draws a sprite rotating it around its centre point.

The sprite is also scaled. You can omit sy value for uniform scaling. YOu can use negative scale for flipping. Scaling is around the center. The sprite will be centred and rotated around its centre.

Parameters
bmptarget bitmap
spritesprite bitmap
x,ycoordinates of the centre of the image
angleangle of rotation in degrees
sxhorizontal scale, 1.0 is unscaled
syvertical scale (defaults to sx)
function rotate_sprite (   bmp,
  sprite,
  x,
  y,
  angle 
)

Draws a rotated sprite Draws a sprite rotating it around its centre point.

The sprite will be centred and rotated around its centre.

Parameters
bmptarget bitmap
spritesprite bitmap
x,ycoordinates of the centre of the image
angleangle of rotation in degrees
function SAMPLE_OBJECT (   element,
  file,
  volume,
  ready,
  type 
)

Sample object, this is not a function.

This is not a function. This is a sample object structure returned by load_sample().

Parameters
elementHTML <audio> element containing the sound properties
filesample file name
volumesample volume, this is combined with global volume
readyloaded indicator flag
typeobject type, "snd" in this case
function scale (   value,
  min,
  max,
  min2,
  max2 
)

Scales a value from one range to another.

Parameters
valuevalue to be scaled
min,maxbounds to scale from
min2,max2bounds to scale to
Returns
scaled value
function scaleclamp (   value,
  min,
  max,
  min2,
  max2 
)

Scales value from one range to another and clamps it down.

Parameters
valuevalue to be scaled
min,maxbounds to scale from
min2,max2bounds to scale and clamp to
Returns
scaled and clamped value
function scaled_sprite (   bmp,
  sprite,
  x,
  y,
  sx,
  sy 
)

Draws a stretched sprite Draws a sprite stretching it to given width and height.

The sprite will be centered. You can omit sy value for uniform scaling. YOu can use negative scale for flipping. Scaling is around the center.

Parameters
bmptarget bitmap
spritesprite bitmap
x,ycoordinates of the top left corder of the image
sxhorizontal scale , 1.0 is unscaled
syvertical scale (defaults to sx)
function SECS_TO_TIMER (   secs)

Converts seconds to install_int_ex interval units.

Parameters
secsnumber of seconds
Returns
value converted to milliseconds
function set_gfx_mode (   canvas_id,
  width,
  height 
)

Enables graphics.

This function should be before calling any other graphics routines. It selects the canvas element for rendering and sets the resolution. It also loads the default font.

Parameters
canvas_idid attribute of canvas to be used for drawing.
widthcanvas width in pixels
heightcanvas height in pixels
Returns
0 on success or -1 on error
function sgn (   a)

Returns sign of value Will return -1 if it's negative, 1 if positive and 0 if zero.

Parameters
avalue
Returns
sign of a
function simple_blit (   source,
  dest,
  x,
  y 
)

Simple Blit Simplified version of blit, works pretty much like draw_sprite but draws from the corner.

Parameters
sourcesource bitmap
destdestination bitmap
x,ytop-left bitmap corner coordinates in target bitmap
Todo:

make rotated versions of this

tell everyone that blitting to itself is slower than the other thing (requires copy?)

function stop_sample (   sample)

Stops playing Also resets position.

Parameters
samplesample to be stopped
function stretch_blit (   source,
  dest,
  sx,
  sy,
  sw,
  sh,
  dx,
  dy,
  dw,
  dh 
)

Scaled blit Draws a scaled chunk of an image on a bitmap.

It's not slower.

Parameters
sourcesource bitmap
destdestination bitmap
sx,sysource origin
sw,shsource dimensions
dx,dytop-left bitmap corner coordinates in target bitmap
dw,dhdestination dimensions
function textout (   bitmap,
  f,
  s,
  x,
  y,
  size,
  colour,
  outline,
  width 
)

Draws text on bitmap.

This draws text using given font, size and colour. You can also specify outline, or make it -1 to disable outline.

Parameters
bitmaptarget bitmap
ffont object
stext string
x,wposition of the text
sizefont size in pixels, this not always reflects the actual glyph dimensions
colourtext colour
outlineoutline colour, or omit for no outline
widthoutline width
function textout_centre (   bitmap,
  f,
  s,
  x,
  y,
  size,
  colour,
  outline,
  width 
)

Draws centred text on bitmap.

This draws centred text using given font, size and colour. You can also specify outline, or make it -1 to disable outline.

Parameters
bitmaptarget bitmap
ffont object
stext string
x,wposition of the text
sizefont size in pixels, this not always reflects the actual glyph dimensions
colourtext colour
outlineoutline colour, or omit for no outline
widthoutline width
function textout_right (   bitmap,
  f,
  s,
  x,
  y,
  size,
  colour,
  outline,
  width 
)

Draws right-aligned text on bitmap.

This draws right-aligned text using given font, size and colour. You can also specify outline, or make it -1 to disable outline.

Parameters
bitmaptarget bitmap
ffont object
stext string
x,wposition of the text
sizefont size in pixels, this not always reflects the actual glyph dimensions
colourtext colour
outlineoutline colour, or omit for no outline
widthoutline width
function time ( )

Unix time stamp! Returns number of milliseconds since 1970 started.

function triangle (   bitmap,
  x1,
  y1,
  x2,
  y2,
  x3,
  y3,
  colour,
  width 
)

Draws a triangle.

Draws a triangle using three coordinates. The triangle is not filled.

Parameters
bitmapto be drawn to
x1,y1first point coordinates
x2,y2second point coordinates
x3,y3third point coordinates
colourcolour in 0xAARRGGBB format
widthline width
function trianglefill (   bitmap,
  x1,
  y1,
  x2,
  y2,
  x3,
  y3,
  colour 
)

Draws a triangle.

Draws a triangle using three coordinates. The triangle is filled.

Parameters
bitmapto be drawn to
x1,y1first point coordinates
x2,y2second point coordinates
x3,y3third point coordinates
colourcolour in 0xAARRGGBB format
function vline (   bitmap,
  x,
  y1,
  y2,
  colour,
  width 
)

Draws a vertical line.

Draws a vertical line from one point to another using given colour. Probably slightly faster than line() method, since this one uses rectfill() to draw the line.

Parameters
bitmapto be drawn to
xcolumn to draw the line to
y1,y2line endpoints
colourcolour in 0xAARRGGBB format
widthline width (defaults to 1)
function wipe_log ( )

Wipes the debug console Clears the debug element of any text.

Useful if you want to track changing values in real time without clogging the browser. Just call it at the beginning every loop()!

Variable Documentation

var ALLEGRO_CONSOLE = false

Set this to true if you want to debug to browser console.

Setting this will make log() log to browser debugger console using console.log().

var canvas

Screen bitmap This is the bitmap object representing the main drawing canvas.

Drawing anything on the screen bitmap displays it.

var key = []

Array of flags indicating state of each key.

Available keyboard scan codes are as follows:

  • KEY_A ... KEY_Z,
  • KEY_0 ... KEY_9,
  • KEY_0_PAD ... KEY_9_PAD,
  • KEY_F1 ... KEY_F12,
  • KEY_ESC, KEY_TILDE, KEY_MINUS, KEY_EQUALS, KEY_BACKSPACE, KEY_TAB, KEY_OPENBRACE, KEY_CLOSEBRACE, KEY_ENTER, KEY_COLON, KEY_QUOTE, KEY_BACKSLASH, KEY_COMMA, KEY_STOP, KEY_SLASH, KEY_SPACE,
  • KEY_INSERT, KEY_DEL, KEY_HOME, KEY_END, KEY_PGUP, KEY_PGDN, KEY_LEFT, KEY_RIGHT, KEY_UP, KEY_DOWN,
  • KEY_SLASH_PAD, KEY_ASTERISK, KEY_MINUS_PAD, KEY_PLUS_PAD, KEY_DEL_PAD, KEY_ENTER_PAD,
  • KEY_PRTSCR, KEY_PAUSE,
  • KEY_LSHIFT, KEY_RSHIFT, KEY_LCONTROL, KEY_RCONTROL, KEY_ALT, KEY_ALTGR, KEY_LWIN, KEY_RWIN, KEY_MENU, KEY_SCRLOCK, KEY_NUMLOCK, KEY_CAPSLOCK
  • KEY_EQUALS_PAD, KEY_BACKQUOTE, KEY_SEMICOLON, KEY_COMMAND
var mouse_b = 0

Mouse button bitmask.

Each bit in the mask represents a separate mouse button state. If right mouse button is down, mouse_b value would be 4, 00100 in binary. Each bit represents one mouse button. use something like if (mouse_b&1) to check for separate buttons.

  • Button 0 is LMB. (mouse_b&1)
  • Button 1 is MMB / wheel. (mouse_b&2)
  • Button 2 is RMB. (mouse_b&4)
var mouse_mx = 0

Mouse mickey, X position since last loop().

Only works inside loop()

var mouse_my = 0

Mouse mickey, Y position since last loop().

Only works inside loop()

var mouse_mz = 0

Mouse mickey, wheel position since last loop().

Only works inside loop()

var mouse_z = -1

Mouse wheel position.

This might not work consistently across all browsers!