Bolt Plugin API Reference ¶

clear ¶

Deletes any previous contents of the surface and sets it to contain a single colour and alpha.

Takes up to four parameters in the range 0.0 - 1.0. All parameters to this function are optional (apart from the surface itself). If none are provided, the surface will be fully transparent. Otherwise, if alpha is not provided, it will be assumed to be 1.0.

Note that if an alpha value less than 1 is provided, the partially-transparent colour will still fully replace the old contents, rather than blending with them.

mysurface:clear() -- transparent
mysurface:clear(1, 0, 0) -- opaque red
mysurface:clear(1, 0, 0, 0.5) -- partially transparent red

subimage ¶

Updates a rectangular section of this surface with the given RGBA pixel data. The parameters are X, Y, width and height, in pixels, followed by the RGBA data. The data can be either a string or a Buffer.

There are four bytes in an RGBA pixel, so the number of bytes in the data is expected to be 4 * width * height. If fewer bytes than that are provided, the data will be padded with zeroes. If too many bytes are provided, the excess data will be unused. The data will be interpreted in row-major order with the first pixel being in the top-left.

Note that non-opqaue pixels will fully replace the old contents of the surface, rather than blending with them.

The following example sets the top-left pixel of a surface to a fully opaque green colour:

mysurface:subimage(0, 0, 1, 1, "\x00\x00\xFF\xFF")

drawtoscreen ¶

Draws a section of the surface directly onto the screen. Parameters are source X,Y,W,H followed by destination X,Y,W,H, all in pixels. Any transparency will be blended additively and, if the size of the source and destination rectangles is different, the image will be scaled smoothly.

mysurface:drawtoscreen(0, 0, 800, 608, 0, 0, 800, 608)

drawtosurface ¶

Draws a section of the surface onto a section of another surface. Parameters are target surface, then source X,Y,W,H, then destination X,Y,W,H, all in pixels. Any transparency will be blended additively and, if the size of the source and destination rectangles is different, the image will be scaled smoothly.

mysurface:drawtosurface(myothersurface, 0, 0, 100, 100, 0, 0, 1920, 1080)

drawtogameview ¶

Draws a section of the surface onto a section of the game view. Can only be called during a rendergameview event, as the event object needs to be passed to this function. Parameters are target surface, then source X,Y,W,H, then destination X,Y,W,H, all in pixels. Any transparency will be blended additively and, if the size of the source and destination rectangles is different, the image will be scaled smoothly.

bolt.onrendergameview(function (event)
  mysurface:drawtogameview(event, 0, 0, 100, 100, 0, 0, 100, 100)
end)

drawtowindow ¶

Draws a section of the surface onto a section of a Window. Parameters are target window, then source X,Y,W,H, then destination X,Y,W,H, all in pixels. Any transparency will be blended additively and, if the size of the source and destination rectangles is different, the image will be scaled smoothly.

mysurface:drawtowindow(mywindow, 0, 0, 100, 100, 0, 0, 1920, 1080)

settint ¶

Sets the "tint" this surface will be drawn with when drawing it to the screen or to another surface. These values are in the range [0.0 - 1.0] and are multiplied with the red, green and blue channels of the image, so values less than 1.0 will darken the image. The defaults are all 1.0.

mysurface:settint(red, green, blue)

setalpha ¶

Sets the alpha transparency this surface will be drawn with when drawing it to the screen or to another surface. The value is in the range [0.0 - 1.0] where 0.0 is invisible and 1.0 is fully opaque. The default is 1.0.

mysurface:setalpha(0.5)

getint8 ¶

Reads a single byte from the buffer at the given offset and returns it as a signed integer. See Buffer for more on the buffer API.

local num = mybuffer:getint8(myoffset)

getint16 ¶

Reads a two-byte value from the buffer at the given offset and returns it as a signed integer. See Buffer for more on the buffer API.

local num = mybuffer:getint16(myoffset)

getint32 ¶

Reads a four-byte value from the buffer at the given offset and returns it as a signed integer. See Buffer for more on the buffer API.

local num = mybuffer:getint32(myoffset)

getint64 ¶

Reads an eight-byte value from the buffer at the given offset and returns it as a signed integer. See Buffer for more on the buffer API.

local num = mybuffer:getint64(myoffset)

getuint8 ¶

Reads a single byte from the buffer at the given offset and returns it as an unsigned integer. See Buffer for more on the buffer API.

local num = mybuffer:getuint8(myoffset)

getuint16 ¶

Reads a two-byte value from the buffer at the given offset and returns it as an unsigned integer. See Buffer for more on the buffer API.

local num = mybuffer:getuint16(myoffset)

getuint32 ¶

Reads a four-byte value from the buffer at the given offset and returns it as an unsigned integer. See Buffer for more on the buffer API.

local num = mybuffer:getuint32(myoffset)

getuint64 ¶

Reads an eight-byte value from the buffer at the given offset and returns it as an unsigned integer. See Buffer for more on the buffer API.

local num = mybuffer:getuint64(myoffset)

getfloat32 ¶

Reads a four-byte IEEE floating point value from the given offset and returns it as a number. See Buffer for more on the buffer API.

local num = mybuffer:getfloat32(myoffset)

getfloat64 ¶

Reads an eight-byte IEEE floating point value from the given offset and returns it as a number. See Buffer for more on the buffer API.

local num = mybuffer:getfloat64(myoffset)

setint8 ¶

Writes a single byte into the buffer at the given offset. See Buffer for more on the buffer API.

mybuffer:setint8(myoffset, myvalue)

setint16 ¶

Writes a two-byte value into the buffer at the given offset. See Buffer for more on the buffer API.

mybuffer:setint16(myoffset, myvalue)

setint32 ¶

Writes a four-byte value into the buffer at the given offset. See Buffer for more on the buffer API.

mybuffer:setint32(myoffset, myvalue)

setint64 ¶

Writes an eight-byte value into the buffer at the given offset. See Buffer for more on the buffer API.

mybuffer:setint64(myoffset, myvalue)

setuint8 ¶

Writes a single unsigned byte into the buffer at the given offset. See Buffer for more on the buffer API.

mybuffer:setuint8(myoffset, myvalue)

setuint16 ¶

Writes a two-byte unsigned value into the buffer at the given offset. See Buffer for more on the buffer API.

mybuffer:setuint16(myoffset, myvalue)

setuint32 ¶

Writes a four-byte unsigned value into the buffer at the given offset. See Buffer for more on the buffer API.

mybuffer:setuint32(myoffset, myvalue)

setuint64 ¶

Writes an eight-byte unsigned value into the buffer at the given offset. See Buffer for more on the buffer API.

mybuffer:setuint64(myoffset, myvalue)

setfloat32 ¶

Writes a number into the buffer at the given offset, as a four-byte IEEE floating-point value. See Buffer for more on the buffer API.

mybuffer:setfloat32(myoffset, myvalue)

setfloat64 ¶

Writes a number into the buffer at the given offset, as an eight-byte IEEE floating-point value. See Buffer for more on the buffer API.

mybuffer:setfloat64(myoffset, myvalue)

setstring ¶

Writes a string into the buffer at the given offset. The entire string will be copied. See Buffer for more on the buffer API.

