Introduction

Dinodeck is a multiplatform, fast, rapid game development library. It’s powered by Lua and uses OpenGL for graphics.

Dinodeck is inspired by many great engines and graphics APIs I’ve used in the past but with an emphasis on speed of development and ease of distribution.

You can download the latest version from the website dinodeck.com.

This is documentation for version 1.1.2 of the engine.

Structure

The Dinodeck engine is usually called dinodeck_win.exe on windows and dinodeck_mac on mac. When executed dinodeck does the following:

1. Checks the local directory for settings.lua.
2. If settings.lua doesn’t exist in the local directory, it attempts to look inside data.7z to check if the file exists there. This is true for all files it attempts to load.
3. Reads settings.lua and creates a window to display graphics and a console to display debugging information.
4. Loads a manifest file specified in the settings.lua file. This is usually manifest.lua
5. The manifest is a list of assets: code files, fonts, textures, sounds etc. These are loaded into memory.
6. The game loop then starts. The settings.lua file specifies which file is the main file and which function to call each frame. By default this is usually main.lua and update().
7. The program then runs until exited.

settings.lua

This file controls the overall settings for the game. It’s a Lua file and so can contain any Lua code.

Here is an example settings file:

name = "The CGGameLoop"
width = 1280/2
height = 720/2
manifest = "manifest.lua"
main_script = "main.lua"
on_update = "update()"

webserver = true

Settings Fields

Field	Default	Description
name	“CGGameLoop”	The name of your game. Appears on the window titlebar.
width	640	The width of the render area in pixels.
height	360	The height of the render area in pixels.
main_script	“main.lua”	This is the first file lua executes and where the on_update function is expected to exist.
on_update	“update()”	The main game loop called once per frame.
manifest	“”	The manifest file is described below. It lists all the files the game needs.
webserver	false	Sets up a local webserver. Used for debugging.
orientation	“portrait”	If you’re tinkering with mobile then this is the default orientation to start in.

Webserver

If the webserver flag is set to true in the settings.lua file then dinodeck runs a local webserver on port 8080. The webbrowser is used for debugging.

You can connect locally to the webserver through this address.

http://127.0.0.1:8080/

The webserver doesn’t serve any HTML by default, so if you try and view it using your browser nothing will happen. The webserver is a RESTful type setup.

Reset the game with this call.

http://127.0.0.1:8080/reset/

Get the last error with this call.

http://127.0.0.1:8080/lasterror/

Run arbitary lua code with this call

http://127.0.0.1:8080/execute/

Run this curl command to overwrite the update loop with one that prints “Hello” to the screen.

curl -XPOST -d 'update = function()
    gRenderer = Renderer.Create()
    gRenderer:DrawText2d(0,0, "Hello")
end' 'http://127.0.0.1:8080/execute/'

Data for the execute command is provided through the post data.

Why!?

Using these commands you can use Dinodeck almost like an interactive editor. Tell it reload from your text editor, or send over a snippet of code, interatively query the program at runtime. It’s a pretty powerful idea and one that that’s not been fully explored!

Orientation

This is a mobile only flag. If the value is any string but "potrait" then landscape mode is chosen. Orientation swaps the values of System.ScreenWidth and System.ScreenHeight as well as the x and y axes.

The expected value is "portrait" or "landscape".

manifest.lua

The manifest file lists the assets the game uses. Like the settings file it is a standard Lua file.

The manifest file is expected to have a table at the global level called “manifest”. This table may have serveral different subtables, each representing a different category of asset. This is best explained with an example.

An example manifest file

manifest =
{
    scripts =
    {
        ['Main.lua'] =
        {
            path = "main.lua"
        },
    },
    fonts =
    {
        ['font'] =
        {
            path = "font.ttf"
        },
    },
    textures =
    {
        ['control_bar.png'] =
        {
            path = "control_bar.png",
            scale = "pixelart"
        },
    }
}

All assets are represented by a key, value pair. The key is the name of the asset (used in the project to access it), the value is table with the path to the asset file and additional meta data about how to treat the asset.

Supported Top Level Tables

Name	Description
scripts	Lua scripts.
fonts	Font files.
textures	Image files.
sounds	Sound files.
soundstreams	Sound files to be streamed off disk. Not supported

Script Formats

Any plain text file is fine. By convention it’s normal for script files to have a ’.lua’ extension.

Font Formats

The font loader expects true type fonts i.e. .tff.

Texture Formats

The following texture formats are supported:

• BMP - non-1bpp, non-RLE (from stb_image documentation)
• PNG - non-interlaced (from stb_image documentation)
• JPG - JPEG baseline (from stb_image documentation)
• TGA - greyscale or RGB or RGBA or indexed, uncompressed or RLE
• DDS - DXT1/2/3/4/5, uncompressed, cubemaps (can’t read 3D DDS files)
• PSD - (from stb_image documentation)
• HDR - converted to LDR, unless loaded with HDR functions (RGBE or RGBdivA or RGBdivA2)

Dinodeck uses SOIL to load images. Format documentation taken from the site.

A texture asset may have an optional scale flag. This determines how the scaling works. By default scaling a sprite causes the texture to be interpolated; smoothing out the pixels. The "pixelart" flag scales using “nearest neighbor” so the pixel boundaries remain distinct.

Sound Formats

Only .wav is supported.

General Notes

Running Multiple Versions

If you run multiple versions with the webserver enabled, they try to open the same port and every version after the first application will fail to shut down cleanly.

Global Functions

Dinodeck injects a few global functions into the Lua namespace.

Function	Parameters	Description
LoadLibrary	string	Used to load libraries into the Lua namespace.
GetDeltaTime	n/a	Seconds since last frame.
GetTime	n/a	Seconds since epoch. Wraps the c time function.

LoadLibrary

Example use of LoadLibrary

LoadLibrary('Renderer')

nil LoadLibrary( string )

LoadLibrary takes in a string that must be the name of a valid library.

Library names are case sensitive, trying to load a library that doesn’t exist causes Dinodeck to enter a crash state.

Name	Description
Asset	Access assets specified in the manifest file.
Http	Send Http messages.
HttpPostData	Add POST data to http messages.
Keyboard	Check keyboard input.
Matrix	Matrix class.
Mouse	Check mouse input.
Renderer	Draw things to the screen.
SaveGame	Save and load data.
Sound	Play sounds.
SoundStream	Stream sounds from the disk. Not supported.
Sprite	Create and draw 2d sprites.
System	System functions.
Texture	Load textures and assign them to sprites.
Time	Time functions.
Touch	Touch input. Mobile only.
Vector	Vector class.

GetDeltaTime

Example use of GetDeltaTime

gDt = GetDeltaTime()

nil GetDeltaTime( nil )

Returns the time in seconds that the last frame took to execute.

Delta is often used to make animations run smoothly no matter the game speed. Dinodeck’s frames are capped at 60 frames per second.

GetTime

Example use of GetTime

local time_now = GetTime()

number GetTime( nil )

Returns the time in seconds that have elapsed since midnight Coordinated Universal Time (UTC), 1 January 1970 (i.e. Unix Epoch time). Often used for seeding Lua’s random number generator.

Libraries

