Getting Started

What is Pi.js?

Pi.js is a JavaScript library that provides easy-to-use functions for building games and other graphical applications. It also includes support for sound and input, including mouse, keyboard, and gamepads. Inspired by the QBasic programming language, Pi.js offers a simple and intuitive interface for creating interactive experiences.

Check out the Pi.js reference for a detailed listing of all the functions including runnable examples for each function.

How to get started?

You can try it out online with one of Pi.js’ online editors.

Playground – A simple online code editor that allows you to try out Pi.js online.
Pi Editor – A more advanced online code editor that lets you upload image and sound files so you can build more advanced Pi.js projects and automatically saves your project to your local system.

Library Downloads

You can download the latest version of Pi.js from our download page. Or link directly to a CDN. See the download page for available versions and CDN links.

Pi.js Essentials

Pi.js can be broken down into three main subjects.

Graphics – Pi.js can create screens and provides a variety of tools for drawing graphics. This includes functions for drawing images and sprites, primitive shapes, lines, and other graphical functions.
Sound – You can dynamically generate music from a string of text, load and play music from files, or generate sounds and beeps by specifying the sound parameters.
Input – Pi.js has a comprehensive set of functions to help make getting input from users fun and easy. This includes input for mouse, keyboard, and gamepads.

Quick Start

Simply copy the code below and save it as index.html, and you are good to go. Although most likely you will want to run on a local server to be able to fully utilize all of Pi.js. This example creates a 320×200 screen and draws a diagonal line.

<!doctype html>
<html lang="en">
<head>
	<meta charset="utf-8">
	<title>Pi.js Demo</title>
	<script
		src="https://cdn.jsdelivr.net/npm/pijs-web@2.0.0/dist/pi.min.js"
		integrity="sha256-SgvzZv2kCC2Z+WAIl8jQ6k/g4wUuOXSczjxMbbwbl/Y="
		crossorigin="anonymous"
	></script>
</head>
<body>
	<script>
		$.screen( "320x200" );
		$.line( 0, 0, 319, 199 );
	</script>
</body>
</html>

Running Locally

To run Pi.js locally you can download the latest version of Pi.js and create an HTML file like below. For the below example to work you must create a “libs” subfolder and copy your downloaded Pi.js file there.

<!doctype html>
<html lang="en">
<head>
	<meta charset="utf-8">
	<title>Pi.js Demo</title>
</head>
<body>
	<script src="libs/pi.min.js"></script>
	<script>
		$.screen( "320x200" );
		$.line( 0, 0, 319, 199 );
	</script>
</body>
</html>

Running a Local Server

If you are running on your dev machine locally you might run into some problems when working with local files. This is due to built-in browser security features that do not allow the browser to read data from images or other files on your local file system. To get around this you will need to run a local web server to run your project.

Here is a list of our recommended ways to set up a simple server for local development.

PHP Webserver – PHP contains a built-in webserver.
Python Webserver – Python contains a built-in webserver.
Node.js – Node.js using the http-server package can set up a server that is super easy to use.
Visual Studio Code – Visual Studio Code IDE with the Live Server extension can get a server up and running with the click of a button.

Accessor Variables

Pi.js can be accessed via the global variables $ or pi, which provide a convenient way to access the Pi.js library from your code. These variables allow you to easily call the various functions and properties provided by Pi.js, making it simple to integrate Pi.js into your existing projects. The $ is what you will see in most examples on this site, but in case of a conflict with a library such as jQuery you can also use the pi variable to access Pi.js. If jQuery is already included before the Pi.js library then the $ will only be used by the jQuery library.

pi.screen( "320x200" );
pi.line( 0, 0, 319, 199 );

All functions are attached to the accessor variables and you can call the functions either through a list of parameters or a single object containing the named parameters. This comes in handy for functions such as screen that contain many optional parameters.

$.screen( "320x200" );

// The following two function calls are identical
$.line( 5, 5, 315, 195 );
$.line( { x1: 5, y1: 5, x2: 315, y2: 195 } );