mybuffer:setstring(myoffset, mystring)

setbuffer ¶

Writes the contents of another buffer into this buffer at the given offset. The entire contents of the source buffer will be copied. See Buffer for more on the buffer API.

mybuffer:setstring(myoffset, mystring)

close ¶

Closes and destroys the window. This is the only way for a window to be destroyed, other than the plugin stopping, which will destroy the window automatically.

Do not use the window again after calling this function on it. No more events will be received (although it is safe to call this from inside an event handler.)

mywindow:close()

id ¶

Returns an integer which uniquely identifies this window. No other object will ever have this ID during this instance of the game process, even if this plugin is stopped and started again.

local id = mywindow:id()

clear ¶

Deletes any previous contents of the window and sets it to contain a single colour and alpha. See surface:clear.

subimage ¶

Updates a rectangular subsection of this window with the given RGBA pixel data. See surface:subimage.

startreposition ¶

Starts repositioning for this window. This function changes how the user’s "drag" action is processed, and would usually be called from the onmousebutton callback for the left mouse button. Repositioning will occur until the user releases the left mouse button or until the repositioning is cancelled. In the first case, an onreposition event will be fired (even if the size and position din’t actually change.) During repositioning, all mouse events will be handled internally by the window, without calling its event handlers. The window will not actually change size or position until repositioning ends by the user releasing the mouse button.

This function takes two integer parameters. The first should be negative if the window’s left edge is being dragged, positive if the right edge is being dragged, or zero if neither. The second should be negative if the window’s top edge is being dragged, positive if the bottom edge is being dragged, or zero if neither. If both parameterss are zero then the window will be moved instead of resized.

The following example would cause the window to be dragged by its top-right edge:

mywindow:startreposition(1, -1)

cancelreposition ¶

Cancels repositioning for this window. The window’s position and size will not change and an onreposition event will not be sent.

mywindow:cancelreposition()

xywh ¶

Returns the x, y, width and height of this window.

local x, y, w, h = mywindow:xywh()

onreposition ¶

Sets an event handler for this window for reposition events. The function will overwrite any previous event handler, or, if it’s not a function, then any previous event handler will be deleted. See Reposition Event for documentation on this event object.

mywindow:onreposition(function (event)
  -- ...
end)

It’s not safe to use an event object after the event handler has returned.

onmousemotion ¶

Sets an event handler for this window for mouse motion events. The function will overwrite any previous event handler, or, if it’s not a function, then any previous event handler will be deleted. See Mouse Motion Event for documentation on this event object.

mywindow:onmousemotion(function (event)
  -- ...
end)

It’s not safe to use an event object after the event handler has returned.

onmousebutton ¶

Sets an event handler for this window for mouse button events. The function will overwrite any previous event handler, or, if it’s not a function, then any previous event handler will be deleted. See Mouse Button Event for documentation on this event object.

This handler runs immediately after a button is pressed down. When the button is released, onmousebuttonup will run.

mywindow:onmousebutton(function (event)
  -- ...
end)

It’s not safe to use an event object after the event handler has returned.

onmousebuttonup ¶

Sets an event handler for this window for mouse button-up events. The function will overwrite any previous event handler, or, if it’s not a function, then any previous event handler will be deleted. See Mouse Button Event for documentation on this event object.

This handler runs immediately after a button is released. It shares the same type of event object as onmousebutton. If the user clicks the window and drags their mouse outside the window, the mouse motion events and button-up will still usually be captured by the window.

mywindow:onmousebuttonup(function (event)
  -- ...
end)

It’s not safe to use an event object after the event handler has returned.

onscroll ¶

Sets an event handler for this window for mouse scroll events. The function will overwrite any previous event handler, or, if it’s not a function, then any previous event handler will be deleted. See Scroll Event for documentation on this event object.

mywindow:onscroll(function (event)
  -- ...
end)

It’s not safe to use an event object after the event handler has returned.

onmouseleave ¶

Sets an event handler for this window for mouse leave events. The function will overwrite any previous event handler, or, if it’s not a function, then any previous event handler will be deleted. See Mouse Leave Event for documentation on this event object.

mywindow:onmouseleave(function (event)
  -- ...
end)

It’s not safe to use an event object after the event handler has returned.

close ¶

Closes and destroys the browser. This is the only way for a browser to be destroyed, other than the plugin stopping, which will destroy the browser automatically.

Do not use the browser again after calling this function on it. No more events will be received (although it is safe to call this from inside an event handler.)

mybrowser:close()

sendmessage ¶

Sends a message to the browser. The data can be either a string or a Buffer. It will be sent to the browser using the postMessage function, so to handle it in your browser application, just add an event listener for "message" to the window object. The event’s data will be an object with "type": "pluginMessage", and "content" will be an ArrayBuffer containing the Lua string that was passed to this function. Note that the binary data will be transferred exactly as it appeared in Lua, byte-for-byte - it will not be decoded or re-encoded in any way.

If this function is called immediately after creating the browser, it’s possible the message may arrive at the JavaScript process before the page has actually loaded. In this case, Bolt will queue the message until after the loading is complete. It’s therefore safe to assume plugin messages will never arrive before the ’DOMContentLoaded’ event.

mybrowser:sendmessage("some message contents")

enablecapture ¶

Enables screen capture for this browser. The screen contents will be sent to the browser using the postMessage function. The event’s data will be an object with "type": "screenCapture", "width" and "height" will be integers indicating the size of the captured area, and "content" will be an ArrayBuffer of length width * height * 3. The contents will be three bytes per pixel, in RGB format, in row-major order, starting with the bottom-left pixel.

The data will be sent using a shared memory mapping, so the overhead is much lower than it would be to send all the data using sendmessage. However, downloading screen contents from the GPU will still slow the game down (takes around 2 to 5 milliseconds depending on window size), so Bolt will limit itself to capturing 4 frames per second via this function.

mybrowser:enablecapture()

disablecapture ¶

Disables screen capture for this browser. See enablecapture.

mybrowser:disablecapture()

showdevtools ¶

Opens a chromium devtools window for this browser. If one is already open, it will be focused instead of opening a new one. The devtools window can’t be closed through code, it can only be closed by a user action (e.g. clicking the ’X’) or by the browser itself closing.

oncloserequest ¶

Sets an event handler for this browser for close-request events. The function will overwrite any previous event handler, or, if it’s not a function, then any previous event handler will be deleted. Unlike most event handlers, this one is called with no parameters.

Bolt takes no default action other than calling this function, which means nothing will happen by default when the user tries to close the browser. To enable normal closing behaviour, add a closerequest handler which calls mybrowser:close():

mybrowser:oncloserequest(function ()
  mybrowser:close()
end)

onmessage ¶

Sets an event handler for this browser for message events. The function will overwrite any previous event handler, or, if it’s not a function, then any previous event handler will be deleted. The function will be called with a string as the only parameter. The string will contain the binary data that was sent in the browser’s POST message.

mybrowser:onmessage(function (message)
  print(string.format("message received: %s", message))
end)

Note that this example assumes that the message is safely formattable text. This may or may not be the case, depending on what your browser’s web page is programmed to send.

close ¶

Closes and destroys the browser. This is the only way for a browser to be destroyed, other than the plugin stopping, which will destroy the browser automatically.

