API Reference¶

Callbacks¶

drystal.init()¶

This function is called after script loading, before the first frame. You may want to load your assets from here but you can load them before if you prefer.

1 2 3 4 5

print '1' function drystal.init() print '3' end print '2'

drystal.update(dt: float)¶

This functions is called at each frame. The dt parameter represents the time elapsed since the last update (in seconds). Use this function to update the game state.

drystal.draw()¶

This function is called after the drystal.update() function.

drystal.atexit()¶

This function is called when the window is closed or when drystal.stop() is called.

drystal.prereload()¶

Called before the game is reloaded (by drystal.reload(), by pressing F3 or with livereloading). You can use it to save the current state of the game inside a global variable, so it will still be accessible after the reload.

drystal.postreload()¶

Called after the game was reloaded. You can use it to restore the state of the game.

Callbacks¶

To receive events, you have to defined some of the following functions.

drystal.mouse_motion(x, y, dx, dy)¶

Called when the mouse is moved. dx and dy are difference between the current position and the last one.

drystal.mouse_press(x, y, button: integer)¶

Called when a button (or mouse wheel) is pressed.

Parameters:	x (int) – X coordinate of the mouse when the button was pressed y (int) – Y coordinate of the mouse when the button was pressed button (int) – drystal.buttons.left (= 1), drystal.buttons.right (= 2), drystal.buttons.middle (= 3), drystal.buttons.wheel_up (= 4), or drystal.buttons.wheel_down (= 5).

drystal.mouse_release(x, y, button: integer)¶

Called when a button (or mouse wheel) is released.

Param:	button is the same as in drystal.mouse_press().

drystal.key_press(key)¶

Called when a key is pressed. Depending on key repeat system configuration of the player, drystal.key_press() can be called multiple times even if the user did not released the key. drystal.key_release() will be called too.

drystal.key_release(key)¶

Same as drystal.key_press() but when a key is released.

drystal.key_text(unicode_key)¶

Called when a key is pressed, unicode_key is the character generated by the key and the current modifiers. For example, if shift and d are pressed, drystal.key_text() will be called with the parameter ‘D’.

drystal.page_resize(w, h)¶

Called when the browser page is resized. Use this callback to resize the canvas in the fullscreen mode (see drystal.set_fullscreen()).

Param:	see inner window width and height

Window¶

drystal.screen¶

drystal.screen is the surface representing the window/canvas, which will be blit after execution of the drystal.draw() callback.

drystal.current_draw_on¶

Surface:draw_on()

drystal.current_draw_from¶

Surface:draw_from()

drystal.resize(width: integer, height: integer)¶

Resizes the window (or the canvas in the browser) to the specified dimensions.

Note

Unlike some engines, you can resize the window without having to recreate your surfaces or shaders.

1 2 3

drystal.resize(200, 300) assert(drystal.screen.w == 200) assert(drystal.screen.h == 300)

drystal.set_fullscreen(fullscreen: boolean)¶

Enables or disables the fullscreen mode.

Note

It will make the game fits the whole page in a browser and not use the true fullscreen mode. We choose this behavior because the escape key will not be available anymore and it makes less sense to play a game in fullscreen with a browser. You also need to ensure that there is no border or margin for the canvas in your index.html.

html,body {
    margin: 0;
    padding: 0;
    width: 100%;
    height: 100%;
    overflow: hidden;
}

Note

When the browser is resized, the canvas is not resized. Call drystal.set_fullscreen(true) from the callback drystal.page_resize() to update it.

drystal.set_title(title: str)¶

Changes the title of the window. In the browser, the title of the document is changed.

drystal.show_cursor(show: boolean)¶

Decides if the mouse cursor should be hidden or not.

Surface¶

class drystal.Surface¶

Object representing a surface. Surfaces can be drawn on other surfaces (screen included).

w¶

Width of the surface.

h¶

Height of the surface.

draw_on() → Surface¶

Use this surface as destination/backbuffer (draw method be redirected to this surface instead of screen) for future draws.

Returns:	the old surface which was used

