API Reference

Introduction

This page contains documentation for all of ERA-3D's API Functions.

Info

A brief description of each function can be accessed using the ERA-3D console.

Access the console by pressing Ctrl+Enter.

The console command api will open a list of API functions, use the arrow keys to navigate and press Enter to view a function's description.

To quickly get the description of a specific function, run the console command help <function>.

Warning

The API documentation accessed using the console is not currently up-to-date with the online version.

For now, it is recommended to use this page instead.

Function Catagories

API functions are organized into several catagories, click a catagory below or in the sidebar to jump to the related functions.

You can also use the search bar in the site header to search for a particular function.

• Math
• Vectors
• Matrices
• Input
• Graphics
• Audio
• Physics
• Memory
• Misc

Math

ceil

Signature:

float ceil(float x)

Arguments:

• float x: Input value

Description:

Returns x rounded upward to the nearest whole number. This function always rounds toward positive infinity.

cos

Signature:

float cos(float x)

Arguments:

• float x: Input value

Description:

Returns the cosine of x. Return value ranges from -1.0 to 1.0.

deg

Signature:

float deg(float angle)

Arguments:

• float angle: Input angle (in radians)

Description:

Returns angle in degrees.

floor

Signature:

float floor(float x)

Arguments:

• float x: Input value

Description:

Returns x rounded downward to the nearest whole number. This function always rounds toward negative infinity.

fract

Signature:

float fract(float x)

Arguments:

• float x: The value to get the fractional component of

Description:

Returns the fractional component of x.

maxf

Signature:

float maxf(float a, float b)

Arguments:

• float a: The first value to check
• float b: The second value to check

Description:

Returns the higher of the two given floats.

maxi

Signature:

int maxi(int a, int b)

Arguments:

• int a: The first value to check
• int b: The second value to check

Description:

Returns the higher of the two given integers.

midf

Signature:

float midf(float a, float b, float c)

Arguments:

• float a: The first value to check
• float b: The second value to check
• float c: The third value to check

Description:

Returns the middle of the three given floats.

midi

Signature:

int midi(int a, int b, int c)

Arguments:

• int a: The first value to check
• int b: The second value to check
• int c: The third value to check

Description:

Returns the middle of the three given integers.

minf

Signature:

float minf(float a, float b)

Arguments:

• float a: The first value to check
• float b: The second value to check

Description:

Returns the lower of the two given floats.

mini

Signature:

int mini(int a, int b)

Arguments:

• int a: the first value to check
• int b: the second value to check

Description:

Returns the lower of the two given integers.

powf

Signature:

float powf(float x, float exp)

Arguments:

• float x: The base value
• float exp: The exponent value

Description:

Returns x raised to the power of exp.

rad

Signature:

float rad(float angle)

Arguments:

• float angle: Input angle (in degrees)

Description:

Returns angle in radians.

randf

Signature:

float randf(float min, float max)

Arguments:

• float min: The minimum range value (inclusive)
• float max: The maximum range value (inclusive)

Description:

Returns a random float in the range [min, max].

randfEx

Signature:

float randfEx()

Description:

Returns a random float in the range [0.0, 1.0).

randi

Signature:

int randi(int min, int max)

Arguments:

• int min: The minimum range value (inclusive)
• int max: The maximum range value (inclusive)

Description:

Returns a random int in the range [min, max].

randiEx

Signature:

int randiEx()

Description:

Returns an int with individually randomized bits.

randomize

Signature:

void randomize()

Description:

Initializes the random number generator with a weak seed.

It is not strictly necessary to call this function on init, as the system will initialize RNG when a cart is ran.

randomizeEx

Signature:

void randomizeEx(int seed)

Arguments:

• int seed: Initialization value for RNG

Description:

Initializes the random number generator with seed.

Identical seeds will produce the same sequence of numbers.

round

Signature:

float round(float x)

Arguments:

• float x: Input value

Description:

Returns x rounded toward to the nearest whole number.

Halfway cases are rounded away from zero.

signf

Signature:

float signf(float x)

Arguments:

• float x: Input value

Description:

Returns the sign of the float x.

If x < 0, returns -1.

If x > 0, returns 1.

If x == 0, returns 0.

signi

Signature:

int signi(int x)

Arguments:

• int x: Input value

Description:

Returns the sign of the int x.

If x < 0, returns -1.

If x > 0, returns 1.

If x == 0, returns 0.

sin

Signature:

float sin(float x)

Arguments:

• float x: Input value

Description:

Returns the sine of x.

Return value will be in the range [-1.0, 1.0].

wrapf

Signature:

float wrapf(float x, float min, float max)

Arguments:

• float x: The value to wrap
• float min: The minimum range value
• float max: The maximum range value (exclusive)

Description:

Returns a float value within the range [min, max).

If x is < min or x >= max, it wraps around to the other end of the range.

wrapi

Signature:

int wrapi(int x, int min, int max)

Arguments:

• int x: The value to wrap
• int min: The minimum range value
• int max: The maximum range value (exclusive)

Description:

Returns an int value within the range [min, max).

If x is < min or x >= max, it wraps around to the other end of the range.

Vectors

cam3DForward

Signature:

vec3 cam3DForward(int camera)

Arguments:

• int camera: Index of the 3D camera to use [0-3]

Description:

Returns a 3D vector pointing forward in camera's local space.

cam3DRight

Signature:

vec3 cam3DRight(int camera)

Arguments:

• int camera: Index of the 3D camera to use [0-3]

Description:

Returns a 3D vector pointing rightward in camera's local space.

vec2Angle

Signature:

float vec2Angle(vec2 a, vec2 b)

Arguments:

• vec2 a: First input vector
• vec2 b: Second input vector

Description:

Returns the angle (in degrees) from a to b.

vec2Cross

Signature:

float vec2Cross(vec2 a, vec2 b)

Arguments:

• vec2 a: First input vector
• vec2 b: Second input vector

Description:

Returns the cross product of a and b.

This value is computed as (a.x * b.y - a.y * b.x).

vec2Direction

Signature:

vec2 vec2Direction(vec2 a, vec2 b)

Arguments:

• vec2 a: Start vector
• vec2 b: End vector

Description:

Returns a normalized 2D vector pointing from a to b.

vec2Distance

Signature:

float vec2Distance(vec2 a, vec2 b)

Arguments:

• vec2 a: First input vector
• vec2 b: Second input vector

Description:

Returns the distance between a and b.

vec2DistanceSq

Signature:

float vec2DistanceSq(vec2 a, vec2 b)

Arguments:

• vec2 a: First input vector
• vec2 b: Second input vector

Description:

Returns the squared distance between a and b.

This function is less costly to compute than vec2Distance().

As such, it is recommended to use this function when exact distance is not needed.

vec2Dot

Signature:

float vec2Dot(vec2 a, vec2 b)

Arguments:

• vec2 a: First input vector
• vec2 b: Second input vector

Description:

Returns the dot product of a and b.

Use this function to compare the angle between two 2D vectors.

For un-normalized vectors:

• Returns 0 when the angle is 90 degrees
• Returns a negative value when the angle is greater than 90 degrees
• Returns a positive value when the angle is less than 90 degrees

For normalized vectors:

• Returns a value in the range [-1.0, 1.0]; -1.0 for a 180 degree angle and 1.0 when a and b are aligned.

vec2Down

Signature:

vec2 vec2Down()

Description:

Returns a vec2 with the value vec2(0.0, -1.0).

vec2Invert

Signature:

vec2 vec2Invert(vec2 v)

Arguments:

• vec2 v: The vector to invert

Description:

Returns the inverse of the v.

Equivelent to vec2(1.0 / v.x, 1.0 / v.y).

vec2Left

Signature:

vec2 vec2Left()

Description:

Returns a vec2 with the value vec2(-1.0, 0.0).

vec2Length

Signature:

float vec2Length(vec2 v)

Arguments:

• vec2 v: The vector to get the length of

Description:

Returns the length (magnitude) of v.

vec2LengthSq

Signature:

float vec2LengthSq(vec2 v)

Arguments:

• vec2 v: The vector to get the length of

Description:

Returns the squared length (squared magnitude) of v.

This function is less costly to compute than vec2length().

As such, it is recommended to use this function when exact magnitude is not needed. (i.e. comparing vectors)

vec2Lerp

Signature:

vec2 vec2Lerp(vec2 start, vec2 end, float amount)

Arguments:

• vec2 start: Start vector
• vec2 end: Destination vector
• float amount: Amount to interpolate by (1.0 = 100%)

Description:

Returns the linear interpolation between start and end.

vec2MoveToward

Signature:

vec2 vec2MoveToward(vec2 start, vec2 end, float distance)

Arguments:

• vec2 start: Starting vector
• vec2 end: Destination vector
• float distance: Maximum distance to travel

Description:

Returns the 2D vector start after being moved toward end by the given distance.

If distance is greater than the amount required to reach end, returns end.

vec2Normalize

Signature:

vec2 vec2Normalize(vec2 v)

Arguments:

• vec2 v: The vector to normalize

Description:

Returns a 2D vector that points in the same direction as v, but has a length (magnitude) of 1.0.

vec2One

Signature:

vec2 vec2One()

Description:

Returns a vec2 with the value vec2(1.0, 1.0).

vec2Reflect

Signature:

vec2 vec2Reflect(vec2 v, vec2 normal)

Arguments:

• vec2 v: The vector to reflect
• vec2 normal: The normal vector to reflect off of

Description:

Returns the 2D vector v reflected off of the normal vector.

vec2Right

Signature:

vec2 vec2Right()

Description:

Returns a vec2 with the value vec2(1.0, 0.0).

vec2Rotate

Signature:

vec2 vec2Rotate(vec2 v, float angle)

Arguments:

• vec2 v: The starting vector
• vec2 angle: The angle to rotate by (in degrees)

Description:

Returns the 2D vector v rotated by the given angle.

vec2Up

Signature:

vec2 vec2Up()

Description:

Returns a vec2 with the value vec2(0.0, 1.0).

vec2Zero

Signature:

vec2 vec2Zero()

Description:

Returns a vec2 with the value vec2(0.0, 0.0).

vec3Angle

Signature:

float vec3Angle(vec3 a, vec3 b)

Arguments:

• vec3 a: First input vector
• vec3 b: Second input vector

Description:

Returns the angle (in degrees) from a to b.

vec3Back

Signature:

vec3 vec3Back()

Description:

Returns a vec3 with the value vec3(0.0, 0.0, 1.0).

vec3Cross

Signature:

float vec3Cross(vec3 a, vec3 b)

Arguments:

• vec3 a: First input vector
• vec3 b: Second input vector

Description:

Returns the cross product of a and b.

vec3Direction

Signature:

vec3 vec3Direction(vec3 a, vec3 b)

Arguments:

• vec3 a: Start vector
• vec3 b: End vector

Description:

Returns a normalized 3D vector pointing from a to b.

vec3Distance

Signature:

float vec3Distance(vec3 a, vec3 b)

Arguments:

• vec3 a: First input vector
• vec3 b: Second input vector

Description:

Returns the distance between a and b.

vec3DistanceSq

Signature:

float vec3DistanceSq(vec3 a, vec3 b)

Arguments:

• vec3 a: First input vector
• vec3 b: Second input vector

Description:

Returns the squared distance between a and b.

This function is less costly to compute than vec3Distance().

As such, it is recommended to use this function when exact distance is not needed.

vec3Dot

Signature:

float vec3Dot(vec3 a, vec3 b)

Arguments:

• vec3 a: First input vector
• vec3 b: Second input vector

Description:

Returns the dot product of a and b.

Use this function to compare the angle between two 3D vectors.

For un-normalized vectors:

• Returns 0 when the angle is 90 degrees.
• Returns a negative value when the angle is greater than 90 degrees.
• Returns a positive value when the angle is less than 90 degrees.

For normalized vectors:

• Returns a value in the range [-1.0, 1.0]; -1.0 for a 180 degree angle and 1.0 when a and b are aligned.

vec3Down

Signature:

vec3 vec3Down()

Description:

Returns a vec3 with the value vec3(0.0, 1.0, 0.0).

vec3Forward

Signature:

vec3 vec3Forward()

Description:

Returns a vec3 with the value vec3(0.0, 0.0, -1.0).

vec3Invert

Signature:

vec3 vec3Invert(vec3 v)

Arguments:

• vec3 v: The vector to invert

Description:

Returns the inverse of v.

Equivelent to vec3(1.0 / v.x, 1.0 / v.y, 1.0 / v,z).

vec3Left

Signature:

vec3 vec3Left()

Description:

Returns a vec3 with the value vec3(-1.0, 0.0, 0.0).

vec3Length

Signature:

float vec3Length(vec3 v)

Arguments:

• vec3 v: The vector to get the length of

Description:

Returns the length (magnitude) of v.

vec3LengthSq

Signature:

float vec3LengthSq(vec3 v)

Arguments:

• vec3 v: The vector to get the length of

Description:

Returns the squared length (squared magnitude) of v.

This function is less costly to compute than vec3Length().

As such, it is recommended to use this function when exact magnitude is not needed. (i.e. comparing vectors)

vec3Lerp

Signature:

vec2 vec3Lerp(vec3 start, vec3 end, float amount)

Arguments:

• vec3 start: Start vector
• vec3 end: Destination vector
• float amount: Amount to interpolate by (1.0 = 100%)

Description:

Returns the linear interpolation between start and end.

vec3MoveToward

Signature:

vec3 vec3MoveToward(vec3 start, vec3 end, float distance)

Arguments:

• vec3 start: The starting vector
• vec3 end: The destination vector
• float distance: The maximum distance to travel

Description:

Returns the 3D vector start after being moved toward end by the given distance.

If distance is greater than the amount required to reach end, returns end.

vec3Normalize

Signature:

vec3 vec3Normalize(vec3 v)

Arguments:

• vec3 v: The vector to normalize

Description:

Returns a 3D vector that points in the same direction as v, but has a length (magnitude) of 1.0.

vec3One

Signature:

vec3 vec3One()

Description:

Returns a vec3 with the value vec3(1.0, 1.0, 1.0).

vec3Reflect

Signature:

vec3 vec3Reflect(vec3 v, vec3 normal)

Arguments:

• vec3 v: The vector to reflect
• vec3 normal: The normal vector to reflect off of

Description:

Returns the 3D vector v reflected off of the normal vector.

vec3Right

Signature:

vec3 vec3Right()

Description:

Returns a vec3 with the value vec3(1.0, 0.0, 0.0).

vec3Rotate

Signature:

vec3 vec3Rotate(vec3 v, vec3 axis, float angle)

Arguments:

• vec2 v: The starting vector
• vec2 axis: The axis to rotate along
• vec2 angle: The angle to rotate by (in degrees)

Description:

Returns the 3D vector v rotated along the given axis by the given angle.

vec3ToScreen

Signature:

vec2 vec3ToScreen(vec3 v, int camera)

Arguments:

• vec3 v: The vector to project
• int camera: The index of the 3D camera to use for the projection [0-3]

Description:

Returns a 2D vector containing the screen coordinates of the 3D vector v, as viewed from the perspective of the given 3D camera.

vec3Up

Signature:

vec3 vec3Up()

Description:

Returns a vec3 with the value vec3(0.0, -1.0, 0.0).

vec3Zero

Signature:

vec3 vec3Zero()

Description:

Returns a vec3 with the value vec3(0.0, 0.0, 0.0).

Matrices

matrixAdd

Signature:

matrix matrixAdd(matrix a, matrix b)

Arguments:

• matrix a: The first matrix to add
• matrix b: The second matrix to add

Description:

Returns a matrix that is the result of a + b.

matrixIdentity

Signature:

matrix matrixIdentity()

Description:

Returns an identity matrix. (a matrix with no transformations applied)

An identity matrix can be constructed as follows:

matrix(
    1.0, 0.0, 0.0, 0.0,
    0.0, 1.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    0.0, 0.0, 0.0, 1.0
)

matrixInvert

Signature:

matrix matrixInvert(matrix m)

Arguments:

• matrix m: The matrix to invert

Description:

Returns the inverse matrix of m.

An inverted matrix multiplied by the original will result in an identity matrix.

matrixLookAt

Signature:

matrix matrixLookAt(vec3 eye, vec3 target, vec3 up)

Arguments:

• vec3 eye: Eye position
• vec3 target: Target position
• vec3 up: Up vector

Description:

Returns a matrix describing a view from eye looking at target with an up vector of up.

matrixMultiply

Signature:

matrix matrixMultiply(matrix a, matrix b)

Arguments:

• matrix a: The first matrix to multiply
• matrix b: The second matrix to multiply

Description:

Returns a matrix that is the result of a * b.

Info

The order of matrices being multiplied is important, as a * b != b * a.

matrixRotate

Signature:

matrix matrixRotate(matrix m, vec3 rotation)

Arguments:

• matrix m: Input matrix
• vec3 rotation: Rotation vector

Description:

Returns the result of a combined ZYX rotation matrix multiplied by m.

matrixScale

Signature:

matrix matrixScale(matrix m, vec3 scale)

Arguments:

• matrix m: Input matrix
• vec3 scale: Scale vector

Description:

Returns the result of a XYZ scale matrix multiplied by m.

matrixSubtract

Signature:

matrix matrixSubtract(matrix a, matrix b)

Arguments:

• matrix a: The first matrix to subtract
• matrix b: The second matrix to subtract

Description:

Returns a matrix that is the result of a - b.

matrixTranslate

Signature:

matrix matrixTranslate(matrix m, vec3 translation)

Arguments:

• matrix m: Input matrix
• vec3 translation: Translation vector

Description:

Returns the result of a XYZ translation matrix multiplied by m.

matrixTranspose

Signature:

matrix matrixTranspose(matrix m)

Arguments:

• matrix m: The matrix to transpose

Description:

Returns the transposed matrix of m.

A transposed matrix is a matrix where its rows have been replaced by its columns.

For example, transposing the input matrix

matrix(
    0, 4, 8 , 12,
    1, 5, 9 , 13,
    2, 6, 10, 14,
    3, 7, 11, 15
)

returns the matrix

matrix(
    0 , 1 , 2 , 3 ,
    4 , 5 , 6 , 7 ,
    8 , 9 , 10, 11,
    12, 13, 14, 15
)

Input

getMouseDelta

Signature:

vec2 getMouseDelta()

Description:

Returns a 2D vector containing the distance the mouse has moved since the last frame.

getMouseDrag

Signature:

vec2 getMouseDrag(int button)

Arguments:

• int button: The mouse button to check [0-2]

Description:

Returns a 2D vector containing the distance the mouse has been dragged since the given mouse button was pressed.

button must be one of the following values:

Constant	Value
BTN_MOUSE_LEFT	0
BTN_MOUSE_RIGHT	1
BTN_MOUSE_MIDDLE	2

getMouseLock

Signature:

int getMouseLock()

Description:

Returns 1 if the mouse is currently locked. Otherwise, returns 0.

getMousePosition

Signature:

vec2 getMousePosition()

Description:

Returns a 2D vector containing the mouse's screen coordinates.

getMouseWheel

Signature:

int getMouseWheel()

Description:

Returns 1 if the mouse wheel is being scrolled up.

Returns -1 if the mouse wheel is being scrolled down.

Otherwise, returns 0.

held

Signature:

int held(int player, int button)

Arguments:

• int player: The player to check [0-3]
• int button: The button to check [0-13]

Description:

Returns 1 if the given player is holding the given button. Otherwise, returns 0.

button must be one of the following values:

Constant	Value
BTN_UP	0
BTN_DOWN	1
BTN_LEFT	2
BTN_RIGHT	3
BTN_TRIANGLE	4
BTN_CROSS	5
BTN_SQUARE	6
BTN_CIRCLE	7
BTN_L1	8
BTN_L2	9
BTN_R1	10
BTN_R2	11
BTN_SELECT	12
BTN_START	13

mouseDragging

Signature:

int mouseDragging(int button)

Arguments:

• int button: The mouse button to check [0-2]

Description:

Returns 1 if the given mouse button has been held for at least 1 frame, and the mouse has moved since being held.

Otherwise, returns 0.

button must be one of the following values:

Constant	Value
BTN_MOUSE_LEFT	0
BTN_MOUSE_RIGHT	1
BTN_MOUSE_MIDDLE	2

mouseHeld

Signature:

int mouseHeld(int button)

Arguments:

• int button: The mouse button to check [0-2]

Description:

Returns 1 if the given mouse button is being held.

Otherwise, returns 0.

button must be one of the following values:

Constant	Value
BTN_MOUSE_LEFT	0
BTN_MOUSE_RIGHT	1
BTN_MOUSE_MIDDLE	2

mousePressed

Signature:

int mousePressed(int button)

Arguments:

• int button: The mouse button to check [0-2]

Description:

Returns 1 if the given mouse button has been pressed this frame.

Otherwise, returns 0.

button must be one of the following values:

Constant	Value
BTN_MOUSE_LEFT	0
BTN_MOUSE_RIGHT	1
BTN_MOUSE_MIDDLE	2

mouseReleased

Signature:

int mouseReleased(int button)

Arguments:

• int button: The mouse button to check [0-2]

Description:

Returns 1 if the given mouse button has been released this frame.

Otherwise, returns 0.

button must be one of the following values:

Constant	Value
BTN_MOUSE_LEFT	0
BTN_MOUSE_RIGHT	1
BTN_MOUSE_MIDDLE	2

pressed

Signature:

int pressed(int player, int button)

Arguments:

• int player: The player to check [0-3]
• int button: The button to check [0-13]

Description:

Returns 1 if the given player has pressed the given button this frame.

Otherwise, returns 0.

button must be one of the following values:

Constant	Value
BTN_UP	0
BTN_DOWN	1
BTN_LEFT	2
BTN_RIGHT	3
BTN_TRIANGLE	4
BTN_CROSS	5
BTN_SQUARE	6
BTN_CIRCLE	7
BTN_L1	8
BTN_L2	9
BTN_R1	10
BTN_R2	11
BTN_SELECT	12
BTN_START	13

released

Signature:

int released(int player, int button)

Arguments:

• int player: The player to check [0-3]
• int button: The button to check [0-13]

Description:

Returns 1 if the given player has released the given button this frame.

Otherwise, returns 0.

button must be one of the following values:

Constant	Value
BTN_UP	0
BTN_DOWN	1
BTN_LEFT	2
BTN_RIGHT	3
BTN_TRIANGLE	4
BTN_CROSS	5
BTN_SQUARE	6
BTN_CIRCLE	7
BTN_L1	8
BTN_L2	9
BTN_R1	10
BTN_R2	11
BTN_SELECT	12
BTN_START	13

setMouseLock

Signature:

void setMouseLock(int lock)

Arguments:

• int lock: Mouse lock flag [true/false]

Description:

If lock is true, hides and locks the mouse to the screen.

If lock is false, shows and unlocks the mouse.

Graphics

ambientColor

Signature:

void ambientColor(int color)

Arguments:

• int color: The ambient light color to use (RGBA32 format)

Description:

Sets the current ambient lighting color.

ambientFactor

Signature:

void ambientFactor(float factor)

Arguments:

• float factor: Percentage of ambient light tinting [0.0-100.0]

Description:

Sets the current ambient light factor.

The ambient factor is the percentage of tinting that objects will recieve from ambient lighting.

beginMesh

Signature:

void beginMesh(int primitive)

Arguments:

• int primitive: The type of mesh primitive to construct [0-2]

Description:

Begins construction of a mesh using the given primitive type.

primitive must be one of the following values:

Constant	Value	Description
MESH_LINES	0	Construct line primitives (2 vertices each)
MESH_TRIANGLES	1	Construct triangle primitives (3 vertices each)
MESH_QUADS	2	Construct quad primitives (4 vertices each)

Must eventually be followed by a call to endMesh().

blendFactors

Signature:

void blendFactors(int src, int dest, int eq)

Arguments:

• int src: The new blending source factor to use [0-14]
• int dest: The new blending destination factor to use [0-14]
• int eq: The new blending equation to use [0-4]

Description:

Changes the current color blending factors and equations for both rgb and alpha.

Must be called before blendMode().

Blend mode must be set to BLEND_CUSTOM (6) after this call.

src and dest must be one of the following values:

Constant	Value
FACTOR_ZERO	0
FACTOR_ONE	1
FACTOR_SRC_RGB	2
FACTOR_ONE_MINUS_SRC_RGB	3
FACTOR_DST_RGB	4
FACTOR_ONE_MINUS_DST_RGB	5
FACTOR_SRC_ALPHA	6
FACTOR_ONE_MINUS_SRC_ALPHA	7
FACTOR_DST_ALPHA	8
FACTOR_ONE_MINUS_DST_ALPHA	9
FACTOR_CONSTANT_RGB	10
FACTOR_ONE_MINUS_CONSTANT_RGB	11
FACTOR_CONSTANT_ALPHA	12
FACTOR_ONE_MINUS_CONSTANT_ALPHA	13
FACTOR_SRC_ALPHA_SATURATE	14

eq must be one of the following values:

Constant	Value
EQ_ADD	0
EQ_SUBTRACT	1
EQ_SUBTRACT_REVERSE	2
EQ_MIN	3
EQ_MAX	4

blendFactorsEx

Signature:

void blendFactorsEx(int src_rgb, int dest_rgb, int src_alpha, int dest_alpha, int eq_rgb, int eq_alpha)

Arguments:

• int src_rgb: Blending source rgb factor to use [0-14]
• int dest_rgb: Blending destination rgb factor to use [0-14]
• int src_alpha: Blending source alpha factor to use [0-14]
• int dest_alpha: Blending destination alpha factor to use [0-14]
• int eq_rgb: Blending rgb equation to use [0-4]
• int eq_alpha: Blending alpha equation to use [0-4]

Description:

Changes the current blending factors and equations for rgb and alpha individually.

Must be called before blendMode().

Blend mode must be set to BLEND_CUSTOM_EX (7) after this call.

See blendFactors() for a list of factors and equations.

blendMode

Signature:

void blendMode(int mode)

Arguments:

• int mode: The new blending mode to use [0-7]

Description:

Changes the current color blending mode setting.

mode must be one of the following values:

Constant	Value
BLEND_ALPHA	0
BLEND_ADD	1
BLEND_MULTIPLY	2
BLEND_ADD_ALT	3
BLEND_SUBTRACT	4
BLEND_PREMULTIPLY	5
BLEND_CUSTOM	6
BLEND_CUSTOM_EX	7

camera2D

Signature:

void camera2D(int camera)

Arguments:

• int camera: Index of the 2D camera to use [0-3]

Description:

Configures the topmost matrix on the stack to match the view of the given 2D camera.

camera3D

Signature:

void camera3D(int camera)

Arguments:

• int camera: Index of the 3D camera to use [0-3]

Description:

Configures the topmost matrix on the stack to match the view of the given 3D camera.

Before the call to draw() each frame, an implicit call to camera3d(0) is made.

clear

Signature:

void clear(int flags)

Arguments:

• int flags: The buffers to clear

Description:

Clears the rendering buffers specified by flags.

flags is a 3-bit bitmask, each bit corresponding to a render buffer.

The following table lists built-in constants that can be used as flags values:

Constant	Value	Description
CLEAR_NONE	Binary: 0b000 (Decimal: 0)	Do not clear any buffers
CLEAR_COLOR	Binary: 0b100 (Decimal: 4)	Clear the color buffer (pixel buffer drawn to the screen)
CLEAR_DEPTH	Binary: 0b010 (Decimal: 2)	Clear the depth buffer (buffer containing each pixel's distance from the camera)
CLEAR_STENCIL	Binary: 0b001 (Decimal: 1)	Clear the stencil buffer (8-bit buffer used to mask to-be-drawn pixels)
CLEAR_ALL	Binary: 0b111 (Decimal: 7)	Clear all buffers

Constants can be bitwise OR'd to clear different combinations of buffers:

clear(CLEAR_DEPTH | CLEAR_STENCIL); // clear depth and stencil buffers, but not color

clearColor

Signature:

void clearColor(int color)

Arguments:

• int color: The new clear color to use. (RGBA32 format)

Description:

Sets the value to fill the color buffer with when clear() is called with the CLEAR_COLOR flag enabled.

The default clear color is black. (0x000000FF)

clearDepth

Signature:

void clearDepth(float depth)

Arguments:

• float depth: The new clear depth to use. [0.0-1.0]

Description:

Sets the value to fill the depth buffer with when clear() is called with the CLEAR_DEPTH flag enabled.

The default clear depth is 1.0.

clearStencil

Signature:

void clearStencil(int stencil)

Arguments:

• int stencil: The new clear stencil to use. [0x00-0xFF]

Description:

Sets the value to fill the stencil buffer with when clear() is called with the CLEAR_STENCIL flag enabled.

The default clear stencil is 0x00.

colorMask

Signature:

void colorMask(int flags)

Arguments:

• int flags: Color channel flags

Description:

Enables/disables writing to the color buffer on a per-channel basis.

flags is a 4-bit bitmask, each bit corresponding to a color channel.

The following table lists built-in constants that can be used as flags values:

Constant	Value	Description
COLOR_NONE	Binary: 0b0000 (Decimal: 0)	Disable all writing to the color buffer
COLOR_R	Binary: 0b1000 (Decimal: 8)	Enable writing the red color channel to the color buffer
COLOR_G	Binary: 0b0100 (Decimal: 4)	Enable writing the green color channel to the color buffer
COLOR_B	Binary: 0b0010 (Decimal: 2)	Enable writing the blue color channel to the color buffer
COLOR_A	Binary: 0b0001 (Decimal: 1)	Enable writing the alpha color channel to the color buffer
COLOR_ALL	Binary: 0b1111 (Decimal: 15)	Enable all writing to the color buffer

Constants can be bitwise OR'd to enable different combinations of channels:

colorMask(COLOR_R | COLOR_A); // write only to the red and alpha channels of the color buffer

cullMode

Signature:

void cullMode(int mode)

Arguments:

• int mode: The new face culling mode to use [0-2]`

Description:

Changes the current face culling mode setting.

mode must be one of the following values:

Constant	Value	Description
CULL_BACK	0	Cull backfaces
CULL_FRONT	1	Cull frontfaces
CULL_NONE	2	Disable face culling

depthFunc

Signature:

void depthFunc(int func)

Arguments:

• int func: The new depth function to use [0-7]

Description:

Sets the function used during depth testing.

func must be one of the following values:

Constant	Value	Description
FUNC_LESS	0	Depth test passes if new depth < current depth
FUNC_LEQUAL	1	Depth test passes if new depth <= current depth
FUNC_GREATER	2	Depth test passes if new depth > current depth
FUNC_GEQUAL	3	Depth test passes if new depth >= current depth
FUNC_EQUAL	4	Depth test passes if new depth == current depth
FUNC_NOTEQUAL	5	Depth test passes if new depth != current depth
FUNC_ALWAYS	6	Depth test always passes
FUNC_NEVER	7	Depth test never passes

depthMask

Signature:

void depthMask(int enable)

Arguments:

• int enable: Depth buffer writing flag [true/false]

Description:

Enables/disables writing to the depth buffer.

depthTest

Signature:

void depthTest(int enable)

Arguments:

• int enable: Depth testing flag [true/false]

Description:

Enables/disables depth testing.

drawObj

Signature:

void drawObj(int entry)

Arguments:

• int entry: OBJMAP entry to draw [0-511]

Description:

Renders the mesh defined by the OBJMAP entry at the index entry.

If the OBJMAP entry is configured to point to collision data, it will not be rendered.

drawObjEx

Signature:

void drawObjEx(int primitive, int start, int n)

Arguments:

• int primitive: The type of primitve to construct [0-2]
• int start: The index of the first vertex in OBJMEM to draw [0-98303]
• int n: The number of primitives to draw

Description:

Renders mesh data in OBJMEM according to the given parameters.

primitive must be one of the following values:

Constant	Value	Description
MESH_LINES	0	Construct line primitives (2 vertices each)
MESH_TRIANGLES	1	Construct triangle primitives (3 vertices each)
MESH_QUADS	2	Construct quad primitives (4 vertices each)

endMesh

Signature:

void endMesh()

Description:

Finalizes the construction of a mesh.

Must only be called after a matching call to beginMesh().

fogColor

Signature:

void fogColor(int color)

Arguments:

• int color: The fog color to use (RGBA32 format)

Description:

Sets the current fog tint color.

fogEnd

Signature:

void fogEnd(float end);

Arguments:

• float end: The distance from the camera where the fog ends. [0.0-1000.0]

Description:

Sets the fog end distance setting.

fogMode

Signature:

void fogMode(int enable)

Arguments:

• int enable: Fog enable flag [true/false]

Description:

Enables/disables fog.

If enable is true, fog rendering will be enabled.

Otherwise, fog rendering will be disabled.

Fog is rendered by fading the color of geometry to the set fog color.

The fog start setting determines how far from the camera the fade begins.

The fog end setting is the distance from the camera where objects will be fully tinted to the fog color.

fogStart

Signature:

void fogStart(float start);

Arguments:

• float start: The distance from the camera to start rendering fog. [0.0-1000.0]

Description:

Sets the fog starting distance setting.

frustum

Signature:

void frustum(float left, float right, float bottom, float top, float near, float far)

Arguments:

• float left: Minimum X coordinate of the near clipping plane
• float right: Maximum X coordinate of the near clipping plane
• float bottom: Minimum Y coordinate of the near clipping plane
• float top: Maximum Y coordinate of the near clipping plane
• float near: Near clipping plane distance
• float far: Far clipping plane distance

Description:

Configures the topmost matrix of the current matrix stack to a projection matrix describing a camera frustum (perpective projection).

getCam2D

Signature:

cam2d* getCam2D(int camera)

Arguments:

• int camera: Index of the 2D camera to get [0-3]

Description:

Returns a pointer to the given 2D camera.

getCam3D

Signature:

cam3d* getCam3D(int camera)

Arguments:

• int camera: Index of the 3D camera to get [0-3]

Description:

Returns a pointer to the given 3D camera.

getLight

Signature:

light* getLight(int light)

Arguments:

• int light: Index of the light to get [0-7]

Description:

Returns a pointer to the given light.

getModelViewMatrix

Signature:

matrix getModelViewMatrix()

Description:

Returns a copy of the topmost model-view matrix.

getProjectionMatrix

Signature:

matrix getProjectionMatrix()

Description:

Returns a copy of the topmost projection matrix.

getTopMatrix

Signature:

matrix getTopMatrix()

Description:

Returns a copy of the topmost matrix of the current matrix stack.

identity

Signature:

void identity()

Description:

Resets the topmost matrix of the current matrix stack to an identity matrix.

(a matrix with no transformations applied)

lightingMode

Signature:

void lightingMode(int mode)

Arguments:

• int mode: Lighting mode flag [true/false]

Description:

Enables/disables vertex lighting.

If mode is true, lighting will be enabled.

Otherwise, lighting will be disabled.

Vertex lighting changes vertex colors to simulate lighting.

When lighting is enabled, meshcolor() calls will be ignored.

Ambient lighting is also calculated when lighting is enabled.

Ambient lighting is a form of light that every object recieves equally.

lookAt

Signature:

void lookAt(vec3 eye, vec3 target, vec3 up)

Arguments:

• vec3 eye: Eye position
• vec3 target: Target position
• vec3 up: Up vector

Description:

Configures the topmost matrix of the current matrix stack to a view matrix describing a view from eye looking at target with an up vector of up.

matrixMode

Signature:

void matrixMode(int index)

Arguments:

• int index: Index of the matrix stack to use. [0-1]

Description:

Changes the current matrix stack used for matrix stack functions such as pushMatrix(), popMatrix(), translate(), etc.

index must be one of the following values:

Constant	Value	Description
MAT_PROJECTION	0	Switch to projection matrix stack
MAT_MODELVIEW	1	Switch to model-view matrix stack

meshColor

Signature:

void meshColor(int color)

Arguments:

• int color: The color to use for the current vertex (RGBA32 format)

Description:

Submits the tint color for the current mesh vertex.

Vertex colors can be used to tint the texture of a mesh, the colors of each vertex are blended across the mesh surface.

Vertex colors are multiplied with texture pixel colors, so a vertex color of pure white will result in the original pixel color.

If lighting is enabled, this function does nothing.

meshNormal

Signature:

void meshNormal(vec3 normal)

Arguments:

• vec3 normal: The 3D normal vector to use for the current vertex

Description:

Submits the 3D normal vector for the current mesh vertex.

The vector must be normalized. (normal must have a length of 1)

Normal vectors are used when calculating lighting.

A vertex with a normal vector pointing toward a light will recieve more light than one with a normal vector pointing away from the light.

If lighting is disabled, this function does nothing.

meshUV

Signature:

void meshUV(vec2 uv)

Arguments:

• vec2 uv: The 2D texture coordinates to use for the current vertex

Description:

Submits the 2D texture coordinates for the current mesh vertex.

(0.0, 0.0) corresponds to the top-left corner of the texture.

(1.0, 1.0) corresponds to the bottom-right corner of the texture.

The normal range for uv coordinates is (0.0, 0.0) to (1.0, 1.0),

Values outside the 0.0-1.0 range will be treated differently depending on the current texture mode. (see textureMode())

meshVertex

Signature:

void meshVertex(vec3 v)

Arguments:

• vec3 v: The 3D coordinates to use for the current vertex

Description:

Submits the 3D coordinates for the current mesh vertex and finalizes the vertex.

This function should be called after all other desired vertex properties

(uv, color, normal) have been submitted.

meshVertex2D

Signature:

void meshVertex2D(vec2 v)

Arguments:

• vec2 v: The 2D screen coordinates to use for the current vertex

Description:

Submits the 2D coordinates for the current mesh vertex and finalizes the vertex.

This function should be called after all other desired vertex properties

(uv, color, normal) have been submitted.

multiplyTopMatrix

Signature:

void multiplyTopMatrix(matrix m)

Arguments:

• matrix m: The matrix to multiply by

Description:

Multiplies the topmost matrix of the current stack by the given matrix.

ortho

Signature:

void ortho(float left, float right, float bottom, float top, float near, float far)

Arguments:

• float left: Minimum X coordinate of the near clipping plane
• float right: Maximum X coordinate of the near clipping plane
• float bottom: Minimum Y coordinate of the near clipping plane
• float top: Maximum Y coordinate of the near clipping plane
• float near: Near clipping plane distance
• float far: Far clipping plane distance

Description:

Configures the topmost matrix of the current matrix stack to a projection matrix describing an orthographic projection.

polygonMode

Signature:

void polygonMode(int mode)

Arguments:

• int mode: The new polygon mode to use [0-2]

Description:

Sets the polygon fill mode.

mode must be one of the following values:

Constant	Value	Description
POLY_POINT	0	Draw only polygon vertices as points
POLY_LINE	1	Draw polygons as wireframes
POLY_FILL	2	Draw filled polygons

popMatrix

Signature:

void popMatrix()

Description:

Pops the topmost matrix off of the current matrix stack.

print2D

Signature:

void print2D(int x, int y, int color, string fmt, ...)

Arguments:

• int x: Text screen x position
• int y: Text screen y position
• int color: The text color to use (RGBA32 format)
• string fmt: Format text string
• ...: Values to format

Description:

Prints a formatted text string to the screen.

The following table lists all supported format specifiers:

Format Specifier	Description
%%	Literal % character
%d or %i	Signed int value
%u	Unsigned int value
%f	float value
%x	Lowercase hexidecimal integer value (zero-padded)
%X	Uppercase hexidecimal integer value (zero-padded)
%v2	vec2 value
%v3	vec3 value

pushMatrix

Signature:

void pushMatrix()

Description:

Pushes a copy of the current matrix to the top of the current matrix stack.

rotate

Signature:

void rotate(vec3 v)

Arguments:

• vec3 v: The vector to rotate by

Description:

Rotates the topmost matrix of the current matrix stack by the 3D vector v.

Rotation angles must be in degrees.

scale

Signature:

void scale(vec3 v)

Arguments:

• vec3 v: The vector to scale by

Description:

Scales the topmost matrix of the current matrix stack by the 3D vector v.

scissor

Signature:

void scissor(int x, int y, int width, int height)

Arguments:

• int x: Scissor screen x position [0-639]
• int y: Scissor screen y position [0-359]
• int width: Scissor width [1-640]
• int height: Scissor height [1-360]

Description:

Restricts all rendering to the rectangle defined by x, y, width, and height.

Pixels outside of the rectangle will not be affected by any drawing commands.

scissorMode

Signature:

void scissorMode(int enable)

Arguments:

• int enable: Scissor test flag [true/false]

Description:

Enables/disables scissor testing.

setModelViewMatrix

Signature:

void setModelViewMatrix(matrix m)

Arguments:

• matrix m: The new matrix to use

Description:

Sets the topmost model-view matrix to the given matrix.

setProjectionMatrix

Signature:

void setProjectionMatrix(matrix m)

Arguments:

• matrix m: The new matrix to use

Description:

Sets the topmost projection matrix to the given matrix.

sprite2D

Signature:

void sprite2D(int src_x, int src_y, int src_w, int src_h, int dest_x, int dest_y)

Arguments:

• int src_x: Source X pixel coordinate
• int src_y: Source Y pixel coordinate
• int src_w: Source rectangle pixel width
• int src_h: Source rectangle pixel height
• int dest_x: Destination screen X coordinate
• int dest_y: Destination screen Y coordinate

Description:

Draws a 2D rectangular portion of TEXMEM to the screen.

sprite2DEx

Signature:

void sprite2DEx(int src_x, int src_y, int src_w, int src_h, int dest_x, int dest_y, int dest_w, int dest_h)

Arguments:

• int src_x: Source X pixel coordinate
• int src_y: Source Y pixel coordinate
• int src_w: Source rectangle pixel width
• int src_h: Source rectangle pixel height
• int dest_x: Destination screen X coordinate
• int dest_y: Destination screen Y coordinate
• int dest_w: Destination screen rectangle width
• int dest_h: Destination screen rectangle height

Description:

Draws a 2D rectangular portion of TEXMEM to the screen, scaled to the given destination rectangle.

stencilFunc

Signature:

void stencilFunc(int face, int func, int ref, int mask)

Arguments:

• int face: The face value to configure [0-2]
• int func: The comparison function to use [0-7]
• int ref: Reference stencil value for comparison [0x00-0xFF]
• int mask: Mask value ANDed with ref and the stored stencil value during the test [0x00-0xFF]

Description:

Sets the stencil comparison function to use for the given face value.

face must be one of the following values:

Constant	Value	Description
FACE_FRONT	0	Configure front face stencil function
FACE_BACK	1	Configure back face stencil function
FACE_BOTH	2	Configure front and back face stencil functions

func must be one of the following values:

(stencil is the value currently in the stencil buffer when the test is made.)

Constant	Value	Description
FUNC_LESS	0	Stencil test passes if ( ref & mask ) < ( stencil & mask )
FUNC_LEQUAL	1	Stencil test passes if ( ref & mask ) <= ( stencil & mask )
FUNC_GREATER	2	Stencil test passes if ( ref & mask ) > ( stencil & mask )
FUNC_GEQUAL	3	Stencil test passes if ( ref & mask ) >= ( stencil & mask )
FUNC_EQUAL	4	Stencil test passes if ( ref & mask ) = ( stencil & mask )
FUNC_NOTEQUAL	5	Stencil test passes if ( ref & mask ) != ( stencil & mask )
FUNC_ALWAYS	6	Stencil test always passes
FUNC_NEVER	7	Stencil test never passes

stencilMask

Signature:

void stencilMask(int face, int mask)

Arguments:

• int face: The face value to configure [0-2]
• int mask: Mask value used to enable/disable writing to specific bits in the stencil buffer [0x00-0xFF]

Description:

Confgures a mask used to enable/disable writing to specific bits in the stencil buffer for the given face value.

face must be one of the following values:

Constant	Value	Description
FACE_FRONT	0	Configure front face stencil mask
FACE_BACK	1	Configure back face stencil mask
FACE_BOTH	2	Configure front and back face stencil masks

A mask of 0x00 will prevent any writing to the stencil buffer.

A mask of 0xFF will allow all writing to the stencil buffer.

stencilMode

Signature:

void stencilMode(int enable)

Arguments:

• int enable: Stencil testing flag [true/false]

Description:

Enables/disables stencil testing.

stencilOp

Signature:

void stencilOp(int face, int sfail, int dpfail, int dppass)

Arguments:

• int face: The face value to configure [0-2]
• int sfail: The operation to perform when the stencil test fails [0-7]
• int dpfail: The operation to perform when the stencil test passes, but the depth test fails [0-7]
• int dppass: The operation to perform when both the stencil test and depth test pass, or the stencil test passes and depth testing is disabled [0-7]

Description:

Sets the operation to perform on the stencil buffer when the stencil test is performed.

face must be one of the following values:

Constant	Value	Description
FACE_FRONT	0	Configure front face stencil operation
FACE_BACK	1	Configure back face stencil operation
FACE_BOTH	2	Configure front and back face stencil operations

sfail, dpfail, and dppass must be one of the following values:

Constant	Value	Description
STENCIL_KEEP	0	Keeps the current stencil value
STENCIL_REPLACE	1	Sets the stencil buffer value to ref, as specified by stencilFunc()
STENCIL_INC	2	Increments the current stencil buffer value, clamps to 0xFF
STENCIL_INC_WRAP	3	Increments the current stencil buffer value, wraps around to 0 when incrementing the value 0xFF
STENCIL_DEC	4	Decrements the current stencil buffer value, clamps to 0
STENCIL_DEC_WRAP	5	Decrements the current stencil buffer value, wraps around to 0xFF when decrementing the value 0
STENCIL_ZERO	6	Sets the stencil buffer value to 0
STENCIL_INVERT	7	Bitwise inverts the current stencil buffer value

texture

Signature:

void texture(int x, int y, int width, int height)

Arguments:

• int x: Texture window x position [0-1023]
• int y: Texture window y position [0-1023]
• int width: Texture window width [1-256]
• int height: Texture window height [1-256]

Description:

Changes the window of texture memory to use as the current texture.

A maximum texture size of 256x256 can be specified.

Texture UV coordinates will be mapped to the specified texture window.

textureMode

Signature:

void textureMode(int mode)

Arguments:

• int mode: The new texture mode to use [0-2]

Description:

Changes the current texture mode setting.

mode must be one of the following values:

Constant	Value	Description
TEXTURE_WRAP	0	Repeat texture (default)
TEXTURE_CLAMP	1	Clamp texture to edges
TEXTURE_NONE	2	Disable texturing

Modes TEXTURE_WRAP and TEXTURE_CLAMP determine whether UVs outside of the 0.0-1.0 range will cause the texture to be repeated accross a surface, or if UVs should be clamped to the 0.0-1.0 range.

Mode TEXTURE_NONE will ignore texture pixel colors and output pure white instead. useful when used with vertex colors.

translate

Signature:

void translate(vec3 v)

Arguments:

• vec3 v: The vector to translate by

Description:

Translates the topmost matrix of the current matrix stack by the 3D vector v.

viewport

Signature:

void viewport(int x, int y, int width, int height)

Arguments:

• int x: Viewport screen x position [0-639]
• int y: Viewport screen y position [0-359]
• int width: Viewport width [1-640]
• int height: Viewport height [1-360]

Description:

Defines the tranformation of coordinates of pixels to render into screen coordinates.

By default, pixels are rendered at 1:1 screen coordinates, but this function allows rendering output to be scaled to the rectangle defined by x, y, width, and height.

Audio

getTrackBPM

Signature:

int getTrackBPM(int track)

Arguments:

• int track: Index of the track to query [0-7]

Description:

Returns the current BPM value of the given soundchip track.

getTrackPan

Signature:

int getTrackPan(int track)

Arguments:

• int track: Index of the track to query [0-7]

Description:

Returns the current panning value of the given soundchip track.

getTrackVolume

Signature:

int getTrackVolume(int track)

Arguments:

• int track: Index of the track to query [0-7]

Description:

Returns the current volume of the given soundchip track.

muteTrack

Signature:

void muteTrack(int track)

Arguments:

• int track: Index of the track to mute [0-7]

Description:

Mutes the given soundchip track.

muteTracks

Signature:

void muteTracks(int track_mask)

Arguments:

• int track_mask: Bitmask of the tracks to mute

Description:

Mutes the given soundchip tracks.

track_mask is an 8-bit bitmask, each bit corresponding to a soundchip track.

The following table lists the values that map to each track:

Mask Value	Track Index
Binary: 0b10000000 (Decimal: 128)	0
Binary: 0b01000000 (Decimal: 64)	1
Binary: 0b00100000 (Decimal: 32)	2
Binary: 0b00010000 (Decimal: 16)	3
Binary: 0b00001000 (Decimal: 8)	4
Binary: 0b00000100 (Decimal: 4)	5
Binary: 0b00000010 (Decimal: 2)	6
Binary: 0b00000001 (Decimal: 1)	7

pauseTrack

Signature:

void pauseTrack(int track)

Arguments:

• int track: Index of the track to pause [0-7]

Description:

Pauses the given soundchip track.

pauseTracks

Signature:

void pauseTracks(int track_mask)

Arguments:

• int track_mask: Bitmask of the tracks to pause

Description:

Pauses the given soundchip tracks.

track_mask is an 8-bit bitmask, each bit corresponding to a soundchip track.

The following table lists the values that map to each track:

Mask Value	Track Index
Binary: 0b10000000 (Decimal: 128)	0
Binary: 0b01000000 (Decimal: 64)	1
Binary: 0b00100000 (Decimal: 32)	2
Binary: 0b00010000 (Decimal: 16)	3
Binary: 0b00001000 (Decimal: 8)	4
Binary: 0b00000100 (Decimal: 4)	5
Binary: 0b00000010 (Decimal: 2)	6
Binary: 0b00000001 (Decimal: 1)	7

playPattern

Signature:

void playPattern(int track, int pattern)

Arguments:

• int track: Index of the track to play on [0-7]
• int pattern: Index of the pattern to play [0x00-0xFF]

Description:

Plays the given sequencer pattern using the given soundchip track.

playSong

Signature:

void playSong(int row)

Arguments:

• int row: Index of the song row to play from [0x00-0xFF]

Description:

Plays all tracks starting at the given song row.

playTrack

Signature:

void playTrack(int track, int row)

Arguments:

• int track: Index of the track to play [0-7]
• int row: Index of the song row to play from [0x00-0xFF]

Description:

Plays the given soundchip track starting at the given song row.

playWav

Signature:

void playWav(int track, int id, int note, float volume, int loop_mode)

Arguments:

• int track: Index of the track to play on [0-7]
• int id: Index of the WAVMAP entry to play [0-511]
• int note: Note value to play the wave at
• float volume: Volume percentage to play the wave at [0.0-100.0]
• int loop_mode: Loop mode to use when playing [0-3]

Description:

Plays the sound described by a WAVMAP entry.

loop_mode must be one of the following values:

Constant	Value	Description
LOOP_OFF	0	Do not loop
LOOP_FORWARD	1	Loop from the beginning of the wave
LOOP_PINGPONG	2	Alternate between playing the wave forwards and backwards
LOOP_RANGE	3	Loop using the sample range specified in the WAVMAP entry

playWavEx

Signature:

void playWavEx(int track, int sample_start, int sample_end, int loop_start, int loop_end, int note, float volume, int loop_mode)

Arguments:

• int track: Index of the track to play on [0-7]
• int sample_start: Index of the WAVMEM sample pair that marks the beginning of the sound [0x000000-0x1BFFFF]
• int sample_end: Index of the WAVMEM sample pair that marks the end of the sound (inclusive) [0x000000-0x1BFFFF]
• int loop_start: Index of the WAVMEM sample pair that marks the beginning loop point [0x000000-0x1BFFFF]
• int loop_end: Index of the WAVMEM sample pair that marks the end loop point (inclusive) [0x000000-0x1BFFFF]
• int note: Note value to play the wave at (0nC4 is the default pitch)
• float volume: Volume percentage to play the wave at [0.0-100.0]
• int loop_mode: Loop mode to use when playing [0-3]

Description:

Plays a given range of samples from WAVMEM.

loop_mode must be one of the following values:

Constant	Value	Description
LOOP_OFF	0	Do not loop
LOOP_FORWARD	1	Loop from the beginning of the wave
LOOP_PINGPONG	2	Alternate between playing the wave forwards and backwards
LOOP_RANGE	3	Loop using the sample range specified by loop_start and loop_end

resumeTrack

Signature:

void resumeTrack(int track)

Arguments:

• int track: Index of the track to resume [0-7]

Description:

Resumes the given soundchip track.

resumeTracks

Signature:

void resumeTracks(int track_mask)

Arguments:

• int track_mask: Bitmask of the tracks to resume

Description:

Resumes the given soundchip tracks.

track_mask is an 8-bit bitmask, each bit corresponding to a soundchip track.

The following table lists the values that map to each track:

Mask Value	Track Index
Binary: 0b10000000 (Decimal: 128)	0
Binary: 0b01000000 (Decimal: 64)	1
Binary: 0b00100000 (Decimal: 32)	2
Binary: 0b00010000 (Decimal: 16)	3
Binary: 0b00001000 (Decimal: 8)	4
Binary: 0b00000100 (Decimal: 4)	5
Binary: 0b00000010 (Decimal: 2)	6
Binary: 0b00000001 (Decimal: 1)	7

setTrackBPM

Warning

This function is not fully implemented, and will have no effect.

Signature:

void setTrackBPM(int track, int bpm)

Arguments:

• int track: Index of the track to modify [0-7]
• int bpm: New BPM value to play at [1-255]

Description:

Sets the BPM value of the given soundchip track.

setTrackPan

Signature:

void setTrackPan(int track, int pan)

Arguments:

• int track: Index of the track to modify [0-7]
• int pan: New panning value to play at [-100-100]

Description:

Sets the panning value of the given soundchip track.

setTrackVolume

Signature:

void setTrackVolume(int track, int volume)

Arguments:

• int track: Index of the track to modify [0-7]
• int volume: New volume value to play at [0x00-0xFF]

Description:

Sets the volume value of the given soundchip track.

stopTrack

Signature:

void stopTrack(int track)

Arguments:

• int track: Index of the track to stop [0-7]

Description:

Stops the given soundchip track.

stopTracks

Signature:

void stopTracks(int track_mask)

Arguments:

• int track_mask: Bitmask of the tracks to stop

Description:

Stops the given soundchip tracks.

track_mask is an 8-bit bitmask, each bit corresponding to a soundchip track.

The following table lists the values that map to each track:

Mask Value	Track Index
Binary: 0b10000000 (Decimal: 128)	0
Binary: 0b01000000 (Decimal: 64)	1
Binary: 0b00100000 (Decimal: 32)	2
Binary: 0b00010000 (Decimal: 16)	3
Binary: 0b00001000 (Decimal: 8)	4
Binary: 0b00000100 (Decimal: 4)	5
Binary: 0b00000010 (Decimal: 2)	6
Binary: 0b00000001 (Decimal: 1)	7

unmuteTrack

Signature:

void unmuteTrack(int track)

Arguments:

• int track: Index of the track to unmute [0-7]

Description:

Unmutes the given soundchip track.

unmuteTracks

Signature:

void unmuteTracks(int track_mask)

Arguments:

• int track_mask: Bitmask of the tracks to unmute

Description:

Unmutes the given soundchip tracks.

track_mask is an 8-bit bitmask, each bit corresponding to a soundchip track.

The following table lists the values that map to each track:

Mask Value	Track Index
Binary: 0b10000000 (Decimal: 128)	0
Binary: 0b01000000 (Decimal: 64)	1
Binary: 0b00100000 (Decimal: 32)	2
Binary: 0b00010000 (Decimal: 16)	3
Binary: 0b00001000 (Decimal: 8)	4
Binary: 0b00000100 (Decimal: 4)	5
Binary: 0b00000010 (Decimal: 2)	6
Binary: 0b00000001 (Decimal: 1)	7

Physics

collide

Signature:

int collide(void* a, void* b)

Arguments:

• void* a: Pointer to the first collision object to test
• void* b: Pointer to the second collision object to test

Description:

Returns true if a is colliding with b. Otherwise, returns false.

Warning

Collision detection is currently only implemented for colaabb vs colaabb.

getRaycastNormal

Warning

This function is not currently implemented.

getRaycastPoint

Warning

This function is not currently implemented.

raycast

Warning

This function is not currently implemented.

Memory

alloc

Signature:

void* alloc(int size)

Arguments:

• int size: The amount of bytes to allocate

Description:

Allocates a heap memory block of at least size bytes and returns its address.

Returns null if the allocation fails.

free

Signature:

void free(void* block)

Arguments:

• void* block: Pointer to the block to free

Description:

Deallocates a heap memory block if block points to a block previously allocated by alloc().

free(null) does nothing.

getObjEntry

Signature:

objentry* getObjEntry(int index)

Arguments:

• int index: Index of the entry to get a pointer to [0-511]

Description:

Returns a pointer to the given OBJMAP entry.

getWavEntry

Signature:

waventry* getWavEntry(int index)

Arguments:

• int index: Index of the entry to get a pointer to [0-511]

Description:

Returns a pointer to the given WAVMAP entry.

initMemCard

Signature:

void initMemCard(string id)

Arguments:

• string id: Unique identifier for memory card data

Description:

Initializes the system's memory card memory range.

id is a string used to identify saved memory card data.

id must be between 1 and 16 characters long and may only contain the characters a-z, A-Z, 0-9, and _

If save data matching the given ID exists, it will be loaded.

loadObjBank

Signature:

void loadObjBank(int bank)

Arguments:

• int bank: Index of the object bank to load [0-3]

Description:

Loads an OBJBANK from the cartridge into OBJMEM.

loadSeqBank

Signature:

void loadSeqBank(int bank)

Arguments:

• int bank: Index of the sequencer bank to load [0-7]

Description:

Loads a SEQBANK from the cartridge into SEQMEM.

loadTexBank

Signature:

void loadTexBank(int bank)

Arguments:

• int bank: Index of the texture bank to load [0-3]

Description:

Loads a TEXBANK from the cartridge into TEXMEM.

loadWavBank

Signature:

void loadWavBank(int bank)

Arguments:

• int bank: Index of the wave bank to load [0-1]

Description:

Loads a WAVBANK from the cartridge into WAVMEM.

memcpy

Signature:

void memcpy(void* destination, void* source, int n)

Arguments:

• void* destination: The memory address to write to
• void* source: The memory address to read from
• int n: The amount of bytes to read

Description:

Copies n bytes from source to destination.

source and destination buffers may safely overlap.

memset

Signature:

void memset(void* destination, int n, int value)

Arguments:

• void* destination: The memory address to write to
• int n: The amount of bytes to write
• int value: Byte value to write [0-255]

Description:

Copies the given byte value to the first n bytes starting at destination.

peek8

Signature:

int peek8(void* address)

Arguments:

• void* address: Memory address to read from

Description:

Returns the byte at the given memory address.

peek32

Signature:

int peek32(void* address)

Arguments:

• void* address: Memory address to read from

Description:

Returns the 32-bit integer value starting at the given memory address.

peekf

Signature:

float peekf(void* address)

Arguments:

• void* address: Memory address to read from

Description:

Returns the float value starting at the given memory address.

poke8

Signature:

void poke8(void* address, int value)

Arguments:

• void* address: Memory address to write to
• int value: Byte value to write [0-255]

Description:

Writes a byte to the given memory address.

poke32

Signature:

void poke32(void* address, int value)

Arguments:

• void* address: Memory address to write to
• int value: 32-bit integer value to write

Description:

Writes a 32-bit integer to the given memory address.

pokef

Signature:

void pokef(void* address, float value)

Arguments:

• void* address: Memory address to write to
• float value: float value to write

Description:

Writes a float to the given memory address.

realloc

Signature:

void* realloc(void* block, int size)

Arguments:

• void* block: Pointer to the block to reallocate
• int size: The new amount of bytes to allocate

Description:

Reallocates the heap memory block pointed to by block to at least size bytes and returns its address.

The contents of block are copied to the newly allocated block.

Returns null if the reallocation fails.

strcat

Signature:

string strcat(string a, string b)

Arguments:

• string a: First string to concatenate
• string b: Second string to concatenate

Description:

Returns a new string containing the contents of a concatenated with the contents of b.

A heap memory block is allocated to contain the new string.

If allocation fails, returns a string with the value string(0, null).

strdup

Signature:

string strdup(string s)

Arguments:

• string s: The string to duplicate

Description:

Returns a new string containing a copy of the contents of s.

A heap memory block is allocated to contain the new string.

If allocation fails, returns a string with the value string(0, null).

Misc

time

Signature:

float time()

Description:

Returns the number of seconds that the current cart has been running.

vargc

Signature:

int vargc()

Description:

Returns the remaining number of vararg bytes for a vararg function.

Must only be called from a vararg function.

vargv

Signature:

void* vargv(int offset)

Arguments:

• int offset: The number of bytes to advance the vararg pointer

Description:

Returns a pointer to the current vararg argument and advances the vararg pointer by $offset bytes.

Must only be called from a vararg function.