Do not use the browser again after calling this function on it. No more events will be received (although it is safe to call this from inside an event handler.)

mybrowser:close()

sendmessage ¶

Sends a message to the browser. See browser:sendmessage.

startreposition ¶

Starts repositioning for this browser. See window:startreposition.

cancelreposition ¶

Cancels repositioning for this browser. See window:cancelreposition.

xywh ¶

Returns the new x, y, width and height for this browser. See window:xywh.

enablecapture ¶

Enables screen capture for this browser. See browser:enablecapture.

disablecapture ¶

Disables screen capture for this browser. See browser:enablecapture.

showdevtools ¶

Opens a chromium devtools window for this browser. If one is already open, it will be focused instead of opening a new one. The devtools window can’t be closed through code, it can only be closed by a user action (e.g. clicking the ’X’) or by the browser itself closing.

oncloserequest ¶

Sets an event handler for this browser for close-request events. The function will overwrite any previous event handler, or, if it’s not a function, then any previous event handler will be deleted. Unlike most event handlers, this one is called with no parameters.

Bolt takes no default action other than calling this function, which means nothing will happen by default when the user tries to close the browser. To enable normal closing behaviour, add a closerequest handler which calls myembeddedbrowser:close():

myembeddedbrowser:oncloserequest(function ()
  myembeddedbrowser:close()
end)

onmessage ¶

Sets an event handler for this browser for message events. The function will overwrite any previous event handler, or, if it’s not a function, then any previous event handler will be deleted. The function will be called with a string as the only parameter. The string will contain the binary data that was sent in the browser’s POST message.

myembeddedbrowser:onmessage(function (message)
  print(string.format("message received: %s", message))
end)

Note that this example assumes that the message is safely formattable text. This may or may not be the case, depending on what your browser’s web page is programmed to send.

onreposition ¶

Sets an event handler for this browser for reposition events. The function will overwrite any previous event handler, or, if it’s not a function, then any previous event handler will be deleted. See Reposition Event for documentation on this event object.

The appropriate JavaScript events will also be sent internally to the browser; plugins don’t need to handle this event from Lua in order to implement any browser functionality.

mybrowser:onreposition(function (event)
  -- ...
end)

It’s not safe to use an event object after the event handler has returned.

onmousemotion ¶

Sets an event handler for this embeddedbrowser for mouse motion events. The function will overwrite any previous event handler, or, if it’s not a function, then any previous event handler will be deleted. See Mouse Motion Event for documentation on this event object.

The appropriate JavaScript events will also be sent internally to the browser; plugins don’t need to handle this event from Lua in order to implement any browser functionality.

mybrowser:onmousemotion(function (event)
  -- ...
end)

It’s not safe to use an event object after the event handler has returned.

onmousebutton ¶

Sets an event handler for this browser for mouse button events. The function will overwrite any previous event handler, or, if it’s not a function, then any previous event handler will be deleted. See Mouse Button Event for documentation on this event object.

The appropriate JavaScript events will also be sent internally to the browser; plugins don’t need to handle this event from Lua in order to implement any browser functionality.

This handler runs immediately after a button is pressed down. When the button is released, onmousebuttonup will run.

mybrowser:onmousebutton(function (event)
  -- ...
end)

It’s not safe to use an event object after the event handler has returned.

onmousebuttonup ¶

Sets an event handler for this browser for mouse button-up events. The function will overwrite any previous event handler, or, if it’s not a function, then any previous event handler will be deleted. See Mouse Button Event for documentation on this event object.

The appropriate JavaScript events will also be sent internally to the browser; plugins don’t need to handle this event from Lua in order to implement any browser functionality.

This handler runs immediately after a button is released. It shares the same type of event object as onmousebutton. If the user clicks the window and drags their mouse outside the window, the mouse motion events and button-up will still usually be captured by the window.

mybrowser:onmousebuttonup(function (event)
  -- ...
end)

It’s not safe to use an event object after the event handler has returned.

onscroll ¶

Sets an event handler for this browser for mouse scroll events. The function will overwrite any previous event handler, or, if it’s not a function, then any previous event handler will be deleted. See Scroll Event for documentation on this event object.

The appropriate JavaScript events will also be sent internally to the browser; plugins don’t need to handle this event from Lua in order to implement any browser functionality.

mybrowser:onscroll(function (event)
  -- ...
end)

It’s not safe to use an event object after the event handler has returned.

onmouseleave ¶

Sets an event handler for this browser for mouse leave events. The function will overwrite any previous event handler, or, if it’s not a function, then any previous event handler will be deleted. See Mouse Leave Event for documentation on this event object.

The appropriate JavaScript events will also be sent internally to the browser; plugins don’t need to handle this event from Lua in order to implement any browser functionality.

mybrowser:onmouseleave(function (event)
  -- ...
end)

It’s not safe to use an event object after the event handler has returned.

transform ¶

Transforms this Point by a Transform object and returns a new Point. The original Point object is not modified.

get ¶

Returns the X, Y and Z values for this point.

toscreen ¶

Transforms the X component of this point from the range [-1.0, 1.0] to the range [0, screen_width], and the Y component from the range [-1.0, 1.0] to the range [0, screen_height]. This will give the actual pixel position of a point in the game view, taking the relative position of the game view itself into account. The Z component, depth, is returned unmodified.

This is useful for a point that has been transformed from world space using a viewproj matrix (or a separate view and projection matrix). For any other point, the results will likely not be meaningful.

Points whose depth values are outside the range [-1.0, 1.0] are probably behind the camera and should be ignored.

local xpixel, ypixel, depth = mypoint:toscreen()
if depth >= -1.0 and depth <= 1.0 then
  -- pixel coordinates are valid, do something with them
end

Functionally, the only difference between this function and togameview is that this adds game_view_x to X and game_view_y to Y before returning them. In other words, togameview() is relative to the game view whereas toscreen() is relative to the overall window, bearing in mind that the game view won’t necessarily fill the whole window depending on the player’s HUD layout.

togameview ¶

Transforms the X component of this point from the range [-1.0, 1.0] to the range [0, gameview_width], and the Y component from the range [-1.0, 1.0] to the range [0, gameview_height]. This will give the actual pixel position of a point in the game view. The Z component, depth, is returned unmodified.

This is useful for a point that has been transformed from world space using a viewproj matrix (or a separate view and projection matrix). For any other point, the results will likely not be meaningful.

Points whose depth values are outside the range [-1.0, 1.0] are probably behind the camera and should be ignored.

local xpixel, ypixel, depth = mypoint:togameview()
if depth >= -1.0 and depth <= 1.0 then
  -- pixel coordinates are valid, do something with them
end

Functionally, the only difference between this function and toscreen is that toscreen() adds gameview_x to X and gameview_y to Y before returning them, while this function doesn’t. In other words, togameview() is relative to the game view whereas toscreen() is relative to the overall window, bearing in mind that the game view won’t necessarily fill the whole window depending on the player’s HUD layout.

aspixels ¶

Deprecated, alias for toscreen

decompose ¶

Decomposes the transform into the following nine constituent values, in this order: X, Y, Z, in model coordinates; scale factor X, Y and Z; yaw, pitch, roll, in radians.