draw_from() → Surface¶

Use this surface as source for future textured draws (like drystal.draw_sprite()).

Returns:	the old surface which was used

set_filter(filter)¶

Parameters:	filter – drystal.filters.nearest, drystal.filters.linear (= drystal.filters.default), drystal.filters.bilinear or drystal.filters.trilinear.

Warning

A surface is limited to 2048x2048 pixels. We follow the WebGL Stats and we use the highest texture size at 100%.

get_pixel(x, y) → r, g, b, a¶

Returns red/green/blue/alpha components at given pixel position. Top-left is at (1, 1) and bottom-right is at (surface.w, surface.h) included.

drystal.new_surface(width, height)¶

Creates a new surface of dimensions (width, height). By default, the surface is transparent.

1 2 3 4 5 6

local surf = drystal.new_surface(200, 200) surf:draw_on() -- the following draw function will act on this surface drystal.set_color('white') drystal.draw_circle(surf.w / 2, surf.h / 2, 100) -- draw a white circle inside the surface drystal.screen:draw_on() ...

drystal.load_surface(filename)¶

Loads a surface from a file. If the file does not exist or is invalid, drystal.load_surface() returns (nil, error).

Note

Use assert(drystal.load_surface 'test.png') to make sure the surface is loaded.

Drawing primitives¶

drystal.set_color(red: float [0-255], green: float [0-255], blue: float [0-255])¶

Sets current color used by draw_* functions.

drystal.set_color(color: table)

Sets current color used by draw_* functions. color should contains 3 values at keys 1, 2 and 3. For example, {128, 128, 128} represents gray.

drystal.set_color(color: string)

Sets current color used by draw_* functions. color should be either a color name from the colors table or a ‘#rgb’ or ‘#rrggbb’ CSS-like string.

drystal.set_alpha(alpha: float [0-255])¶

Sets the current alpha used by draw_* functions.

drystal.draw_background()¶

Clears the current current_draw_on surface.

drystal.draw_point(x, y, size)¶

Draws a point at the given coordinate and with given size.

drystal.draw_point_tex(sourcex, sourcey, x, y, size)¶

Draws a textured point at the given coordinate and with given size. The point will be textured with the surface bound to current_draw_from, starting from sourcex, sourcey to sourcex+64, sourcey+64.

drystal.draw_line(x1, y1, x2, y2, width=1: float)¶

Draws a line between the two given points.

drystal.draw_triangle(x1, y1, x2, y2, x3, y3)¶

Draws a filled triangle between the three given points.

drystal.draw_surface(ix1, iy1, ix2, iy2, ix3, iy3, ox1, oy1, ox2, oy2, ox3, oy3)¶

Draws a surface (set as current_draw_from). The first 6 parameters represent a triangle in the source texture, the last 6 represent the destination triangle. They can have different sizes to create deformations.

Tinting is possible by using drystal.set_color() (255, 255, 255 for no modification).

drystal.draw_quad(ix1, iy1, ix2, iy2, ix3, iy3, ix4, iy4, ox1, oy1, ox2, oy2, ox3, oy3, ox4, oy4)¶

Same as drystal.draw_surface() but with quadrilaterals instead of triangles.

drystal.draw_rect(x, y, w, h)¶

Draws a filled rectangle.

drystal.draw_rect_rotated(x, y, w, h, angle: float)¶

Draws a filled rotated rectangle.

drystal.draw_square(x, y, w, h, width)¶

Draws a non-filled rectangle.

drystal.draw_circle(x, y, radius: float)¶

Draws a circle. The coordinate is the position of the center. radius is expressed in pixel.

Note

This function draws a lot of triangles. If possible, include a circle in your spritesheet and draw it with drystal.draw_sprite().

drystal.draw_polygon(x1, y1, x2, y2, ...)¶

Draws a filled polygon.

drystal.draw_polyline(loop, width, x1, y1, x2, y2, ...)¶

Draws a non-filled polygon.

drystal.draw_image(x, y, w, h, destx, desty[, destw=w[, desth=h]])¶