Dinodeck comes with a number of built in libraries. These can be loaded into your game using the LoadLibrary function.

> Asset

Assets are files used by the game. In practice we only care about the lua files in the manifest.

Run

Example use of Asset.Run

manifest.lua

manifest =
{
    scripts =
    {
        ['Main.lua'] =
        {
            path = "main.lua"
        },
        ['AnotherFile.lua']
        {
            path = "AnotherFile.lua"
        }
    }
}

main.lua

Asset.Run('AnotherFile.lua')

nil Asset.Run( string assetName )

Parameter	Type	Description	Optional
assetName	string	Name of an asset defined in the manifest file.	✘

The function takes in the name of an asset as defined in the manifest file. It then executes the asset.

Assets are most commonly Lua scripts, using Asset.Run allows projects to be composed of multiple scripts.

> Http

The Http library allows data to be retrieved and sent from websites. This opens up the possibility of leaderboards, asynchronous multiplayer games, cloud saves, integration of social services and interesting things of that sort.

Post

Example use of Http.Post

Http.Post("http://www.example.com",
        nil,
        function(data)
            print('Success:', data)
        end,
        function()
            print('Failure')
        end)

Here the data is the html page of “http://www.example.com”.

nil Http.Post(string url, HttpPostData postData, function OnSuccess, function OnFailure)

Parameter	Type	Description	Optional
url	string	The http address to contact.	✘
postData	HttpPostData	Data to attach to the http request and send to the target webpage.	✓ Default: nil
OnSuccess	function	A lua function that gets called on successfully contacting the target site.	✘
OnFailure	function	A lua function that gets called on failing to contact the target site	✘

When sending a POST request to a website OnSuccess is called if contact is successfully made with the website. OnFailure occurs if the request times out or there’s a failure to contact the website. The OnSuccess function may be passed the information from the website as a string. PostData can be sent with the request, such as a highscore, or it may be nil if no postdata is required.

HttpPostData

Used to attach data to a Http POST request.

Create

Example of creating a HttpPostData object.

local postData = HttpPostData.Create("application/x-www-form-urlencoded")

HttpPostData HttpPostData.Create( string content_type )

Parameter	Type	Description	Optional
content_type	string	Controls how post data is attached : “multipart/form-data” or “application/x-www-form-urlencoded”	✘

Creates a HttpPostData object. The encoding_type may be “application/x-www-form-urlencoded” or “multipart/form-data”.

Generally it’s best to use “multipart/form-data” but it also depends on the site you’re sending the data to.

application/x-www-form-urlencoded

The data is attached to the end of the URL

multipart/form-data

The data is attached to the request in chunks.

AddValue

Add Value example

local postData = HttpPostData.Create("application/x-www-form-urlencoded")
postData:AddValue("data", "{score=1000}")

nil HttpPostData.AddValue(string key, string value)

Parameter	Type	Description	Optional
key	string	The string id of the data to attach to the request.	✘
value	string	The string value of the data to attach to the request.	✘

Adds a key value pair to the post data that can then be sent on to the post request.

> Keyboard

The keyboard library lets you query the state of the keyboard.

The following globals are added to query the state of keys. Each entry is an integer value representing the keycode.

Key	Description
KEY_BACKSPACE	The Backspace key.
KEY_TAB	The Tab key.
KEY_CLEAR	The 5 key on a numpad when NumLock is off.
KEY_RETURN	The Return / Enter key.
KEY_PAUSE	The Pause key.
KEY_ESCAPE	The Escape key.
KEY_SPACE	The Space key.
KEY_EXCLAIM	The ! key.
KEY_QUOTEDBL	The “ key.
KEY_HASH	The # key.
KEY_DOLLAR	The $ key.
KEY_AMPERSAND	The & key.
KEY_QUOTE	The ’ key.
KEY_LEFTPAREN	The ( key.
KEY_RIGHTPAREN	The ) key.
KEY_ASTERISK	The * key.
KEY_A	The A key.
KEY_B	The B key.
KEY_C	The C key.
KEY_D	The D key.
KEY_E	The E key.
KEY_F	The F key.
KEY_G	The G key.
KEY_H	The H key.
KEY_I	The I key.
KEY_J	The J key.
KEY_K	The K key.
KEY_L	The L key.
KEY_M	The M key.
KEY_N	The N key.
KEY_O	The O key.
KEY_P	The P key.
KEY_Q	The Q key.
KEY_R	The R key.
KEY_S	The S key.
KEY_T	The T key.
KEY_U	The U key.
KEY_V	The V key.
KEY_W	The W key.
KEY_X	The X key.
KEY_Y	The Y key.
KEY_Z	The Z key.
KEY_0	The 0 key.
KEY_1	The 1 key.
KEY_2	The 2 key.
KEY_3	The 3 key.
KEY_4	The 4 key.
KEY_5	The 5 key.
KEY_6	The 6 key.
KEY_7	The 7 key.
KEY_8	The 8 key.
KEY_9	The 9 key.
KEY_UP	The up arrow key.
KEY_DOWN	The down arrow key.
KEY_RIGHT	The right arrow key.
KEY_LEFT	The left arrow key.
KEY_INSERT	The insert key.
KEY_HOME	The home key.
KEY_END	The end key.
KEY_PAGEUP	The page up key.
KEY_PAGEDOWN	The page down key.
KEY_RSHIFT	The right shift key.
KEY_LSHIFT	The left shift key.
KEY_RCTRL	The right control key.
KEY_LCTRL	The left control key.
KEY_RALT	The right alt key.
KEY_LALT	The left alt key.

Held

Example of the Held function.

LoadLibrary(Keyboard)
LoadLibrary(Renderer)

gRenderer = Renderer:Create()
gRenderer:AlignText("center", "center")
function update()
    if Keyboard.Held(KEY_A) then
        gRenderer:DrawText2d(0, -20, "The A key is being held.")
    end
end

boolean Keyboard.Held( number keyCode)

Parameter	Type	Description	Optional
keyCode	number	The key to check if held. Refer to the table in the Keyboard Library for a full lisitng of key codes.	✘

Returns true if the key is currently being pressed.

JustReleased

boolean Keyboard.JustReleased( number keyCode )

Parameter	Type	Description	Optional
keyCode	number	The key to check if held. Refer to the table in the Keyboard Library for a full lisitng of key codes.	✘

Returns true if the key was released during the previous frame.

JustPressed

boolean Keyboard.JustPressed( number keyCode )

Returns true if the key was pressed during the previous frame.

Parameter	Type	Description	Optional
keyCode	number	The key to check if held. Refer to the table in the Keyboard Library for a full lisitng of key codes.	✘

> Matrix

A matrix 4x4 class. Matrices are useful for transformations.

Create

Example Matrix Creates functions.

LoadLibrary(Matrix)

local m = Matrix:Create() -- identity
local m2 = Matrix:Create(m) -- clone

local m3 = Matrix:Create(
    Vector.Create(1, 0, 0, 0),
    Vector.Create(0, 1, 0, 0),
    Vector.Create(0, 0, 1, 0),
    Vector.Create(0, 0, 0, 1),
  )

Matrix Matrix.Create( nil )

If no data is passed in then the matrix is initialised to the identity matrix.