Matrix decomposition is an experimental feature. It assumes the right-most column of the matrix to be (0, 0, 0, 1). That will always be the case in transforms returned by vertexanimation, which is the primary intended use of this function.

local x, y, z, xscale, yscale, zscale, yaw, pitch, roll = mytransform:decompose()

get ¶

Returns the 16 floating-point values that make up this transformation matrix, in row-major order.

local m1,  m2,  m3,  m4,
      m5,  m6,  m7,  m8,
      m9,  m10, m11, m12,
      m13, m14, m15, m16 = mytransform:get()

setattribute ¶

Sets a shader attribute. This function is somewhat analogous to glVertexAttribPointer, but not exactly the same. Firstly, this function permanently enables attribute n for the given program, and it’s an error to call this more than once for the same attribute index for the same program. Secondly, the actual vertex data isn’t needed for this call, and is instead passed as a Shader Buffer to the draw function. This means that, unlike glVertexAttribPointer, this API requires all vertex data to be contained in a single shader buffer.

This function requires seven parameters, as follows:

1. the attribute number
2. byte-size of each number in the input data, typically 1, 2, 4 or 8
3. "is_signed", a boolean indicating whether the input numbers are signed (true) or unsigned (false)
4. "is_float", a boolean indicating whether the input numbers are floats (true) or integers (false)
5. the number of numbers per attribute, e.g. 3 for a vec3 attribute
6. byte offset of the first attribute in the input data
7. stride, in bytes, between each attribute in the input data

Valid byte sizes for floats are 2, 4 and 8, and valid byte sizes for integers are 1, 2, or 4. An invalid byte size will cause this function to call error(). It will also call error() if is_signed is false and is_float is true.

-- enable attribute 0 to read float32 values, three per attribute,
-- beginning at byte 0 of the buffer and stepping forward by 12 bytes per attribute
myprogram:setattribute(0, 4, true, false, 3, 0, 12)

setuniform1i ¶

Sets one integer as a uniform value. The first param is the "location" specified in GLSL and the second is the value. This value will be permanently associated with this location for this program, until it’s overwritten by another setuniform call.

myprogram:setuniform1i(location, myinteger)

setuniform2i ¶

Sets two integers as a uniform value. The first param is the "location" specified in GLSL and the rest are the values. These values will be permanently associated with this location for this program, until it’s overwritten by another setuniform call.

myprogram:setuniform2i(location, myint1, myint2)

setuniform3i ¶

Sets three integers as a uniform value. The first param is the "location" specified in GLSL and the rest are the values. These values will be permanently associated with this location for this program, until it’s overwritten by another setuniform call.

myprogram:setuniform3i(location, myint1, myint2, myint3)

setuniform4i ¶

Sets four integers as a uniform value. The first param is the "location" specified in GLSL and the rest are the values. These values will be permanently associated with this location for this program, until it’s overwritten by another setuniform call.

myprogram:setuniform4i(location, myint1, myint2, myint3, myint4)

setuniform1f ¶

Sets one float as a uniform value. The first param is the "location" specified in GLSL and the second is the value. This value will be permanently associated with this location for this program, until it’s overwritten by another setuniform call.

myprogram:setuniform1f(location, mynumber)

setuniform2f ¶

Sets two floats as a uniform value. The first param is the "location" specified in GLSL and the rest are the values. These values will be permanently associated with this location for this program, until it’s overwritten by another setuniform call.

myprogram:setuniform2f(location, mynum1, mynum2)

setuniform3f ¶

Sets three floats as a uniform value. The first param is the "location" specified in GLSL and the rest are the values. These values will be permanently associated with this location for this program, until it’s overwritten by another setuniform call.

myprogram:setuniform3f(location, mynum1, mynum2, mynum3)

setuniform4f ¶

Sets four floats as a uniform value. The first param is the "location" specified in GLSL and the rest are the values. These values will be permanently associated with this location for this program, until it’s overwritten by another setuniform call.

myprogram:setuniform4f(location, mynum1, mynum2, mynum3, mynum4)

setuniformmatrix2f ¶

Sets four floats as a uniform mat2x2 value. The first param is the "location" specified in GLSL, the second is the "transpose" boolean, and the rest are the values. Transposing a matrix turns it from row-major to column-major or vice versa. These values will be permanently associated with this location for this program, until it’s overwritten by another setuniform call.

myprogram:setuniformmatrix2f(location, false, n11, n21, n12, n22)

setuniformmatrix3f ¶

Sets nine floats as a uniform mat3x3 value. The first param is the "location" specified in GLSL, the second is the "transpose" boolean, and the rest are the values. Transposing a matrix turns it from row-major to column-major or vice versa. These values will be permanently associated with this location for this program, until it’s overwritten by another setuniform call.

myprogram:setuniformmatrix3f(location, false, n11, n21, n31, n12, n22, n32, n13, n23, n33)

setuniformmatrix4f ¶

Sets 16 floats as a uniform mat4x4 value. The first param is the "location" specified in GLSL, the second is the "transpose" boolean, and the rest are the values. Transposing a matrix turns it from row-major to column-major or vice versa. These values will be permanently associated with this location for this program, until it’s overwritten by another setuniform call.

In the following example, the 16 values are returned from get, taking advantage of the Lua feature where multiple return values can be used implicitly as multiple function arguments:

myprogram:setuniformmatrix4f(location, false, mytransform:get())

setuniformsurface ¶

Sets a Surface as a uniform value. This will usually be used for uniform sampler2D variables. This value will be permanently associated with this location for this program, until it’s overwritten by another setuniform call. Note that if the surface is destroyed before being used for a render, the results will be undefined, so make sure to keep your surface object in scope for as long as it remains bound to any uniforms.

myprogram:setuniformsurface(location, mysurface)

setuniformdepthbuffer ¶

Sets the depth buffer as a uniform value. This will usually be used for sampler2D variables. This function works like all other setuniform functions, but requiring a rendergameview event as the second argument, and, as such, it may only be called during an onrendergameview event.

bolt.onrendergameview(function (event)
  myprogram:setuniformdepthbuffer(location, event)
end)

During rendering of the game view, the game engine maintains an explicit depth buffer. The depth buffer is like a normal surface, but not exactly the same: a normal surface has internal contents of format GL_RGBA, whereas the depth buffer has contents of format GL_DEPTH_COMPONENT32F. This means that while it can be sampled in a sampler2D like any other surface, the R component will contain the depth value for that pixel, the G and B components will be undefined, and the A component will usually be 1.0.

The depth component of any given pixel represents the Z-value of whatever was drawn on that pixel, and is used by the game to ensure that something far from the camera won’t be drawn in front of something nearer, regardless of what order they’re drawn in. The primary reason why a Bolt plugin may want to sample this data would be to create a pseudo-3D effect, where each pixel in an overlay may be drawn or not drawn depending on the user’s perspective. For example, if a fragment shader was set up to draw an overlay where each pixel is either opaque or transparent depending on the depth of that pixel, it would appear that objects in the game view were obscuring the overlay by being in front of it.

Z-values are logarithmic in the range [-1.0, +1.0]. -1.0 is immediately in front of the camera, 0.0 is a very short distance away from the camera, and 1.0 is the maximum view distance away from the camera.