Draws an image. It can be resized if destw or desth are different than w and h

drystal.draw_sprite(sprite: table, x, y[, transform: table])¶

Draws a sprite, from the current Surface:draw_from() surface.

Use Sprite for easier sprite drawing.

Parameters:	sprite (table) – must have the fields: x, y, w and h transform (table) – must have the fields: angle, wfactor and hfactor

1 2 3 4 5 6 7 8 9 10

local sprite = { -- the first image of a 32x32 spritesheet x = 0, y = 0, w = 32, h = 32, } function drystal.draw() ... drystal.draw_sprite(sprite, 200, 300) end

drystal.draw_sprite_simple(sprite: table, x, y)¶

drystal.draw_sprite_rotated(sprite: table, x, y, angle: float)¶

drystal.draw_sprite_resized(sprite: table, x, y, w, h)¶

Blending¶

drystal.set_blend_mode(blend_mode)¶

Sets the current blend mode.

Parameters:	blend_mode – drystal.blends.alpha (= drystal.blends.default), drystal.blends.add or drystal.blends.mult.

Camera¶

The camera can be used the modify position and size of the following draws.

drystal.camera.x(=0)¶

Position of the camera (x coordinate).

drystal.camera.y(=0)¶

Position of the camera (y coordinate).

drystal.camera.zoom(=1)¶

Zoom of the camera. Values greater than 1 mean zoom in, less than 1 mean zoom out.

drystal.camera.angle(=0)¶

Angle of the camera. You can easily apply a tilt effect with this field.

drystal.camera.reset()¶

Resets the camera fields to default values.

drystal.camera.push()¶

Saves the current camera state. You can then restore it with drystal.camera.pop().

drystal.camera.pop()¶

Restores the camera to the previous state.

drystal.screen2scene(x: float, y: float) → float, float¶

Computes the position of screen coordinates (x, y) to scene/camera coordinates.

Buffer¶

A buffer can only contain one type of shape (point, textured point, line, triangle, textured triangle).

class drystal.Buffer¶

use()¶

Use this buffer as current buffer.

draw([dx=0: float[, dy=0: float]])¶

Draw this buffer. dx and dy can be used to offset the draw.

reset()¶

Removes all elements from the buffer.

upload_and_free()¶

Sends the buffer to the graphic card and free memory. If a buffer is freed, you cannot call Buffer:reset(), Buffer:use() or Buffer.upload_and_free() anymore or errors will be thrown.

drystal.new_buffer([initial_size: integer]) → Buffer¶

Creates a buffer of the specified initial_size. Once the buffer is full, it is resized.

drystal.use_default_buffer()¶

Tells drystal to use the default buffer.

Shader¶

class drystal.Shader¶

use()¶

Use this shader for the following draws.

feed(uniform: str, value: float)¶

drystal.new_shader([vertex: str[, fragment_color: str[, fragment_texture: str]]]) → Shader¶

Creates a shader with code specified. If one of the code is nil, code of the default shader is used.

drystal.use_default_shader()¶

Tells drystal to use the default shader.

Colors¶

class drystal.Color¶

rgb() → r, g, b¶

Gets the RGB values of the color. You can also use .r, .g and .b.

hsl() → h, s, l¶

Gets the HSL values of the color. You can also use .h, .s and .l.

cmyk() → c, m, y, k¶

Gets the CMYK values of the color. You can also use .c, .m, .y and .k.

add(color) → Color¶

Creates a new Color which is the combination of the two colors using the CMYK subtractive color model.

Note

You can also use the + operator.

sub(color) → Color¶

Creates a new Color which is the substraction of the two colors using the CMYK subtractive color model.

Note

You can also use the - operator.

mul(color) → Color¶

Creates a new Color which is the multiplication of the two colors.

Note

You can also use the * operator.

darker() → Color¶

Creates a darker color.

lighter() → Color¶

Creates a lighter color.

drystal.new_color(table) → Color¶

Creates a color with the RGB color model.

Parameters:	table (table) – must contains the three components: r, g and b.

drystal.new_color('rgb', r, g, b) → Color