The identity matrix.

1, 0, 0, 0,
0, 1, 0, 0,
0, 0, 1, 0,
0, 0, 0, 1

Matrix Matrix.Create( Matrix m )

Parameter	Type	Description	Optional
m	Matrix	Data is copied from this matrix to create new one.	✘

Matrix Matrix.Create( Vector row0, Vector row1, Vector row2, Vector row3 )

Parameter	Type	Description	Optional
row0	Vector	First row of the matrix as a vector	✘
row1	Vector	Second row of the matrix as a vector	✘
row2	Vector	Third row of the matrix as a vector	✘
row3	Vector	Forth row of the matrix as a vector	✘

This function creates a new matrix object.

Multiply

The multiply operation supports matrix, matrix multiplication and matrix vector multiplication.

Matrix Matrix.Create(Matrix lhs, Matrix rhs)

Parameter	Type	Description	Optional
lhs	Matrix	Left-hand side matrix in the multiplication.	✘
rhs	Matrix	Right-hand side matrix in the multiplication.	✘

Vector Matrix.Create(Matrix lhs, Vector rhs)

Parameter	Type	Description	Optional
lhs	Matrix	Left-hand side matrix in the multiplication.	✘
rhs	Vector	Right-hand side vector in the multiplication.	✘

SetColumn

This function updates a column inside a matrix.

nil Matrix.SetColumn(Matrix m, int index, Vector v)

Parameter	Type	Description	Optional
m	Matrix	Matrix to update.	✘
index	number	The matrix column to update 1 - 4.	✘
v	Vector	The values to write into the column.	✘

nil Matrix.SetColumn(Matrix m, int index, number x, number y, number z, number w)

Parameter	Type	Description	Optional
m	Matrix	Matrix to update.	✘
index	number	The matrix column to update 1 - 4.	✘
x	number	Value to write position 1 of the column.	✘
y	number	Value to write position 2 of the column.	✘
z	number	Value to write position 3 of the column.	✘
w	number	Value to write position 4 of the column.	✘

SetRotation

Write a rotation transformation into the matrix.

nil Matrix.SetRotation(Matrix m, Vector axis, number angle)

Parameter	Type	Description	Optional
m	Matrix	The matrix to write the rotation data to.	✘
axis	Vector	The normal vector to rotate around.	✘
angle	number	The amount of rotation to apply in degrees.	✘

SetScale

Write a scale transform into the matrix.

nil Matrix.SetScale(Matrix m, Vector scale)

Parameter	Type	Description	Optional
m	Matrix	The matrix to write the scale data to.	✘
scale	Vector	The scale to apply along the x, y and z axis.	✘

SetTranslate

Write a translate transform into the matrix.

nil Matrix.SetTranslate(Matrix m, Vector translate)

Parameter	Type	Description	Optional
m	Matrix	The matrix to write the translate data to.	✘
scale	Vector	The translation to apply to the x, y and z axis.	✘

Override: To String

Return the matrix as a string.

local m = Matrix:Create()
print(m)

> 1, 0, 0, 0,
> 0, 1, 0, 0,
> 0, 0, 1, 0,
> 0, 0, 0, 1

Override: Multiple Operator

Multiply a matrix with another matrix or a vector.

local m = Matrix:Create()
local m2 = m * m            -- returns a martix
local v = Vector.Create()
local v3 = m * v            -- returns a vector

> Mouse

The Mouse library lets us query the mouse. The mouse adds the following global variables for querying the mouse buttons.

• MOUSE_BUTTON_LEFT
• MOUSE_BUTTON_MIDDLE
• MOUSE_BUTTON_RIGHT

X

The current X position of the mouse.

float Mouse.X()

local x = Mouse:X()

Y

The current Y position of the mouse.

float Mouse.Y()

local y = Mouse:Y()

Position

The X, Y position of the mouse returned as a Vector. The z coordinate is 0.

Vector Mouse.Position()

PrevPosition

The position of the mouse on the previous frame.

Vector Mouse.PrevPosition()

Difference

The difference between the PrevPosition and the Position as a vector.

Vector Mouse.Difference()

JustPressed

If a mouse button has just been pressed down.

bool Mouse.JustPressed(int mouseButton)

Parameter	Type	Description	Optional
mouseButton	int	The mouse button to test either left, middle or right.	✘

if Mouse.JustPressed(MOUSE_BUTTON_LEFT) then
    print("Left mouse button pressed.")
end

JustReleased

If a mouse button has just been pressed and then released.

bool Mouse.JustReleased(int mouseButton)

Parameter	Type	Description	Optional
mouseButton	int	The mouse button to test either left, middle or right.	✘

if Mouse.JustReleased(MOUSE_BUTTON_LEFT) then
    print("Left mouse button released.")
end

Held

Is the current mouse button being held.

bool Mouse.Held(int mouseButton)

Parameter	Type	Description	Optional
mouseButton	int	The mouse button to test either left, middle or right.	✘

-- Draws "Hello World" next to the mouse position.
gRenderer = Renderer.Create()
if Mouse.Held(MOUSE_BUTTON_LEFT) then
    local pos = Mouse.Position()
    gRenderer:DrawText2d(pos:X(), pos:Y(), "Hello World")
end

> Renderer

The renderer library is responsible for drawing things to the screen.

The render library adds two variables to the global namespace:

Key	Description
BLEND_BLEND	The normal blend mode for sprites.
BLEND_ADDITIVE	Additive blend mode for sprites.

AlignText

Sets the the alignment for any subsequent text drawn to this renderer.

gRenderer = Renderer.Create()
gRenderer:AlignText("center", "center")

function update()
    gRenderer:DrawText2d(0, 0, "Hello World")
end

nil Renderer.AlignText(Renderer renderer, string alignX, string alignY)

Parameter	Type	Description	Optional
renderer	Renderer	The text alignment is set for this renderer.	✘
alignX	string	Takes in a “left”, “right” or “center” alignment values.	✓ Default: nil
alignY	string	Takes in a “top”, “bottom” or “center” alignment values.	✓ Default: nil

AlignTextX

Set the horizontal alignment for any subsequent text drawn to this renderer.

nil Renderer.AlignX(Renderer renderer, string align)

Parameter	Type	Description	Optional
renderer	Renderer	The text alignment is set for this renderer.	✘
align	string	Takes in a “left”, “right” or “center” alignment value.	✘

AlignTextY

Set the vertical alignment for any subsequent text drawn to this renderer.

nil Renderer.AlignY(Renderer renderer, string align)

Parameter	Type	Description	Optional
renderer	Renderer	The text alignment is set for this renderer.	✘
align	string	Takes in a “top”, “bottom” or “center” alignment value.	✘

Create

Creates a Renderer object. Usually you’ll only need a single renderer. (Future work could, in theory, extend this to allow renderers to draw to a texture instead of the screen.)

Renderer Renderer.Create()

gRenderer = Renderer:Create()
gRenderer:Align("center", "center")

function update()
    gRenderer:DrawText2d(0,0,"Hello World")
end

Clip

Define a clipping rectangle in screenspace. Pixels are only drawn inside the rectangle. Clip commands can be nested but only the most recently set clipping command is active.