The width and height of the depth buffer surface, in pixels, can be retrieved by calling size() on the rendergameview event object, since the size of the game view and the size of the depth buffer will always match.

Uniform bindings in the Bolt API are permanent until overwritten, but event objects cannot be used after the even handler has returned. So, after calling this function, be careful not to use this program again after the rendergameview event handler has returned, until the uniform binding has been changed to something else.

drawtosurface ¶

Invokes this shader program to draw to a surface. Parameters are the target surface, a shader buffer, and an integer indicating the number of vertices to draw. Each 3 vertices will make a triangle. If the number of vertices isn’t a multiple of 3, then the last 1 or 2 will usually be ignored.

drawtogameview ¶

Invokes this shader program to draw to the game view. This can only be called during a rendergameview event, as the event object needs to be passed to this function. Parameters are a rendergameview event object, a shader buffer, and an integer indicating the number of vertices to draw. Each 3 vertices will make a triangle. If the number of vertices isn’t a multiple of 3, then the last 1 or 2 will usually be ignored.

vertexcount ¶

Returns the number of vertices in a 2D batch object. Divide by verticesperimage to get the number of icons being rendered.

verticesperimage ¶

Returns the number of vertices per individual image in this batch. At time of writing, this will always return 6 (i.e. enough to draw two separate triangles). To future-proof against possible engine updates, it’s recommended to use this function instead of hard-coding the number 6 into your plugin.

targetsize ¶

Returns the width and height of the target area of this render, in pixels.

For a miminap render event, this will be the size of the minimap image, usually 256x256. For a normal render2d event, this will be proportional to the size of the inner area of the game window, given by gamewindowsize - that is, if the user has an interface scaling other than 100%, it will be bigger or smaller than that area, proportionally.

targetscale ¶

Returns the interface scaling being applied to this render. For example, if the interface scaling is set to 135%, this function will return 1.35. For minimap2d handlers this function will always return 1.

vertexxy ¶

Alias for vertextargetxy

vertextargetxy ¶

Given an index of a vertex in a batch, returns its X and Y position on the target surface, in pixel coordinates. As with all screen coordinates in the Bolt API, this is relative to the top-left pixel of the screen.

As explained in targetsize, the size of the target surface won’t necessarily match the screen size. If interface scaling is in use, the target surface will be proportionally bigger or smaller than the actual game window. This function provides precise pixel locations independent of interface scaling, which are useful for distance comparisons. If a plugin needs to convert to actual screen coordinates to support interface scaling, it should use vertexscaledxy instead.

For a minimap2d handler, vertextargetxy and vertexscaledxy are the same function.

vertexscaledxy ¶

Given an index of a vertex in a batch, returns its X and Y position on the screen, in pixel coordinates. As with all screen coordinates in the Bolt API, this is relative to the top-left pixel of the screen.

This is the same as vertextargetxy except the results are multiplied by the player’s interface scaling setting (given by targetscale) to give actual screen coordinates. As a result, the values are less precise and are not necessarily whole numbers, but if a plugin wants to draw an overlay above a vertex, this is the correct function to use.

For a minimap2d handler, vertextargetxy and vertexscaledxy are the same function.

vertexatlasdetails ¶

Given an index of a vertex in a batch, returns six values describing the vertex’s image in the texture atlas. The first four values are the x, y, width and height, in pixels. The fifth and six values are booleans which relate to U and V coordinates respectively: if the value is true, U or V coordinates which fall outside the sub-image should wrap around within it. If the value is false, values should instead be clamped to the edges of the sub-image.

vertexuv ¶

Given an index of a vertex in a batch, returns the vertex’s associated "UV" coordinates. The values will either be floating-point numbers in the range 0.0 - 1.0, or nil.

If either of the returned values is nil, then the texture data for this vertex should be ignored and RGBA values of 1.0 should be used instead. Otherwise, the UVs are relative to the entire texture atlas, but may be outside of the sub-image rectangle. See See vertexatlasdetails to see how to handle those cases.

vertexcolour ¶

Given an index of a vertex in a batch, returns the red, green, blue and alpha values for that vertex, in that order. All four values will be floating-point numbers in the range 0.0 - 1.0.

These values are multiplied with the texture, so values less than 1.0 will darken the texture. A common use for this is to draw coloured text.

vertexcolor ¶

Alias for vertexcolour

textureid ¶

Returns the unique ID of the texture associated with this render. There will always be one (and only one) texture atlas associated with a 2D render batch.

The plugin API does not have a way to get a texture by its ID; this is intentional, as it wouldn’t always be safe to do so. The purpose of this function is to be able to compare texture IDs together to check if the current texture is the same one that was used in a previous render.

texturesize ¶

Returns the size of the overall texture atlas associated with this batch, in pixels.

texturecompare ¶

Compares a section of the texture atlas for this batch to some RGBA pixel data. The data can be a string or a Buffer. The function will return true only if the bytes are an exact match. It internally uses memcmp from the C library. This means comparing each set of contiguous data is very fast, but, since the data needs to be contiguous, it can only be checked one row at a time.

Internally, Bolt compares against data taken from the CPU just before being uploaded to the GPU, so there will never be any imprecision issues caused by different GPUs/drivers/etc.

The example below checks if the pixels at x,y and (x+1),y are fully opaque and red.

mybatch:texturecompare(x, y, "\xFF\x00\x00\xFF\xFF\x00\x00\xFF")

Normally the X and Y coordinates should be calculated from vertexatlasdetails.

texturedata ¶

Gets the RGBA data starting at a given coordinate of the texture atlas, and returns it as a Lua string.

The following example would return an 8-bytes-long string, containing the RGBA data for two pixels.

mybatch:texturedata(x, y, 8)

Using this function to search for specific textures isn’t recommended as it would be noticeably slower than using texturecompare.

vertexcount ¶

Returns the number of vertices in a model.

local count = event:vertexcount()

vertexpoint ¶

Given a vertex number, returns a Point representing the vertex’s model coordinates, according to the static model data.

local modelpoint = event:vertexpoint(1)

modelmatrix ¶

Returns the Transform representing the model matrix of the model being rendered. This can be used to transform points from model coordinates into world coordinates.

local modelmatrix = event:modelmatrix()
local modelpoint = event:vertexpoint(1)
local worldpoint = modelpoint:transform(modelmatrix)

viewmatrix ¶

Returns the Transform representing the view matrix of the model being rendered. Unless you understand the difference between a view matrix and a projection matrix, this probably isn’t useful to you; viewprojmatrix can be used to more efficiently get a transform from world coordinates to pixel coordinates.

projectionmatrix ¶

Returns the Transform representing the projection matrix of the model being rendered. Unless you understand the difference between a view matrix and a projection matrix, this probably isn’t useful to you; viewprojmatrix can be used to more efficiently get a transform from world coordinates to pixel coordinates.

viewprojmatrix ¶

Returns the Transform representing the combined view and projection matrices, commonly called the "viewproj matrix", of the model being rendered. This can be used to transform points from world coordinates into screen coordinates.

inverseviewmatrix ¶

Returns a Transform representing the inverse of the view matrix (a.k.a. the camera matrix) for this render. This can be used to transform points from eye-space to world-space.