Creates a color with the RGB color model.

drystal.new_color('hsl', h, s, l) → Color

Creates a color with the HSL color model.

drystal.new_color('cmyk', c, m, y, k) → Color

Creates a color with the CMYK color model.

drystal.colors¶

This table contains all of the W3C colors. You can also create colors from the #rgb or #rrggbb syntax by indexing this table, like so: drystal.colors['#F0F'].

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

local drystal = require 'drystal'
local color = drystal.colors.green
function drystal.init()
       drystal.resize(600, 400)
       print('press d or l or m or a')
end

function drystal.draw()
       drystal.set_color(color)
       drystal.draw_background()
end

function drystal.key_press(key)
       if key == 'd' then
              color = color:darker()
       end
       if key == 'l' then
              color = color:lighter()
       end
       if key == 'm' then
              color = color * drystal.colors.steelblue
       end
       if key == 'a' then
              color = color + drystal.colors.red
       end
end

Sprite¶

class drystal.Sprite¶

source¶

Source table of the sprite. It must contain x, y, w and h fields.

color(={255, 255, 255})¶

Tint of the sprite.

alpha(=255)¶

Alpha of the sprite.

x, y

Coordinates on the screen (or any destination surface).

w, h

Width and height of the sprite. If this is different than values from source, the sprite will be resized.

angle(=0)¶

Rotation of the sprite.

draw()¶

Draws the sprite on the current draw on surface. You have to set the correct sprite sheet as draw from surface before use this function.

drystal.new_sprite(source: table[, x=0, y=0[, w=source.w, h=source.h]]) → Sprite¶

Creates a sprite.

Parameters:	source (table) – must contain the following fields: x, y : coordinates where the sprite is located in the draw_from image w, h : size of the sprite in the draw_from image

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

local surface = assert(drystal.load_surface('spritesheet.png'))
local source = { x=0, y=0, w=32, h=32 }
local sprite = drystal.new_sprite(source, 350, 200)
sprite.update=function(self, dt)   -- custom field
   self.angle = self.angle + dt * math.pi * 2
end
function drystal.update(dt)
    sprite:update(dt)
end
function drystal.draw()
    ... -- draw background, etc
    surface:draw_from()
    sprite:draw()
end

Shape¶

class drystal.Shape¶

set_density(density: float)¶

Sets the density of the shape.

get_density() → float¶

Returns the density of the shape.

set_restitution(restitution float)¶

Sets the restitution of the shape.

get_restitution() → float¶

Returns the restitution of the shape.

set_friction(friction float)¶

Sets the friction of the shape.

get_friction() → float¶

Returns the friction of the shape.

set_sensor(sensor: boolean)¶

If sensor is true, the shape will not collide but the on_collision callback will be called.

Body¶

class drystal.Body¶

set_position(x: float, y: float)¶

Sets the position of the body.

get_position() → float, float¶

Returns the position of the body.

set_angle(angle: float)¶

Sets the angle of the body.

get_angle() → float¶

Returns the angle of the body.

set_linear_velocity(x: float, y: float)¶

Sets the linear velocity of the body.

get_linear_velocity() → float, float¶

Returns the linear velocity of the body.

set_angular_velocity(x: float, y: float)¶

Sets the angular velocity of the body.

get_angular_velocity() → float, float¶

Returns the angular velocity of the body.

set_linear_damping(damping: float)¶

Sets the linear damping of the body.

get_linear_damping() → float¶

Returns the linear damping of the body.

set_angular_damping(damping: float)¶

Sets the angular damping of the body.

get_angular_damping() → float¶

Returns the angular damping of the body.

set_fixed_rotation(fixed: boolean)¶

Fixes the rotation of the body.

get_fixed_rotation() → boolean¶

Returns true if the body has fixed rotation.

set_active(active: boolean)¶

Enables or disables a body.

set_bullet(bullet: boolean)¶

Marks the body as a fast moving object.

get_mass() → float¶

Returns the mass of the body.

set_mass_center(x, y)¶

Sets the mass center.