nil Renderer.Clip(Renderer renderer, number x, number y, number width, number height, function doRender)

Parameter	Type	Description	Optional
renderer	Renderer	The renderer to clip.	✘
x	number	Left position of the clipping rectangle.	✘
y	number	Top position of the clipping rectangle.	✘
width	number	Width of the clipping rectangle. Negative numbers are rounded to 0.	✘
height	number	Height of the clipping rectangle. Negative numbers are rounded to 0.	✘
doRender	function	Any render commands called in this function, are clipped to the clipping rectangle.	✘

gRenderer = Renderer:Create()

function update()
    -- The right half of the screen gets clipped.
    gRenderer:Clip(0,0, System.ScreenWidth()/2, System.ScreenHeight()/2,
    function()
        gRenderer:DrawText2d(0,0,"Hello World")
    end)
end

DrawCircle2d

Draw an unfilled circle to the screen. The circle is always white.

nil Renderer.DrawCircle2d(Renderer renderer, number x, number y, number radius, number segments)

Parameter	Type	Description	Optional
renderer	Renderer	The circle is drawn using this renderer.	✘
x	number	Center x position of circle.	✘
y	number	Center y position of circle.	✘
radius	number	The radius of the circle.	✘
segments	number	The number of line segments used to draw the circle.	✓ Default: 16

DrawLine2d

Draw a straight 2d line segment between two points. The points can be two vectors or four numbers.

nil Renderer.DrawLine2d(Renderer renderer, Vector start, Vector end, Vector color)

Parameter	Type	Description	Optional
renderer	Renderer	The line is drawn using this renderer.	✘
start	Vector	Start point of the line.	✘
end	Vector	End point ofr the line.	✘
color	Vector	RGBA color to color the line.	✓ Default: White

nil Renderer.DrawLine2d(number x1, number y1, number x2, number y2, Vector color)

Parameter	Type	Description	Optional
renderer	Renderer	The line is drawn using this renderer.	✘
x1	Vector	x position of line start.	✘
y1	Vector	y position of line start.	✘
x2	Vector	x position of line end.	✘
y2	Vector	y position of line end.	✘
color	Vector	RGBA color to color the line.	✓ Default: White

DrawRect2d

Draws a filled rectangle to the screen. The rectangle can be specified with two vectors or four numbers.

-- Draw a black screen over the entire render area
gRenderer:DrawRect2d(System.ScreenTopLeft(),
                     System.ScreenBottomRight(),
                     Vector.Create(0,0,0,1))

nil Renderer.DrawRect2d(Renderer renderer, Vector bottomLeft, Vector topRight, Vector color)

Parameter	Type	Description	Optional
renderer	Renderer	The rectangle is drawn using this renderer.	✘
bottomLeft	Vector	Bottom left point of rectangle.	✘
topRight	Vector	Top right point of rectangle.	✘
color	Vector	RGBA color to fill the rectangle with.	✓ Default: Black

nil Renderer.DrawRect2d(Renderer renderer, number left, number bottom, number right, number top, Vector color)

Parameter	Type	Description	Optional
renderer	Renderer	The rectangle is drawn using this renderer.	✘
left	number	Position of left edge of the rectangle.	✘
bottom	number	Position of the bottom edge of the rectangle.	✘
right	number	Position of the right edge of the rectangle.	✘
top	number	Position of the top edge of the rectangle.	✘
color	Vector	RGBA color to fill the rectangle with.	✓ Default: Black

DrawSprite

Draw a sprite to the screen. Each sprite has it’s own position. Sprites are center aligned by default.

gRenderer = Renderer.Create()
gSprite = Sprite.Create()
gSprite:SetTexture(Texture.Find("logo.png"))

function update()
    gRenderer:DrawSprite(gSprite)
end

nil Renderer.DrawSprite(Renderer renderer, Sprite sprite)

Parameter	Type	Description	Optional
renderer	Renderer	The sprite is drawn using this renderer.	✘
sprite	Sprite	The sprite to draw.	✘

DrawText2d

Draw a string of text to the screen using the current options set for the renderer. By default text is draw aligned from the top, left.

nil Renderer.DrawText2d(Renderer renderer, Vector pos, string text, Vector color, number width)

Parameter	Type	Description	Optional
renderer	Renderer	The text is drawn using this renderer.	✘
position	Vector	Position to draw the text.	✘
text	string	Text to draw.	✘
color	Vector	Color to draw the text.	✓ Default: White
width	number	The max width of the text before it’s wrapped onto a new line	✓ Default: -1 (no wrapping)

nil Renderer.DrawText2d(Renderer renderer, number x, number y, string text, Vector color, number width)

Parameter	Type	Description	Optional
renderer	Renderer	The text is drawn using this renderer.	✘
x	number	x position to render text	✘
y	number	y position to render text	✘
text	string	Text to draw.	✘
color	Vector	Color to draw the text.	✓ Default: White
width	number	The max width of the text before it’s wrapped onto a new line	✓ Default: -1 (no wrapping)

GetKern

Kerning describes the pixel distance between two letters in a piece of text for a given font. i.e. ll tend to be closer together that ww in a non-monospace font.

A string is passed into this function because Lua doesn’t have a char type. If the string is greater than 1 character only the first character is used.

nil Renderer.GetKern(Renderer renderer, string char1, string char2)

Parameter	Type	Description	Optional
renderer	Renderer	The text is drawn using this renderer.	✘
char1	string	x position to render text	✓ Default: ’\0’
char2	string	y position to render text	✓ Default: ’\0’

GetRotate

Return the camera rotation in degrees for the renderer. This is 0 by default.

number Renderer.GetRotate(Renderer renderer)

Parameter	Type	Description	Optional
renderer	Renderer	The renderer to get the rotation from.	✘

GetScale

Returns the scale on the X and Y axis for the current renderer. The scale is X: 1, Y: 1 by default.

Vector Renderer.GetScale(Renderer renderer)

Parameter	Type	Description	Optional
renderer	Renderer	The renderer to get the scale from.	✘

GetTextRotation

Returns the current rotation applied to text drawn on the renderer, in degrees. Default rotation is 0.

Vector Renderer.GetTextRotation(Renderer renderer)

Parameter	Type	Description	Optional
renderer	Renderer	The renderer to get the text rotation from.	✘

GetTranslate

Returns the X, Y translation (this can be thought of as the position or offset, if you’re not familiar with the term translation) applied to the renderer.

Vector Renderer.GetTranslate(Renderer renderer)

Parameter	Type	Description	Optional
renderer	Renderer	The renderer to get the translation from.	✘

MeasureText

Given a piece of text this will return the text’s width and height for the current renderer in pixels (no rounding, so depending on the scale and font this may include fractional pixels).

nil Renderer.MeasureText(Renderer renderer, string text, Vector output, number width)

Parameter	Type	Description	Optional
renderer	Renderer	The renderer to use when measuring the text.	✘
text	string	The text to measure.	✘
output	Vector	The vector to write the width and height to. These are written to the X and Y elements.	✘
width	number	The pixel width after which the text will wrap. A value of -1 means the with is unlimited.	✓ Default: -1

Vector Renderer.MeasureText(Renderer renderer, string text, number width)