vertexmeta ¶

Given a vertex number, returns a meta-ID (an integer) relating to its associated texture image. This can then be passed to atlasxywh.

local meta = event:vertexmeta(1)
local x, y, w, h = event:atlasxywh(meta)

atlasxywh ¶

Given a vertex number, returns the X, Y, width and height of its associated image in the texture atlas, in pixel coordinates.

local meta = event:vertexmeta(1)
local x, y, w, h = event:atlasxywh(meta)

vertexuv ¶

Given a vertex number, returns the vertex’s associated "UV" coordinates.

The values will be floating-point numbers, usually in the range 0.0 - 1.0. They are relative to image in the texture atlas. They may fall outside the image (and therefore outside the range 0.0 - 1.0), in which case they’re expected to wrap around within the image.

vertexcolour ¶

Given a vertex number, returns the red, green, blue and alpha values for that vertex, in that order. All four values will be floating-point numbers in the range 0.0 - 1.0.

These values are multiplied with the texture, so values less than 1.0 will darken the texture (or make it more transparent in the case of the alpha channel). A common use for this is to draw differently "tinted" versions of the same model using the same texture.

vertexcolor ¶

Alias for vertexcolour

textureid ¶

Returns the unique ID of the texture associated with this render. There will always be one (and only one) texture atlas associated with a 3D render.

The plugin API does not have a way to get a texture by its ID; this is intentional, as it wouldn’t always be safe to do so. The purpose of this function is to be able to compare texture IDs together to check if the current texture is the same one that was used in a previous render.

texturesize ¶

Returns the size of the overall texture atlas associated with this batch, in pixels.

texturecompare ¶

Compares a section of the texture atlas for this batch to some RGBA pixel data. The data can be a string or a Buffer. The function will return true only if the bytes are an exact match. It internally uses memcmp from the C library. This means comparing each set of contiguous data is very fast, but, since the data needs to be contiguous, it can only be checked one row at a time.

Internally, Bolt compares against data taken from the CPU just before being uploaded to the GPU, so there will never be any imprecision issues caused by different GPUs/drivers/etc.

The example below checks if the pixels at x,y and (x+1),y are fully opaque and red.

event:texturecompare(x, y, "\xFF\x00\x00\xFF\xFF\x00\x00\xFF")

Normally the X and Y coordinates should be calculated from atlasxywh.

texturedata ¶

Gets the RGBA data starting at a given coordinate of the texture atlas, and returns it as a Lua string.

The following example would return an 8-bytes-long string, containing the RGBA data for two pixels.

mybatch:texturedata(x, y, 8)

Using this function to search for specific textures isn’t recommended as it would be noticeably slower than using texturecompare.

vertexanimation ¶

Given a vertex number, returns the Transform object that would be applied to its static model, in model coordinates, to transform it into its current animated position.

It’s a fatal error to call this function on a render event for a non-animated model, since non-animated models have no bone transforms that could be queried. To check if the model is animated, use animated.

animated ¶

Returns a boolean value indicating whether this model is animated. Animated models can have multiple bones which can move independently of each other. If this function returns false, then the model has no animation data, and calling vertexanimation will result in an error.

if event:animated() then
  -- it's safe to call event:vertexanimation
end

cameraposition ¶

Returns the X, Y and Z of the camera position, in world coordinates, during this render.

local x, y, z = event:cameraposition()

vertexcount ¶

Returns the number of vertices being rendered.

local count = event:vertexcount()

vertexparticleorigin ¶

Given a vertex number, returns a Point representing the position of the particle that the vertex belongs to, in world coordinates. All vertices of a particle will have the same origin, since they all belong to the same particle.

local worldpoint = event:vertexparticleorigin(i)

vertexworldoffset ¶

Given a vertex number, returns three numbers representing the X, Y and Z offset of that vertex from the particle’s origin, in world space. See Render Particles Event for more info on offsets.

local xoffset, yoffset, zoffset = event:vertexworldoffset(i)

vertexeyeoffset ¶

Given a vertex number, returns two numbers representing the X and Y offset of that vertex from the particle’s origin, in eye-space (i.e. relative to the direction the camera is facing, for billboarding.) See Render Particles Event for more info on offsets.

local xoffset, yoffset = event:vertexeyeoffset(i)

vertexuv ¶

Given a vertex number, returns the vertex’s associated "UV" coordinates.

The values will be floating-point numbers, usually in the range 0.0 - 1.0. They are relative to image in the texture atlas. They may fall outside the image (and therefore outside the range 0.0 - 1.0), in which case they’re expected to wrap around within the image.

vertexcolour ¶

Given a vertex number, returns the red, green, blue and alpha values for that vertex, in that order. All four values will be floating-point numbers in the range 0.0 - 1.0.

These values are multiplied with the texture, so values less than 1.0 will darken the texture (or make it more transparent in the case of the alpha channel). A common use for this is to draw differently "tinted" versions of the same type of particle using the same texture.

vertexcolor ¶

Alias for vertexcolour

vertexmeta ¶

Given a vertex number, returns a meta-ID (an integer) relating to its associated texture image. This can then be passed to atlasxywh.

local meta = event:vertexmeta(1)
local x, y, w, h = event:atlasxywh(meta)

atlasxywh ¶

Given a vertex number, returns the X, Y, width and height of its associated image in the texture atlas, in pixel coordinates.

local meta = event:vertexmeta(1)
local x, y, w, h = event:atlasxywh(meta)

textureid ¶

Returns the unique ID of the texture associated with this render. There will always be one (and only one) texture atlas associated with a particle render.

The plugin API does not have a way to get a texture by its ID; this is intentional, as it wouldn’t always be safe to do so. The purpose of this function is to be able to compare texture IDs together to check if the current texture is the same one that was used in a previous render.

texturesize ¶

Returns the size of the overall texture atlas associated with this render, in pixels.

texturecompare ¶

Compares a section of the texture atlas for this batch to some RGBA pixel data. The data can be a string or a Buffer. The function will return true only if the bytes are an exact match. It internally uses memcmp from the C library. This means comparing each set of contiguous data is very fast, but, since the data needs to be contiguous, it can only be checked one row at a time.

Internally, Bolt compares against data taken from the CPU just before being uploaded to the GPU, so there will never be any imprecision issues caused by different GPUs/drivers/etc.

The example below checks if the pixels at x,y and (x+1),y are fully opaque and red.

event:texturecompare(x, y, "\xFF\x00\x00\xFF\xFF\x00\x00\xFF")

texturedata ¶

Gets the RGBA data starting at a given coordinate of the texture atlas, and returns it as a Lua string.

The following example would return an 8-bytes-long string, containing the RGBA data for two pixels.

mybatch:texturedata(x, y, 8)

Using this function to search for specific textures isn’t recommended as it would be noticeably slower than using texturecompare.

viewmatrix ¶

Returns a Transform representing the view matrix being used for this particle render.

projmatrix ¶

Returns a Transform representing the projection matrix being used for this particle render.

viewprojmatrix ¶

Returns the Transform representing the combined view and projection matrices, commonly called the "viewproj matrix", for this particle render. This can be used to transform points from world coordinates into screen coordinates.

