This document will walk-through what PIXTOY is and how to get started using it! Further below is a detailed reference outlining all of the globals and functions available in PIXTOY.

To get started, PIXTOY is a fun and simple web toy for creating miniature pixelated graphics effects using the Lua programming language. The app exposes a small set of simple primitive drawing functions, as well as some other utility functions (maths, bitwise ops, etc.) to allow for the creation of these effects. This guide will not explain the Lua programming language, as it is outside of the scope of this document. However, if you wish to learn, we recommend checking out the official Lua Getting Started page for that! It is a very simple language (especially in the context of PIXTOY) and very fun to learn and use.

When you first arrive at the PIXTOY homepage you will be greeted with a screen that looks somewhat like this:

This is where you will be developing your PIXTOY creations! On the right is the text editor that is used to write the Lua code for the program. On the left is the screen that will show the output of your app. Above and below are control bars containing various actions; the top bar contains navigation links, and the bottom bar contains controls for the PIXTOY app. The start/pause button, as the name implies, can be used to control the playback of your app in case you want to pause or resume it at anytime. The reset button will rebuild the code, with any changes you've made, and restart the program from the beginning.

Get familiar with this workspace and play around with the buttons, once you're ready we can start writing some actual code!

Here is a breakdown of the basic structure of a PIXTOY program:

Neither of these components are mandatory, you could write a program that just runs through once to draw a scene and does not need a DRAW function; or you could write a program that only uses a DRAW function and never has any startup code - it's entirely up to you!

It is worth nothing that, unlike normal Lua, PIXTOY does not care about case-sensitivity, this is done to make things a bit simpler (and because the font of PIXTOY, Emulogic, is all uppercase anyway).

PIXTOY has a number of drawing functions available for creating interesting visuals, all of these functinos do not take in colors how you might expect. For example calling CLRS to clear the screen with a value of 6 will result in the screen being filled with this green color:

Why is this? It is because PIXTOY uses a color palette! There are 16 unique colors available in PIXTOY, each mapping to a number from 0-15, you can use these different colors in any of the draw functions by simply passing in the associated number. Here is a handy reference of all the colors in PIXTOY and what numbers they map to:

It's worth mentioning that the palette used by PIXTOY is Sweetie 16 by Grafxkid!

Contains the width of the screen in pixels (always 128).

Contains the height of the screen in pixels (always 128).

Return the total elapsed time in seconds since the program started.

Returns the delta time for the current draw frame.

c | clear color (palette index 0-15) |

None |

Clears the entire screen with the specified color.

x | x coordinate |

y | y coordinate |

c | pixel color (palette index 0-15) |

None |

Sets the pixel at x,y to the specified color.

x | x coordinate |

y | y coordinate |

c | pixel color (palette index 0-15) |

Gets the color value at the pixel coordinate x,y.

x1 | start x coordinate |

y1 | start y coordinate |

x2 | end x coordinate |

y2 | end y coordinate |

c | draw color (palette index 0-15) |

None |

Draws a line starting at x1,y1 and ending at x2,y2, in the specified color.

x | x coordinate |

y | y coordinate |

w | width |

h | height |

c | draw color (palette index 0-15) |

None |

Draws a box outline of size w,h at coordinates x,y in the specified color.

x | x coordinate |

y | y coordinate |

w | width |

h | height |

c | draw color (palette index 0-15) |

None |

Draws a filled box of size w,h at coordinates x,y in the specified color.

x | x coordinate |

y | y coordinate |

r | radius |

t | thickness |

c | draw color (palette index 0-15) |

None |

Draws a circle outline centered at x,y in the specified color.

x | x coordinate |

y | y coordinate |

r | radius |

c | draw color (palette index 0-15) |

None |

Draws a filled circle centered at x,y in the specified color.

x | x coordinate |

y | y coordinate |

t | text |

c | draw color (palette index 0-15) |

None |

Draws the desired text starting at x,y in the specified color. Use the special character '\n' to insert new lines and the special character '\t' to insert tabs (tabs are output with a width of two characters).

x | number to operate on |

y | absolute value of x |

Returns the absolute value of the argument x.

x | number to operate on |

y | arc cosine of x |

Returns the arc cosine of the argument x.

x | number to operate on |

y | arc sine of x |

Returns the arc sine of the argument x.

y | the y coordinate |

x | the x coordinate |

z | arc tangent of y/x |

Returns the arc tangent of y/x. If the optional x parameter is not provided then the x value is automatically filled in equal to 1.

x | number to round |

y | rounded value of x |

Returns the result of rounding x to the nearest whole number. If the decimal portion of x is less than 0.5 then the value will be rounded down otherwise the value will be rounded up.

x | number to round |

y | rounded value of x |

Returns the result of rounding x up to the nearest whole number.

x | number to round |

y | rounded value of x |

Returns the result of rounding x down to the nearest whole number.

r | radians to convert |

d | r converted to degrees |

Converts the radians value r to the equivalent value in degrees.

d | degrees to convert |

r | d converted to radians |

Converts the degrees value d to the equivalent value in radians.

x | number to operate on |

y | exponential of x |

Calculates the base-e exponential of the value x.

n | numerator |

d | denominator |

r | remainder of n/d |

Returns the remainder of the operation n/d.

x | number to operate on |

i | integeral part of x |

f | fractional part of x |

Splits x into its separate integral and fractional components.

x | number to operate on |

y | logarithm of x |

Calculates the base-e logarithm of the value x.

a | first number |

b | second number |

c | smallest of the two arguments |

Takes in arguments a,b and returns the smaller of the two values.

a | first number |

b | second number |

c | largest of the two arguments |

Takes in arguments a,b and returns the larger of the two values.

x | number to operate on |

y | square root of x |

Calculates the square root of the value x.

x | number to operate on |

y | cosine of x |

Returns the cosine of the argument x.

x | number to operate on |

y | sine of x |

Returns the sine of the argument x.

x | number to operate on |

y | tangent of x |

Returns the tangent of the argument x.

x | value to clamp |

l | lower bound |

u | upper bound |

y | clamped value |

Returns the value of x clamped within the lower and upper bounds. If x is greater than the upper bound, then h is returned. If x is lower than the lower bound then l is returned. Otherwise x is returned unchanged.

x | new seed value |

None |

Calculates a new random number generation seed. If x is provided then that value becomes the new seed. If no arguments are provided then the current time is used as the new seed value.

x | lower/upper bound |

y | upper bound |

z | random number |

Generates a new random number within the specified range. If no arguments are provided then a random value between 0 and the maximum random value will be generated. If just x is provided then a random number will be generated between 0 and x. If x,y is provided then a random number will be generated between x and y.

a | first integer number |

b | second integer number |

c | result of a AND b |

Takes the arguments a,b and returns the result of performing the bitwise AND operation on the two values. Both arguments are expected to be integers, if either is not their decimal value will be truncated.

a | first integer number |

b | second integer number |

c | result of a OR b |

Takes the arguments a,b and returns the result of performing the bitwise OR operation on the two values. Both arguments are expected to be integers, if either is not their decimal value will be truncated.

a | first integer number |

b | second integer number |

c | result of a XOR b |

Takes the arguments a,b and returns the result of performing the bitwise XOR operation on the two values. Both arguments are expected to be integers, if either is not their decimal value will be truncated.

x | an integer number |

y | result of NOT x |

Takes the argument x and returns the result of performing the bitwise NOT operation on the value. The argument is expected to be an integer, if it is not then its decimal value will be truncated.

x | a numeric ASCII code |

c | character representation of x |

Converts the ASCII code x to its character representation and returns it.