Parameter	Type	Description	Optional
renderer	Renderer	The renderer to use when measuring the text.	✘
text	string	The text to measure.	✘
width	number	The pixel width after which the text will wrap. A value of -1 means the with is unlimited.	✓ Default: -1

NextLine

Given a string of text, an index into that text and max width, this function returns the largest chunk of text after the index that fits within the max width for the current render settings.

This function respects word boundaries. It won’t break a word in half. i.e. “We went to the park”, will never be returned as “We went to the pa”, “rk”, instead it would be “We went to the ”, “park”

local text = "This is a lot of text and it won't fit in a small area. Therefore we might want to let the player page through it, or issue a warning etc."
gRenderer = Renderer.Create()

start, finish = gRenderer:NextLine(text, 1, 256)

print("First chunk: ", string.sub(text, start, finish))

number, number Renderer.NextLine(Renderer renderer, string text, number index, number maxwidth)

Parameter	Type	Description	Optional
renderer	Renderer	The renderer to use when working out the next chunk of text that fits.	✘
text	string	The text to break up.	✘
index	number	Where to start in the text string. The index must be 1 or great and no greater than the text length	✘
width	number	The maximum width the line can be in pixels before cutting it off.	✘

The function returns the chunk of text that fits before the max width as two indices. The first is the start index, the second is the end.

Rotate

Set the rotation of the renderer in degrees.

nil Renderer.Rotate(Renderer renderer, number rotation)

Parameter	Type	Description	Optional
renderer	Renderer	The renderer to rotate.	✘
rotation	number	The rotation to set the renderer to in degrees.	✘

RotateText

Set the rotation of any subsequent text commands sent to the renderer. In degrees, default is 0.

nil Renderer.RotateText(Renderer renderer, number rotation)

Parameter	Type	Description	Optional
renderer	Renderer	The renderer to rotate.	✘
rotation	number	The rotation for all subsequent text calls for the renderer.	✘

Scale

Set the scale of renderer on the X and Y axis. Default value is X: 1, Y: 1.

nil Renderer.Scale(Renderer renderer, Vector scale)

Parameter	Type	Description	Optional
renderer	Renderer	The renderer to scale.	✘
scale	Vector	The scale for the renderer.	✘

nil Renderer.Scale(Renderer renderer, number scaleX, number scaleY)

Parameter	Type	Description	Optional
renderer	Renderer	The renderer to scale.	✘
scaleX	number	The x scale for the renderer.	✘
scaleY	number	The y scale for the renderer.	✓ Default: current scale on the y

ScaleText

Set the X, Y scale for any subsequent text calls.

nil Renderer.ScaleText(Renderer renderer, number scaleX, number scaleY)

Parameter	Type	Description	Optional
renderer	Renderer	The renderer to set the text scale for.	✘
scaleX	number	The text x scale for the renderer.	✘
scaleY	number	The text y scale for the renderer.	✓ Default: 0

ScaleTextX

Set the horizontal scale for any subsequent text calls.

nil Renderer.ScaleTextX(Renderer renderer, number scale)

Parameter	Type	Description	Optional
renderer	Renderer	The renderer to set the text scale for.	✘
scale	number	The text x scale for the renderer.	✘

ScaleTextY

Set the vertical scale for any subsequent text calls.

nil Renderer.ScaleTextY(Renderer renderer, number scale)

Parameter	Type	Description	Optional
renderer	Renderer	The renderer to set the text scale for.	✘
scale	number	The text y scale for the renderer.	✘

SetBlend

Set the blend mode for any subsequent calls to the renderer. Additive blend works well for some particle effects, laser, explosions etc.

gRenderer = Renderer.Create()
gRenderer:SetBlend(BLEND_ADDITIVE)

There are two blend modes:

• BLEND_BLEND
• BLEND_ADDITIVE

nil Renderer.SetBlend(Renderer renderer, number blend)

Parameter	Type	Description	Optional
renderer	Renderer	The renderer to set the blend mode for.	✘
blend	number	The number for the blend mode. 1 is normal, 2 is additive. There are some globals added by the renderer to make it more friendly to use.	✘

SetFont

Set a font to be used for any subsequent draw text calls. All fonts must be included in the manifest before they can be used.

nil Renderer.SetFont(Renderer renderer, string fontName)

Parameter	Type	Description	Optional
renderer	Renderer	The renderer to set the font for.	✘
fontName	string	The name of the font is defined in the manifest file.	✘

Translate

Set the translation for the renderer.

nil Renderer.Translate(Renderer renderer, Vector position)

Parameter	Type	Description	Optional
renderer	Renderer	The renderer to translate.	✘
position	Vector	New offset for the renderer. Values are taken from the X, Y elements.	✘

nil Renderer.Translate(Renderer renderer, number x, number y)

Parameter	Type	Description	Optional
renderer	Renderer	The renderer to scale.	✘
x	number	The x scale for the renderer.	✘
y	number	The y scale for the renderer.	✓ Default: current y position

> SaveGame

Dinodeck supports extremely simple saving. On PC and Mac a save game file save.dat will be written to the same directory when the save game is written. To save the Lua data the data needs serialising to a string.

Create

Create the save game object.

SaveGame SaveGame.Create()

Read

Read the save game as a string.

string SaveGame.Read(SaveGame saveGame)

local data = someSave:Read()
print("Save data: ", data)

Write

Write a Lua string to the save game. This overwrites any existing save game.

nil SaveGame.Write(SaveGame saveGame, string data)

local someSave = SaveGame.Create()
someSave:Write("{level_unlocked = 1}")

> Sound

Play a sound definied in the manifest. Only .wavs are supported.

Play

Play a sound.

local id = Sound.Play("button_press", false)

number Sound.Play(string name, boolean loop)

Parameter	Type	Description	Optional
name	string	The name of the sound as defined in the manifest.	✘
loop	boolean	If the sound should loop.	✓ Default: false

The play function returns an id that can be used to control the sound.

Stop

Stop a sound.

nil Sound.Stop(number id)

Parameter	Type	Description	Optional
id	number	The id of the sound.	✘

Pause

Pause a sound.

nil Sound.Pause(number id)

Parameter	Type	Description	Optional
id	number	The id of the sound.	✘

Resume

Resume a paused sound.

nil Sound.Resume(number id)

Parameter	Type	Description	Optional
id	number	The id of the sound.	✘

SetVolume

Set the volume of a sound, from 0 to 1.

nil SoundSetVolume(number id, number volume)

Parameter	Type	Description	Optional
id	number	The id of the sound.	✘
volume	number	The volume to set the sound. 0 to 1.	✘

> SoundStream

Soundstream is for streaming music from the hard disk.

Play

Start playing the soundstream.

local id = SoundStream.Play("background_music", true)

number SoundStream.Play(string name, boolean loop)

Parameter	Type	Description	Optional
name	string	The name of the soundstream as defined in the manfiest.	✘
loop	boolean	If the soundstream should loop.	✓ Default: false

The returned number is an id for the soundstream that can be used to alter it’s volume or turn it off etc.

Stop

Stop a soundstream.

nil SoundStream.Stop(number id)

Parameter	Type	Description	Optional
id	number	The id of the sound stream.	✘