inverseviewmatrix ¶

Returns a Transform representing the inverse of the view matrix (a.k.a. the camera matrix) for this particle render. This can be used to transform points from eye-space to world-space.

cameraposition ¶

Returns the X, Y and Z of the camera position, in world coordinates, during this render.

local x, y, z = event:cameraposition()

vertexcount ¶

Returns the number of vertices being rendered.

local count = event:vertexcount()

verticesperimage ¶

Returns the number of vertices per individual image in this batch. At time of writing, this will always return 6 (i.e. enough to draw two separate triangles). To future-proof against possible engine updates, it’s recommended to use this function instead of hard-coding the number 6 into your plugin.

vertexpoint ¶

Given a vertex number, returns a Point representing the vertex’s model coordinates.

local modelpoint = event:vertexpoint(1)

vertexeyeoffset ¶

Given a vertex number, returns two numbers representing the X and Y offset of that vertex from the particle’s origin, in eye-space (i.e. between the view and projection transforms, as described in Render Billboard Event).

local xoffset, yoffset = event:vertexeyeoffset(i)

vertexuv ¶

Given a vertex number, returns the vertex’s associated "UV" coordinates.

The values will be floating-point numbers, usually in the range 0.0 - 1.0. They are relative to image in the texture atlas.

At time of writing, UV coordinates for renderbillboard are stored as integers, meaning each one can only be 0 or 1.

vertexcolour ¶

Given a vertex number, returns the red, green, blue and alpha values for that vertex, in that order. All four values will be floating-point numbers in the range 0.0 - 1.0.

These values are multiplied with the texture, so values less than 1.0 will darken the texture (or make it more transparent in the case of the alpha channel). A common use for this is to draw differently "tinted" versions of the same image using the same texture.

vertexcolor ¶

Alias for vertexcolour

vertexmeta ¶

Given a vertex number, returns a meta-ID (an integer) relating to its associated texture image. This can then be passed to atlasxywh.

local meta = event:vertexmeta(1)
local x, y, w, h = event:atlasxywh(meta)

atlasxywh ¶

Given a vertex number, returns the X, Y, width and height of its associated image in the texture atlas, in pixel coordinates.

local meta = event:vertexmeta(1)
local x, y, w, h = event:atlasxywh(meta)

textureid ¶

Returns the unique ID of the texture associated with this render. There will always be one (and only one) texture atlas associated with a billboard render.

The plugin API does not have a way to get a texture by its ID; this is intentional, as it wouldn’t always be safe to do so. The purpose of this function is to be able to compare texture IDs together to check if the current texture is the same one that was used in a previous render.

texturesize ¶

Returns the size of the overall texture atlas associated with this render, in pixels.

texturecompare ¶

Compares a section of the texture atlas for this batch to some RGBA pixel data. The data can be a string or a Buffer. The function will return true only if the bytes are an exact match. It internally uses memcmp from the C library. This means comparing each set of contiguous data is very fast, but, since the data needs to be contiguous, it can only be checked one row at a time.

Internally, Bolt compares against data taken from the CPU just before being uploaded to the GPU, so there will never be any imprecision issues caused by different GPUs/drivers/etc.

The example below checks if the pixels at x,y and (x+1),y are fully opaque and red.

event:texturecompare(x, y, "\xFF\x00\x00\xFF\xFF\x00\x00\xFF")

texturedata ¶

Gets the RGBA data starting at a given coordinate of the texture atlas, and returns it as a Lua string.

The following example would return an 8-bytes-long string, containing the RGBA data for two pixels.

mybatch:texturedata(x, y, 8)

Using this function to search for specific textures isn’t recommended as it would be noticeably slower than using texturecompare.

viewmatrix ¶

Returns a Transform representing the view matrix being used for this billboard render.

projmatrix ¶

Returns a Transform representing the projection matrix being used for this billboard render.

viewprojmatrix ¶

Returns the Transform representing the combined view and projection matrices, commonly called the "viewproj matrix", for this particle render. This can be used to transform points from world coordinates into screen coordinates.

inverseviewmatrix ¶

Returns a Transform representing the inverse of the view matrix (a.k.a. the camera matrix) for this particle render. This can be used to transform points from eye-space to world-space.

cameraposition ¶

Returns the X, Y and Z of the camera position, in world coordinates, during this render.

local x, y, z = event:cameraposition()

xywh ¶

Returns the x, y, width and height of where this icon is being drawn on the screen, in pixel coordinates. The X and Y are relative to the top-left pixel of the inner area of the window.

local x, y, width, height = event:xywh()

modelcount ¶

Returns the number of 3D models that were rendered to this icon.

for model = 1, event:modelcount() do
  -- ...
end

modelvertexcount ¶

Given a model index, returns the number of vertices in that model.

for model = 1, event:modelcount() do
  for vertex = 1, event:modelvertexcount(model) do
    -- ...
  end
end

modelvertexpoint ¶

Given a model number and vertex number, returns a Point representing the vertex’s model coordinates.

local point = event:modelvertexpoint(model, vertex)

modelvertexcolour ¶

Given a model number and a vertex number, returns the red, green, blue and alpha values for that vertex, in that order. All four values will be floating-point numbers in the range 0.0 - 1.0.

These values are multiplied with the texture, so values less than 1.0 will darken the texture (or make it more transparent in the case of the alpha channel). A common use for this is to draw differently "tinted" versions of the same model using the same texture.

local red, green, blue, alpha = event:modelvertexcolour(model, vertex)

modelvertexcolor ¶

Alias for modelvertexcolour

targetsize ¶

Returns the width and height of the target area of this render, in pixels.

This will be proportional to the size of the inner area of the game window, given by gamewindowsize - that is, if the user has an interface scaling other than 100%, it will be bigger or smaller than that area, proportionally.

local width, height = event:targetsize()

modelviewmatrix ¶

Given a model number, returns a Transform representing the view matrix that was used to render it.

local viewmatrix = event:modelviewmatrix(model)

modelprojectionmatrix ¶

Given a model number, returns a Transform representing the projection matrix that was used to render it.

local projmatrix = event:modelprojectionmatrix(model)

modelviewprojmatrix ¶

Given a model number, returns a Transform representing the combined view and projection matrices, commonly called the "viewproj matrix", that was used to render that model. These are pre-multiplied in the shader, so using the viewproj matrix is more efficient than using the view and projection matrices separately.

local viewprojmatrix = event:modelviewprojmatrix(model)

colour ¶

Returns the red, green, blue and alpha values that this icon is being rendered with. These values are multiplied with the texture, so values less than 1.0 will darken the icon (or make it more transparent in the case of the alpha channel). This is usually used to draw transparent or "tinted" versions of the same pre-rendered icon. For example, a placeholder item in your bank will be drawn slightly transparent, even though the icon itself is non-transparent, to indicate that the item is a placeholder and not an actual item.

local red, green, blue, alpha = event:colour()

color ¶

Alias for colour

angle ¶

Returns the angle at which the minimap background image is being rendered, in radians. The angle is 0 when upright (facing directly north), and increases counter-clockwise (note that turning the camera clockwise rotates the minimap counter-clockwise and vice versa).

scale ¶

