PixToy

Getting Started

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.

Overview

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.

Website Layout

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!

Program Structure

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).

Color Palette

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!

API Reference

Globals

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.

Drawing

clrs(c)

Arguments

c	clear color (palette index 0-15)

Returns

None

Description

Clears the entire screen with the specified color.

pset(x,y,c)

Arguments

x	x coordinate
y	y coordinate
c	pixel color (palette index 0-15)

Returns

None

Description

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

pget(x,y) => c

Arguments

x	x coordinate
y	y coordinate

Returns

c	pixel color (palette index 0-15)

Description

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

line(x1,y1,x2,y2,c)

Arguments

x1	start x coordinate
y1	start y coordinate
x2	end x coordinate
y2	end y coordinate
c	draw color (palette index 0-15)

Returns

None

Description

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

recto(x,y,w,h,c)

Arguments

x	x coordinate
y	y coordinate
w	width
h	height
c	draw color (palette index 0-15)

Returns

None

Description

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

rectf(x,y,w,h,c)

Arguments

x	x coordinate
y	y coordinate
w	width
h	height
c	draw color (palette index 0-15)

Returns

None

Description

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

circo(x,y,r,t,c)

Arguments

x	x coordinate
y	y coordinate
r	radius
t	thickness
c	draw color (palette index 0-15)

Returns

None

Description

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

circf(x,y,r,c)

Arguments

x	x coordinate
y	y coordinate
r	radius
c	draw color (palette index 0-15)

Returns

None

Description

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

text(x,y,t,c)

Arguments

x	x coordinate
y	y coordinate
t	text
c	draw color (palette index 0-15)

Returns

None

Description

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).

Math

abs(x) => y

Arguments

x	number to operate on

Returns

y	absolute value of x

Description

Returns the absolute value of the argument x.

acos(x) => y

Arguments

x	number to operate on

Returns

y	arc cosine of x

Description

Returns the arc cosine of the argument x.

asin(x) => y

Arguments

x	number to operate on

Returns

y	arc sine of x

Description

Returns the arc sine of the argument x.

atan(y[,x]) => z

Arguments

y	the y coordinate
x	the x coordinate

Returns

z	arc tangent of y/x

Description

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.

round(x) => y

Arguments

x	number to round

Returns

y	rounded value of x

Description

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.

ceil(x) => y

Arguments

x	number to round

Returns

y	rounded value of x

Description

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

floor(x) => y

Arguments

x	number to round

Returns

y	rounded value of x

Description

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

deg(r) => d

Arguments

r	radians to convert

Returns

d	r converted to degrees

Description

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

rad(d) => r

Arguments

d	degrees to convert

Returns

r	d converted to radians

Description

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

exp(x) => y

Arguments

x	number to operate on

Returns

y	exponential of x

Description

Calculates the base-e exponential of the value x.

fmod(n,d) => r

Arguments

n	numerator
d	denominator

Returns

r	remainder of n/d

Description

Returns the remainder of the operation n/d.

modf(x) => i,f

Arguments

x	number to operate on

Returns

i	integeral part of x
f	fractional part of x

Description

Splits x into its separate integral and fractional components.

log(x) => y

Arguments

x	number to operate on

Returns

y	logarithm of x

Description

Calculates the base-e logarithm of the value x.

min(a,b) => c

Arguments

a	first number
b	second number

Returns

c	smallest of the two arguments

Description

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

max(a,b) => c

Arguments

a	first number
b	second number

Returns

c	largest of the two arguments

Description

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

sqrt(x) => y

Arguments

x	number to operate on

Returns

y	square root of x

Description

Calculates the square root of the value x.

cos(x) => y

Arguments

x	number to operate on

Returns

y	cosine of x

Description

Returns the cosine of the argument x.

sin(x) => y

Arguments

x	number to operate on

Returns

sine of x

Description

Returns the sine of the argument x.

tan(x) => y

Arguments

x	number to operate on

Returns

y	tangent of x

Description

Returns the tangent of the argument x.

clamp(x,l,u) => y

Arguments

x	value to clamp
l	lower bound
u	upper bound

Returns

y	clamped value

Description

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.

Random

seed([x])

Arguments

x	new seed value

Returns

None

Description

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.

rand([x[,y]]) => z

Arguments

x	lower/upper bound
y	upper bound

Returns

z	random number

Description

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.

Bitwise

band(a,b) => c

Arguments

a	first integer number
b	second integer number

Returns

c	result of a AND b

Description

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.

bor(a,b) => c

Arguments

a	first integer number
b	second integer number

Returns

c	result of a OR b

Description

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.

bxor(a,b) => c

Arguments

a	first integer number
b	second integer number

Returns

c	result of a XOR b

Description

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.

bnot(x) => y

Arguments

x	an integer number

Returns

y	result of NOT x

Description

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.

Misc

chr(x) => c

Arguments

x	a numeric ASCII code

Returns

c	character representation of x

Description

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