Pause

Pause a sound stream.

nil SoundStream.Pause(number id)

Parameter	Type	Description	Optional
id	number	The id of the sound stream.	✘

Resume

Resume a paused sound stream.

nil SoundStream.Resume(number id)

Parameter	Type	Description	Optional
id	number	The id of the sound stream.	✘

SetVolume

Set the volume of a sound stream, from 0 to 1.

nil SoundStream.SetVolume(number id, number volume)

Parameter	Type	Description	Optional
id	number	The id of the sound stream.	✘
volume	number	The volume to set the sound stream. 0 to 1.	✘

> Sprite

Sprites are used to draw images to the screen. They can be colored, moved, scaled and rotated. Sprites are pretty lightweight so you can have a lot and it should still be performant.

Create

Create a new Sprite object.

Sprite Sprite.Create()

GetColor

Get the color of the sprite. By default the color is white RGBA: (1, 1, 1, 1).

nil Sprite.GetColor(Sprite s, Vector v)

Parameter	Type	Description	Optional
s	Sprite	The sprite to get the color from.	✘
v	Vector	The sprite color is written into this vector.	✘

Vector Sprite.GetColor(Sprite s)

Parameter	Type	Description	Optional
s	Sprite	The sprite to get the color from.	✘

GetPosition

Get the position of the sprite. By default this is X: 0, Y: 0.

nil Sprite.GetPosition(Sprite s, Vector v)

Parameter	Type	Description	Optional
s	Sprite	The sprite to get the Position from.	✘
v	Vector	The sprite position is written into the X, Y components of this vector.	✘

Vector Sprite.GetPosition(Sprite s)

Parameter	Type	Description	Optional
s	Sprite	The sprite to get the position from.	✘

GetRotation

Get the rotation of the sprite in degrees. By default this is 0.

number Sprite.GetScale(Sprite s)

Parameter	Type	Description	Optional
s	Sprite	The sprite to get the rotation from.	✘

GetScale

Gets the scale for the sprite. By default this is X:1, Y:1.

nil Sprite.GetScale(Sprite s, Vector v)

Parameter	Type	Description	Optional
s	Sprite	The sprite to get the scale from.	✘
v	Vector	The sprite scale is written into the X, Y components of this vector.	✘

Vector Sprite.GetScale(Sprite s)

Parameter	Type	Description	Optional
s	Sprite	The sprite to get the scale from.	✘

GetTexture

Gets the texture currently associated with the sprite. If no texture is assigned this returns nil.

-- Get pixel size of the sprite
-- s is a setup sprite
local t = s:GetTexture()
local width = t:GetWidth()
local height = t:GetHeight()
local scale = s:GetScale()
print(string.format("Sprite is %d x %d pixels",
    width * s:X(),
    height * s:Y()))

Texture Sprite.GetTexture(Sprite s)

Parameter	Type	Description	Optional
s	Sprite	The sprite to get the texture from.	✘

SetColor

Set the color of the sprite. This color uses a multiply blend. This means if the sprite was a white circle with a black border and it’s color was set to red, the white parts would be red and the black would stay the same.

local s = Sprite.Create()
local t = Texture.Find("circle.png")
s:SetTexture(t)
s:SetColor(Vector.Create(1, 0, 0, 0))

The color is represented by a vector where the four color channels RGBA map to XYZW. (That’s Red, Green, Blue, Alpha. The alpha channel controls the sprite’s opacity).

nil Sprite.SetColor(Sprite s, Vector color)

Parameter	Type	Description	Optional
s	Sprite	The sprite to set the color for.	✘
color	Vector	The color of the sprite. XYZW elements map to RGBA.	✘

SetPosition

Set the position for a sprite. This is where it’s drawn when rendered. By default the position is X: 0, Y: 0; dead center of the screen.

-- Draw an image in top left corner of the screen
gRenderer = Renderer.Create()
local s = Sprite.Create()
local t = Texture.Find("monkey_face.png")
s:SetTexture(t)
s:SetPosition(System.ScreenTopLeft())

function update()
    gRenderer:DrawSprite(s)
end

nil Sprite.SetPosition(Sprite s, Vector position)

Parameter	Type	Description	Optional
s	Sprite	The sprite to set the position for.	✘
position	Vector	The position of the sprite. Only the X, Y elements are used.	✘

nil Sprite.SetPosition(Sprite s, number x, number y)

Parameter	Type	Description	Optional
s	Sprite	The sprite to set the position for.	✘
x	number	The x position for the sprite.	✘
y	number	The y position for the sprite.	✓ Default: The current y value.

SetRotation

Set the rotation for the sprite in degrees. The default rotation value is 0.

-- Draw a spinning monkey face on screen.

gRenderer = Renderer.Create()

local s = Sprite.Create()
s:SetTexture(Texture.Find("monkey_face.png"))

local t = 0
function update()
    t = t + GetDeltaTime()
    -- Will range from -180 to 180
    s:SetRotation(180*math.sin(t))
    gRenderer:DrawSprite(s)
end

nil Sprite.SetRotation(Sprite s, number rotation)

Parameter	Type	Description	Optional
s	Sprite	The sprite to set the rotation for.	✘
rotation	number	The rotation in degrees.	✘

SetScale

Set the scale for the sprite. 1 represents the sprite’s original scale. The default scale for a sprite is X: 1, Y: 1.

local s = Sprite.Create()
s:SetTexture(Texture.Find("logo.png"))
s:SetScale(10, 10) -- make it 10x as big

s:SetScale(1, 2) -- make it 2x as tall

-- reset using a vector
local originalScale = Vector.Create(1, 1)
s:SetScale(originalScale)

-- half size
s:SetScale(originalScale * 0.5)

nil Sprite.SetScale(Sprite s, Vector scale)

Parameter	Type	Description	Optional
s	Sprite	The sprite to set the scale for.	✘
scale	Vector	Vector to use to set the scale. X is the width, Y is the height.	✘

nil Sprite.SetScale(Sprite s, number scaleX, number scaleY)

Parameter	Type	Description	Optional
s	Sprite	The sprite to set the scale for.	✘
scaleX	number	Scale for the sprite’s width.	✘
scaleY	number	Scale for the sprite’s height.	✓ Default: 0

SetTexture

Assign a texture for the sprite to use when drawn.

Sprite s = Sprite.Create()
s:SetTexture(Texture.Find("logo.png"))

nil Sprite.SetTexture(Sprite s, Texture t)

Parameter	Type	Description	Optional
s	Sprite	The sprite to set the texture for.	✘
t	Texture	The texture to assign to the sprite.	✘

SetUVs

Set the texture coordinates for the sprite. If you’re not already familiar with U,Vs they; define a rectangle that’s cut out of the sprite’s texture. By default we use the entire texture from the top left (0,0) to the bottom right (1, 1).

--Use only the top quarter of a texture
local s = Sprite.Create()
s:SetTexture(Texture.Find("logo.png"))
s:SetUVs(0, 0, 0.5, 0.5)

Using this function you can do neat things like scroll the UVs.

nil Sprite.SetUVs(Sprite s, number u1, number v1, number u2, number v2)