Returns the scale at which the minimap background image is being rendered. This indicates how far in or out the minimap is zoomed. It appears to be capped between roughly 0.5 and 3.5.

position ¶

Returns an estimate of the X and Y position the minimap is centered on, in world coordinates. This is only a rough estimate and can move around a lot even while standing still. It usually doesn’t vary by more than half a tile.

size ¶

Returns the width and height of the game view being rendered, in pixels. This will also be the width and height of the depth buffer.

local width, height = event:size()

xywh ¶

Returns the x, y, width and height of the section of the minimap image being drawn, in pixels.

local x, y, width, height = event:sourcexywh()

xywh ¶

Returns the x, y, width and height of where the minimap is being drawn on the screen, in pixel coordinates. The X and Y are relative to the top-left pixel of the inner area of the window.

local x, y, width, height = event:targetxywh()

targetsize ¶

Returns the width and height of the target area of this render, in pixels.

This will be proportional to the size of the inner area of the game window, given by gamewindowsize - that is, if the user has an interface scaling other than 100%, it will be bigger or smaller than that area, proportionally.

local width, height = event:targetsize()

readpixels ¶

Reads pixel data from a portion of the screen, defined by the given X, Y, width and height. The bounds are not allowed to exceed the size of the game window (given by gamewindowsize) and width and height are not allowed to be negative.

The function will return a Buffer with size (width * height * 3) containing RGB pixel data. The first row of data will be the one that’s nearest the bottom of the user’s screen, then continuing upwards.

The length of time this function takes will be proportional to the number of pixels being read, but an expected time to read a 1920x1080 rectangle would be around 5 milliseconds, so use with care.

Any windows, embedded browsers, or overlay contents drawn by any plugins will not be included in the image data.

local gamewidth, gameheight = bolt.gamewindowsize()
local buffer = event:readpixels(0, 0, gamewidth, gameheight)

copytosurface ¶

Copies some data from the user’s screen to a surface. Parameters are the X, Y, width and height of the region of the user’s screen, followed by the X, Y, width and height of the target area of the surface. Any previous contents of the surface in the destination area will be overwritten with a fully opaque image.

This function is preferable over readpixels as the contents of the image never need to be retrieved from the GPU, which is slow.

Any windows, embedded browsers, or overlay contents drawn by any plugins will not be included in the image.

local gamewidth, gameheight = bolt.gamewindowsize()
local mysurface = bolt.createsurface(gamewidth, gameheight)
local buffer = event:copytosurface(mysurface, 0, 0, gamewidth, gameheight, 0, 0, gamewidth, gameheight)

xywh ¶

Returns the new x, y, width and height that the window was repositioned to.

local newx, newy, newwidth, newheight = event:xywh()

didresize ¶

Returns a boolean value indicating whether the window changed size. If true, the contents of the window were cleared and need to be redrawn.

if event:didresize() then
  -- re-draw something to the window
end

xy ¶

Returns the x and y for this mouse event in pixels, relative to the top-left of the window that it relates to.

local x, y = event:xy()

ctrl ¶

Returns a boolean value indicating whether ctrl was held when this event was fired.

local ctrl = event:ctrl()

shift ¶

Returns a boolean value indicating whether shift was held when this event was fired.

local shift = event:shift()

meta ¶

Returns a boolean value indicating whether the meta key (also known as super, command, or the "windows key") was held when this event was fired.

local meta = event:meta()

alt ¶

Returns a boolean value indicating whether alt was held when this event was fired.

local alt = event:alt()

capslock ¶

Returns a boolean value indicating whether caps lock was on when this event was fired.

local capslock = event:capslock()

numlock ¶

Returns a boolean value indicating whether numlock was on when this event was fired.

local numlock = event:numlock()

mousebuttons ¶

Returns three boolean values indicating whether each primary mouse button was held when this event fired, in the order: left, right, middle.

local lmb, rmb, mmb = event:mousebuttons()

xy ¶

Returns the x and y for this mouse event in pixels, relative to the top-left of the window that it relates to.

local x, y = event:xy()

ctrl ¶

Returns a boolean value indicating whether ctrl was held when this event was fired.

local ctrl = event:ctrl()

shift ¶

Returns a boolean value indicating whether shift was held when this event was fired.

local shift = event:shift()

meta ¶

Returns a boolean value indicating whether the meta key (also known as super, command, or the "windows key") was held when this event was fired.

local meta = event:meta()

alt ¶

Returns a boolean value indicating whether alt was held when this event was fired.

local alt = event:alt()

capslock ¶

Returns a boolean value indicating whether caps lock was on when this event was fired.

local capslock = event:capslock()

numlock ¶

Returns a boolean value indicating whether numlock was on when this event was fired.

local numlock = event:numlock()

mousebuttons ¶

Returns three boolean values indicating whether each primary mouse button was held when this event fired, in the order: left, right, middle.

local lmb, rmb, mmb = event:mousebuttons()

button ¶

Returns an integer representing the mouse button that was pressed or released. Possible values are 1 for the left mouse button, 2 for the right mouse button, and 3 for the middle mouse button (clicking the mouse wheel).

xy ¶

Returns the x and y for this mouse event in pixels, relative to the top-left of the window that it relates to.

local x, y = event:xy()

ctrl ¶

Returns a boolean value indicating whether ctrl was held when this event was fired.

local ctrl = event:ctrl()

shift ¶

Returns a boolean value indicating whether shift was held when this event was fired.

local shift = event:shift()

meta ¶

Returns a boolean value indicating whether the meta key (also known as super, command, or the "windows key") was held when this event was fired.

local meta = event:meta()

alt ¶

Returns a boolean value indicating whether alt was held when this event was fired.

local alt = event:alt()

capslock ¶

Returns a boolean value indicating whether caps lock was on when this event was fired.

local capslock = event:capslock()

numlock ¶

Returns a boolean value indicating whether numlock was on when this event was fired.

local numlock = event:numlock()

mousebuttons ¶

Returns three boolean values indicating whether each primary mouse button was held when this event fired, in the order: left, right, middle.

local lmb, rmb, mmb = event:mousebuttons()

direction ¶

Returns a boolean value representing the scroll direction. False means scrolling down, toward the user, and true means scrolling up, away from the user.

local direction = event:direction()

xy ¶

Returns the x and y for this mouse event in pixels, relative to the top-left of the window that it relates to.

local x, y = event:xy()

ctrl ¶

Returns a boolean value indicating whether ctrl was held when this event was fired.

local ctrl = event:ctrl()

shift ¶

Returns a boolean value indicating whether shift was held when this event was fired.

local shift = event:shift()

meta ¶

Returns a boolean value indicating whether the meta key (also known as super, command, or the "windows key") was held when this event was fired.

local meta = event:meta()

alt ¶

Returns a boolean value indicating whether alt was held when this event was fired.

local alt = event:alt()

capslock ¶

Returns a boolean value indicating whether caps lock was on when this event was fired.

local capslock = event:capslock()

numlock ¶

Returns a boolean value indicating whether numlock was on when this event was fired.

local numlock = event:numlock()

mousebuttons ¶

Returns three boolean values indicating whether each primary mouse button was held when this event fired, in the order: left, right, middle.

local lmb, rmb, mmb = event:mousebuttons()