apply_force(x, y[, x, y])¶

Applies a force (by default, x, y are the body’s center).

apply_linear_impulse(x, y)¶

Applies a linear impulse (by default, x, y are the body’s center).

apply_angular_impulse(angle)¶

Applies a angular impulse.

apply_torque(torque)¶

Applies a torque.

dump()¶

Prints Box2D attributes of the body.

destroy()¶

Destroys the body.

Warning

Once the body is destroy, you cannot call any of its functions anymore. Make sure to remove references (my_body = nil).

Warning

Associated joints are destroyed too. Calling functions on those joints will throw an error, make sure to remove references (my_joint = nil).

MouseJoint¶

class drystal.MouseJoint¶

set_target(x, y)¶

Sets the target position of the joint.

destroy()¶

Destroys the joint.

RopeJoint¶

class drystal.RopeJoint¶

set_max_length(max_length: float)¶

Sets the maximum length of the joint

destroy()¶

Destroys the joint.

DistanceJoint¶

class drystal.DistanceJoint¶

set_length(length: float)¶

Sets the length of the joint

set_frequency(frequency: float)¶

Sets the frequency of the joint.

destroy()¶

Destroys the joint.

RevoluteJoint¶

class drystal.RevoluteJoint¶

set_angle_limits(min, max)¶

Sets the angle limits of the joint. If min equals max, limits are disabled.

set_motor_speed(speed: float[, maxtorque=20: float])¶

Set the motor speed. If speed is 0, motor is disabled.

destroy()¶

Destroys the joint.

PrismaticJoint¶

class drystal.PrismaticJoint¶

set_motor_speed(speed: float)¶

Sets the motor speed.

set_max_motor_force(force: float)¶

Sets the maximum motor force.

set_enable_motor(enable: boolean)¶

Enables or disables the motor.

set_enable_limit(enable: boolean)¶

Enables or disables the limit.

is_limit_enabled() → boolean¶

Returns true if the joint has limit.

is_motor_enabled() → boolean¶

Returns true if the motor is enabled.

destroy()¶

Destroys the joint.

Music¶

class drystal.Music¶

Musics are for large audio files, mainly for ambiance musics during the game.

play([loop=false: bool[, onend_callback: function]])¶

Plays the music (from the beginning). If loop is true, the music will loop forever. onend_callback is called when the music finishes (and is not called by :stop()).

set_pitch(pitch: float)¶

Sets the pitch of the music. pitch must be > 0.

set_volume(volume: float)¶

Sets the volume of the music. volume must be >= 0.

pause()¶

Pauses the music.

stop()¶

Stops the music.

drystal.load_music(filename: str) -> Music | (nil, error)¶

Loads a music from a file.

Warning

Only the Ogg format is available.

drystal.load_music(callback: function[, samplesrate=44100: integer]) -> Music | (nil, error)

Loads a music according to a callback function generating the music.

drystal.set_music_volume(volume: float [0-1])¶

Sets the global music volume.

Sound¶

class drystal.Sound¶

Sounds are for short audio files like special effects (e.g. a jump, a shot fired or an explosion).

They are loaded directly into memory. So if you want to play longer audio files it is recommended to use Music objects which stream the music instead of playing it directly.

play([volume=1[, x=0[, y=0[, pitch=1]]])¶

Plays the sound at given volume, position and pitch.

Parameters:	volume (float) – between 0 and 1 x (float) – between -1 and 1 (-1 is full left, 1 is full right) y (float) – between -1 and 1 pitch (float) – greater than 0

drystal.load_sound(filename: str) -> Sound | (nil, error)¶

Loads a sound from a file. It has to be in WAV format. Only 44100Hz, 8 bits or 16 bits are supported. If you want to use positional audio, it has to be mono audio.

drystal.load_sound(callback: function, numsamples: integer) -> Sound | (nil, error)

Loads a sound according to a callback function generating the sound.

drystal.load_sound(data: table) -> Sound | (nil, error)

drystal.set_sound_volume(volume: float [0-1])¶

Sets the global sound volume.