Parameter	Type	Description	Optional
s	Sprite	The sprite to set the UVs on.	✘
u1	number	The leftmost coordinate for the texture.	✘
v1	number	The topmost coordinate for the texture.	✘
u2	number	The rightmost coordinate for the texture.	✘
v2	number	The bottommost coordinate for the texture.	✘

__tostring

A metatable entry for writing to a string. Outputs the type information.

local sprite = Sprite.Create()
print(sprite) -- "Sprite"

> System

System functions control how the game is displayed and interacts with the host operating system.

Exit

This call closes down the application. Want to implement a Quit button? This is what you’re after.

nil System.Exit()

IsWideScreen

This a dummy function that will always return true.

boolean System.IsWideScreen()

OpenURL

Opens a URL in the default webbrowser.

System.OpenURL("http://dinodeck.com")

nil System.OpenURL(string url)

ScreenTopLeft

Get the the top left position of the screen in pixels. (Equivalent to: -ScreenWidth()/2, ScreenHeight).

Vector System.ScreenTopLeft()

ScreenBottomRight

Get the the bottom right position of the screen in pixels. (Equivalent to: ScreenWidth()/2, -ScreenHeight).

Vector System.ScreenBottomRight()

ScreenHeight

Get the height of the screen in pixels.

number ScreenHeight()

ScreenWidth

Get the width of the screen in pixels.

number ScreenWidth()

Version

Returns the current version of Dinodeck as a string.

string Version()

local version = System.Version()
print(version) -- "v1.1.2"

> Texture

A class that represents a reference to a texture defined in the manifest file.

Find

This is a “static” function that let’s you create textures from the manifest. Each texture is a reference so creating two different textures using the same file doesn’t cause any siginificant overhead.

-- Imagine your manifest looks like this
manifest =
{
    scripts =
    {
        ['Main.lua'] = { path = "main.lua" },
    },
    textures =
    {
        ['logo.png'] = { path = "logo.png", },
    }
}
-- Then you load that texture in main.lua as so

local t = Texture.Find("logo.png")
string.format("The texture is %s pixels wide.",
              t:GetWidth())
-- Prints:
-- The texture is 128 pixels wide.

Texture Texture.Find(string id)

Parameter	Type	Description	Optional
id	string	The id of the texture, as defined in the manifest file.	✘

GetHeight

Get the height of texture in pixels.

number Texture.GetHeight(Texture t)

Parameter	Type	Description	Optional
t	Texture	The texture to get the height from.	✘

GetWidth

Get the width of texture in pixels.

number Texture.GetWidth(Texture t)

Parameter	Type	Description	Optional
t	Texture	The texture to get the width from.	✘

__tostring

A metatable entry for writing to a string. Outputs the texture dimensions and type information.

local logo = Texture.Find("logo.png")
print(logo) -- "Texture [128 x 128]"

> Time

Time and date code is notoriously tricky but luckily this library is here to help out.

Difference

Returns the difference between two times in seconds.

number Time.Difference(number time1, number time2)

LoadLibrary("Renderer")
LoadLibrary("Time")

gRenderer = Renderer:Create()

start = Time.GetTime()

function update()

    local now = Time.GetTime()
    local runTimeSecs = Time.Difference(start, now)

    gRenderer:AlignText("right", "center")
    gRenderer:DrawText2d(-5, 0, "Program Has Been Running For:")
    gRenderer:AlignText("left", "center")
    gRenderer:DrawText2d(5, 0, string.format("%ds", runTimeSecs))
end

GetDate

Returns the date, in the range 1-31, from a raw time number.

number GetDate(number time)

local now = Time.GetTime()
print(Time.GetDate(now)) -- a number representing the date

GetDay

Returns the day, in the range 1-7, from a raw time number.

local now = Time.GetTime()
print(Time.GetDay(now)) -- a number representing the day

number GetDay(number time)

GetHour

Returns the hour of the day from a raw time number. In the range 0 - 23.

local now = Time.GetTime()
print(Time.GetHour(now)) -- a number representing the hour

number GetHour(number time)

GetMinute

Returns the current minute of the time from a raw time number. (This not the time in minutes, it’s the minute value of the current time. i.e. if the time ends in 4:03 this function returns 3.)

The range returned is 0 - 59.

number GetMinute(number time)

GetMonth

Gets the month from a raw time string. The range is 1-12.

number GetMonth(number time)

GetSecond

Get the second value for the current time.

GetTime

Get the raw time string for the current date and time.

local time = Time.GetTime()
print("It's the year %s", Time.GetYear(time))

number GetTime()

GetYear

Get the year for the current raw string.

number GetYear(number time)

> Touch

The touch library is for touch input, such as a mobile phone screen.

Held

Is the user pressing their finger against the touchpad.

boolean Touch.Held()

Returns true if held, otherwise false.

JustPressed

Has the user touched the pad for the first time.

boolean Touch.JustPressed()

Returns true if just pressed, otherwise false.

JustReleased

Has the user released their press of the touch screen.

boolean Touch.JustReleased()

Returns true if just released the press otherwise false.

Position

Gets the last position of the touch as a vector. Starts at 0, 0.

Vector Touch.Position()

void Touch.Position(Vector v)

X

Gets the last X position of the touch.

number Touch.X()

Y

Gets the last Y position of the touch.

number Touch.Y()

> Vector

A Vector class. It has four elements: XYZW. It’s used for physics simulations and math stuff. The vector is also used as a simple way to hold a color where XYZW is treated as RGBA.

Add

Adds two vectors together, or adds a number to all vector values.

local v1 = Vector.Create(0, 0, 0, 1)
local v2 = Vector.Create(1, 1, 1, 1)

Vector.Add(v1, v2) -- (1, 1, 1, 2)
v1:Add(v2) -- (1, 1, 1, 2)

Vector.Add(v2, 1) -- (2, 2, 2, 2)
v1:Add(1) -- (1, 1, 1, 2)

Vector Vector.Add(Vector v1, Vector v2)

Parameter	Type	Description	Optional
v1	Vector	The first vector to add.	✘
v2	Vector	The second vector to add	✘

Vector Vector.Add(Vector v1, float n)

Parameter	Type	Description	Optional
v1	Vector	The first vector to add.	✘
n	number	Number to add to each of the vector’s elements	✘

Copy

Copies the data from one Vector to another.

local v1 = Vector.Create(0, 0, 0, 1)
local v2 = Vector.Create(1, 1, 1, 1)

v1:Copy(v2)
print(v1) -- (1, 1, 1, 1)
Vector.Copy(v2, Vector.Create(5, 4, 3, 2))
print(v2) -- (5, 4, 3, 2)

Vector Vector.Copy(Vector to, Vector from)

Parameter	Type	Description	Optional
to	Vector	The vector that will have it data overriden.	✘
from	Vector	The vector to copy the new data from.	✘

Create

Create a new Vector.

local v = Vector.Create()
print(v) -- (0, 0, 0, 0)

local source = Vector.Create(1, 2, 3, 4)
local s2 = Vector.Create(source)

print(s2) -- (1, 2, 3, 4)

Vector Vector.Create()

With no arguments an empty vector with all elements set to zero is returned.

Vector Vector.Create(float x, float y, float z, float w)

Parameter	Type	Description	Optional
x	number	The x element for the vector.	✓ Default: 0
y	number	The y element for the vector.	✓ Default: 0
z	number	The z element for the vector.	✓ Default: 0
w	number	The w element for the vector.	✓ Default: 0

Vector Vector.Create(Vector source)

Parameter	Type	Description	Optional
source	Vector	A new vector is created copying all the data from the source.	✘

Cross

Performs the cross product on two vectors. If you imagine the two vectors making a plane, the cross product gives the normal for that plane.

void Vector.Cross(Vector destination, Vector left, Vector right)

local xAxis = Vector.Create(1, 0, 0, 0)
local zAxis = Vector.Create(0, 0, 1, 0)
output = Vector.Create()

Vector.Cross(output, xAxis, zAxis)
print(output) -- (0, 1, 0, 0)

Parameter	Type	Description	Optional
destination	Vector	The vector to store the result in.	✘
left	Vector	The left vector of the cross.	✘
right	Vector	The right vector of the cross.	✘

Divide

The left vector’s elements are divided by the right and stored in the destination vector.

void Vector.Divide(Vector destination, Vector left, Vector right)

local a = Vector.Create(2, 4, 6, 8)
local b = Vector.Create(2, 2, 2, 2)
output = Vector.Create()

Vector.Divide(output, a, b)
print(output) -- (1, 2, 3, 4)

Parameter	Type	Description	Optional
destination	Vector	The vector to store the result in.	✘
left	Vector	The left vector of the divide.	✘
right	Vector	The right vector of the divide.	✘

Dot2

Performs a dot product on the X, Y elements for the vector. The dot product calculates the cosine of the angle between two vectors.

a = Vector.Create(0, 1, 0, 0)
b = Vector.Create(0, -1, 0, 0)
output = Vector.Dot2(a, b)
print(output) -- -1

Values range from 1 to -1. If the two input vectors are pointing in the same direction, then the return value will be 1. If the two input vectors are pointing in opposite directions, then the return value will be -1.

void Vector.Dot2(Vector a, Vector b)

Parameter	Type	Description	Optional
left	Vector	The left vector of the dot.	✘
right	Vector	The right vector of the dot.	✘

Dot3

Performs the dot product on the X, Y, Z elements of two vectors. Otherwise the same as Dot2.

Dot4

Performs the dot product on the X, Y, Z, W elements of two vectors. Otherwise the same as Dot2.

Length2

Returns the length of a vector, only taking into account the X and Y elements.

a = Vector.Create(0, 1, 0, 0)
length = a:Length2()
print(length) -- 1

void Vector.Length2(Vector v)

Parameter	Type	Description	Optional
v	Vector	The vector to calculate the length from.	✘

Length3

Same as Length2 but operates on the X, Y and Z elements.

Length4

Same as Length4 but operates on the X, Y and Z elements.

Multiply

Multiply the elements of one vector with another.

a = Vector.Create(0, 1, 0, 0)
b = Vector.Create(1, 1, 1, 1)
c = Vector.Create()
Vector.Multiply(c, a, b)

print(c) -- 0, 1, 0, 0

void Vector.Multiply(Vector destination, Vector left, Vector right)

Parameter	Type	Description	Optional
destination	Vector	The vector to store the result in.	✘
left	Vector	The left vector of the mutiply.	✘
right	Vector	The right vector of the mutiply.	✘

Normalize2

Normalize the vector to a unit vector. Only considers the X, Y elements

Normalize3

Normalize the vector to a unit vector. The same as Normalize2 but for X, Y, Z

Normalize4

Normalize the vector to a unit vector. The same as Normalize3 but for X, Y, Z, W.

SetBroadcast

Set every element of the vector to the same value.

a = Vector.Create(1, 2, 3, 4)
a:SetBroadcast(2)

print(a) -- 2, 2, 2, 2

void Vector.SetBroadcast(Vector vector, number value)

Parameter	Type	Description	Optional
v	Vector	The vector to write to.	✘
value	Vector	The number to write into the vector.	✘

SetXyzw

Sets the X, Y, Z and W elements of the vector.

SetX

Set the X value for a vector.

number Vector.SetX(Vector vector, number value)

Vector v = Vector.Create(0, 0, 0, 0)
v:SetX(20)
print(v:X()) -- 20

SetY

Set the Y value for a vector.

number Vector.SetY(Vector vector, number value)

Vector v = Vector.Create(0, 0, 0, 0)
v:SetY(20)
print(v:Y()) -- 20

SetZ

Set the Z value for a vector.

number Vector.SetZ(Vector vector, number value)

Vector v = Vector.Create(0, 0, 0, 0)
v:SetZ(20)
print(v:Z()) -- 20

SetW

Set the W value for a vector.

number Vector.SetW(Vector vector, number value)

Vector v = Vector.Create(0, 0, 0, 0)
v:SetW(20)
print(v:W()) -- 20

Subtract

Subtract two vectors.

local v1 = Vector.Create(0, 0, 0, 1)
local v2 = Vector.Create(1, 1, 1, 1)

Vector.Subtract(v1, v2) -- (-1, -1, -1, 0)
v1:Subtract(v2) -- (-1, -1, -1, 0)

Vector Vector.SetW(Vector v1, Vector v2)

Parameter	Type	Description	Optional
v1	Vector	First vector to subtract.	✘
v2	Vector	Second vector to subtract from first	✘

X

Get the X element for a vector.

number Vector.X(Vector vector)

Vector v = Vector.Create(1, 2, 3, 0)
print(v:X()) -- 1

Y

Get the Y element for a vector.

number Vector.Y(Vector vector)

Vector v = Vector.Create(1, 2, 3, 0)
print(v:Y()) -- 2

Z

Get the Z element for a vector.

number Vector.Z(Vector vector)

Vector v = Vector.Create(1, 2, 3, 0)
print(v:Z()) -- 3

W

Get the W element for a vector.

number Vector.W(Vector vector)

Vector v = Vector.Create(1, 2, 3, 0)
print(v:W()) -- 0

__add

A metatable entry for infix addition. Uses the Add function.

a = Vector.Create(1,1,1,1)
b = Vector.Create(a)
print(a + b) -- 2,2,2,2

__div

A metatable entry for infix division. Uses the Divide function.

a = Vector.Create(1,1,1,1)
b = Vector.Create(2,2,2,2)
print(a / b) -- 0.5, 0.5, 0.5, 0.5

__mul

A metatable entry for infix multiplication. Uses the Multiply function.

a = Vector.Create(1,1,1,1)
b = Vector.Create(2,2,2,2)
print(a * b) -- 2, 2, 2, 2

__sub

A metatable entry for infix subtraction. Uses the Subtract function.

a = Vector.Create(1,1,1,1)
b = Vector.Create(2,2,2,2)
print(a - b) -- -1, -1, -1, -1

__tostring

A metatable entry for writing to a string.

print(Vector.Create())
-- Ouputs:
-- Vector.Create(0, 0, 0, 0)

__unm

A metatable entry for adding a minus to the front of the vector to negate it.

a = -Vector.Create(1, 1, 1, 1)
print(a) -- -1, -1, -1, -1