Javascript rewrite of Andrew Merrill's 2D Python graphics [library](http://inside.catlin.edu/site/compsci/resources/python/graphics/PythonGraphics.html). ~Just like from Computer Science 1
npm install @soft-boy/graphics.jsJavascript rewrite of Andrew Merrill's 2D Python graphics library. ~Just like from Computer Science 1

Try it on CodePen
To make an animation or game, you need to write three functions:
- A function that initializes a new world
- A function that updates the world for each frame of the animation
- A function that draws the world on the screen
``js
import { makeGraphicsWindow, runGraphics, fillCircle } from '@soft-boy/graphics.js'
makeGraphicsWindow(800, 600, document.getElementById('canvas'))
// this function is called once to initialize your new world
function startWorld(world) {
world.ballX = 50
world.ballY = 300
}
// this function is called every frame to update your world
function updateWorld(world) {
world.ballX = world.ballX + 3
}
// this function is called every frame to draw your world
function drawWorld(world) {
fillCircle(world.ballX, world.ballY, 50, "red")
}
runGraphics(startWorld, updateWorld, drawWorld)
`
`
#install cli if you don't already have it
npm install -g create-graphics-js
create-graphics-js my-game
cd my-game
npm start
`
2. You can specify the red, green, and blue components of the exact color that you want to use. Each component can vary in intensity from 0 (none) to 255 (full intensity). You need to put square brackets around the three component values and separate them with commas.
For example: [220,20,60]
3. Any CSS color string.
For example: "#D3D3D3" rgba(220, 20, 60, .5)Fundamental Functions
$3
Creates a new graphics window. You must call this function before doing anything else with graphics or animation.
- width: number the desired width of the animation window, in pixels
- height: number the desired height of the animation window, in pixels
- canvasDOMNode: object the DOM node for the html canvas elementReturns:
undefined (nothing)Examples:
`js
makeGraphicsWindow(800, 600, document.getElementById('canvas'))
`
$3
For an interactive, world-based program, your should call this function on the very last line of your program.
- startFunction: function the name of the function that initializes your new world. Takes one argument (the world).
- updateFunction: function the name of the function that updates your world for the next frame. Takes one argument (the world).
- drawFunction: function the name of the function that draws the frames of your animation. Takes one argument (the world).Returns:
undefined (nothing)Examples:
`js
runGraphics(startWorld, updateWorld, drawWorld)
`
$3
Stops the animation from running.Returns:
undefined (nothing)Examples:
`js
endGraphics()
`
Drawing Functions
$3
-
x: number the x coordinate of the point
- y: number the y coordinate of the point
- color: string the color to useReturns:
undefined (nothing)Examples:
`js
drawPixel(200, 100)
drawPixel(200, 100, "red")
`
$3
- x1: number the x coordinate of the start of the line
- y1: number the y coordinate of the start of the line
- x2: number the x coordinate of the end of the line
- y2: number the y coordinate of the end of the line
- color: string the color to use (optional; defaults to "black")
- thickness: number the thickness of the line (optional; defaults to 1)Returns:
undefined (nothing)Examples:
`js
drawLine(200, 100, 600, 150)
drawLine(200, 100, 600, 150, "red")
drawLine(200, 100, 600, 150, "red", 10)
`
$3
- x: number the x coordinate of the center of the circle
- y: number the y coordinate of the center of the circle
- radius: number the radius of the circle
- color: string the color to use (optional; defaults to "black")
- thickness: number the thickness of the edge (optional; defaults to 1)Returns:
undefined (nothing)Examples:
`js
drawCircle(200, 100, 25)
drawCircle(200, 100, 25, "red")
drawCircle(200, 100, 25, "red", 5)
`
$3
- x: number the x coordinate of the center of the circle
- y: number the y coordinate of the center of the circle
- radius: number the radius of the circle
- color: string the color to use (optional; defaults to "black")Returns:
undefined (nothing)Examples:
`js
fillCircle(200, 100, 25)
fillCircle(200, 100, 25, "red")
`
$3
- x: number the x coordinate of the center of the ellipse
- y: number the y coordinate of the center of the ellipse
- width: number the width of the ellipse
- height: number the height of the ellipse
- color: string the color to use (optional; defaults to "black")
- thickness: number the thickness of the edge (optional; defaults to 1)Returns:
undefined (nothing)Examples:
`js
drawEllipse(200, 100, 50, 25)
drawEllipse(200, 100, 50, 25, "red")
drawEllipse(200, 100, 50, 25, "red",5)
`
$3
- x: number the x coordinate of the center of the ellipse
- y: number the y coordinate of the center of the ellipse
- width: number the width of the ellipse
- height: number the height of the ellipse
- color: string the color to use (optional; defaults to "black")Returns:
undefined (nothing)Examples:
`js
fillEllipse(200, 100, 50, 25)
fillEllipse(200, 100, 50, 25, "red")
`
$3
- width: number the desired width of the animation window, in pixels
- height: number the desired height of the animation window, in pixels
- canvasDOMNode: object the DOM node for the html canvas elementReturns:
undefined (nothing)Examples:
`js
drawRectangle(200,100,300,150)
drawRectangle(200,100,300,150,"red")
drawRectangle(200,100,300,150,"red",10)
`
$3
- width: number the desired width of the animation window, in pixels
- height: number the desired height of the animation window, in pixels
- canvasDOMNode: object the DOM node for the html canvas elementReturns:
undefined (nothing)Examples:
`js
fillRectangle(200, 100, 300, 150)
fillRectangle(200, 100, 300, 150, "red")
`
$3
- pointlist: array An array of arrays, where each subarray is the [x,y] coordinates of a vertex of the polygon.
- color: string the color to use (optional; defaults to "black")
- thickness: number the thickness of the edge (optional; defaults to 1)Returns:
undefined (nothing)Examples:
`js
drawPolygon([[100,100],[200,100],[150,150]])
drawPolygon([[100,100],[200,100],[150,150]], "red", 5)
`
$3
- pointlist: array An array of arrays, where each subarray is the [x,y] coordinates of a vertex of the polygon.
- color: string the color to use (optional; defaults to "black")Returns:
undefined (nothing)Examples:
`js
fillPolygon([[100,100],[200,100],[150,150]])
fillPolygon([[100,100],[200,100],[150,150]], "red")
`
$3
-
text: string the text to display
- x: number the x coordinate of the top-left corner of the text
- y: number the y coordinate of the top-left corner of the text
- size: number the size of the letters in the text, in pixels (optional; defaults to 30)
- color: string the color to use (optional; defaults to "black")
- bold: boolean a boolean, true for bold, false for regular (optional; defaults to false)
- italic: booleana boolean, true for italic, false for regular (optional; defaults to False)Returns:
undefined (nothing)Examples:
`js
drawString("You Win", 20, 550)
drawString(score, 50, 200, 40, "red")
`
Image Functions
$3
Loads a graphics image from a disk file. Unless you want to draw a rectangular image, your image's background should be transparent, or you should specify the color of the image's background for the _transparentColor_ parameter (see below). Images are cached, so if you load the same image with the same options more than once, it will reuse the originally loaded image for efficiency.
- file: number the file that contains the image
- rotate: number the number of degrees to rotate the image counter-clockwise (use a negative number to rotate clockwise) (optional; defaults to 0, meaning no rotation)
- scale: number the scaling (resizing) factor, where 1 means no scaling, 2 means draw the image at twice its usual size, 0.5 means draw the image at half its usual size, etc. (optional; defaults to 1, meaning no scaling)
- flipHorizontal: boolean a boolean, indicating whether to flip the image horizontally (across the Y axis), where true means flip and false means don't flip (optional; defaults to False, don't flip)
- flipVertical: boolean a boolean, indicating whether to flip the image vertically (across the X axis), where true means flip and False means don't flip (optional; defaults to false, don't flip)Returns:
object an image that you can pass to the drawImage function (see below) to have drawn on the screenExamples:
`js
world.soccerball = await loadImage(require("./soccer.jpg"))
world.soccerball = await loadImage(require("./soccer.jpg"), scale=0.5)
`
$3
Draws a graphic image on the screen
- image: number the desired width of the animation window, in pixels
- x: number the x coordinate of the point on which to center the image
- y: number the y coordinate of the point on which to center the image
- rotate: number the number of degrees to rotate the image counter-clockwise (use a negative number to rotate clockwise) (optional; defaults to 0, meaning no rotation)
- scale: number the scaling (resizing) factor, where 1 means no scaling, 2 means draw the image at twice its usual size, 0.5 means draw the image at half its usual size, etc. (optional; defaults to 1, meaning no scaling)
- flipHorizontal: boolean a boolean, indicating whether to flip the image horizontally (across the Y axis), where true means flip and false means don't flip (optional; defaults to False, don't flip)
- flipVertical: boolean a boolean, indicating whether to flip the image vertically (across the X axis), where true means flip and False means don't flip (optional; defaults to false, don't flip)Returns:
undefined (nothing)Examples:
`js
drawImage(soccerball, 300, 200)
drawImage(soccerball, 300, 200, 90)
drawImage(soccerball, 300, 200, 90, 0.75)
drawImage(soccerball, 300, 200, scale=0.75)
drawImage(soccerball, 300, 200, 45, 0.75, false, true)
drawImage(soccerball, 300, 200, flipHorizontal=true)
`
$3
Returns the width in pixels of a loaded image
- image: object the image to get the width ofReturns:
number The width in pixelsExamples:
`js
let width = getImageWidth(soccerball)
`
$3
Returns the height in pixels of a loaded image
- image: object the image to get the width ofReturns:
number The height in pixelsExamples:
`js
let height = getImageHeight(soccerball)
`
Sound Functions
We have two categories for audio functions. Sound functions are for short sound clips like sound effects. Music functions are intended for longer music clips
$3
Loads a sound clip from a disk file (must be in WAV or OGG format, sorry no MP3s).
- file: string the text to display
- volume: number the x coordinate of the top-left corner of the textReturns:
object a sound that you can pass to the playSound function (see below)Examples:
`js
world.beep = await loadSound(require("./beep.wav"))
world.soundtrack = await loadSound(require("./funkybeat.wav", 0.3))
`
$3
Plays a sound clip on your computer speakers.
- sound: object the sound clip to play (must have been already loaded by the loadSound function)
- repeat: boolean a boolean indicating whether to repeat the sound forever or just play it once. true means repeat forever, false means play it once. (optional; defaults to false, play it once)Returns:
undefined (nothing)Examples:
`js
playSound(beep)
playSound(soundtrack, true)
`
$3
Stops a sound clip from playing.
- sound: object the sound clip to stopReturns:
undefined (nothing)Examples:
`js
stopSound(soundtrack)
`
$3
Loads a music clip from a disk file so that you can play it later using the playMusic function. Only one music clip may be loaded at a time. This supports MP3 and some other music file formats.
- file: string the file that contains the music clip
- volume: number a number between 0.0 and 1.0 that indicates what volume to use for this music clip. 1.0 is full volume, and 0.0 would be completely muted. (optional; defaults to 1.0)Returns:
undefined (nothing)Examples:
`js
loadMusic(require("./themesong.mp3"))
`
$3
Plays the music clip that you loaded with the loadMusic function. Only one music clip can be playing at once.
- repeat: boolean a boolean indicating whether to repeat the music forever or just play it once. true means repeat forever, false means play it once. (optional; defaults to false, play it once)Returns:
undefined (nothing)Examples:
`js
playMusic()
playMusic(true)
`
$3
Stops the current music from playing.Returns:
undefined (nothing)Examples:
`js
stopMusic()
`
Mouse Functions
There are two ways you can get information from the user's mouse: Event Listeners and Direct Polling. With an Event Listener, you write a function that gets called automatically when the user uses their mouse. With Direct Polling, you can ask about the mouse whenever you want, which you would typically do during each frame in your update world function.You can also control the mouse pointer - showing and hiding it.
$3
$3
Returns the current position of the mouse.Returns:
array an array that contains the x and y coordinates of the mouseExamples:
`js
let [x, y] = getMousePosition()
`
$3
Returns whether a given mouse button is pressed or not.
- button: number a number indicating which button to check (1 for left, 2 for middle, 3 for right) (use 1 on a Mac with one button)Returns:
boolean a boolean where true means that button is currently pressed and false means it is notExamples:
`js
if (getMouseButton(1)) {
fireRockets = true
}
`
$3
$3
Registers your function that listens for mouse pressed events.
- listenerFunction: function the listener function that you wrote. Your listener function must take four arguments:
- the world
- the x coordinate where the mouse was when the button was pressed
- the y coordinate where the mouse was when the button was pressed
- a number indicating which button was pressed (1 for left, 2 for middle, 3 for right) (use 1 for a Mac with one button)Returns:
undefined (nothing)Examples:
`js
function myMousePressedFunction(world, mouseX, mouseY, button) {
if (button == 1 && mouseX < 100 && mouseY < 100) {
world.myball.xspeed = 0
}
}function startWorld(world) {
onMousePress(myMousePressedFunction)
}
`
$3
Registers your function that listens for mouse pressed events.
- listenerFunction: function the listener function that you wrote. Your listener function must take four arguments:
- the world
- the x coordinate where the mouse was when the button was pressed
- the y coordinate where the mouse was when the button was pressed
- a number indicating which button was pressed (1 for left, 2 for middle, 3 for right) (use 1 for a Mac with one button)Returns:
undefined (nothing)
$3
Registers your function that listens for mouse pressed events.
- listenerFunction: function the listener function that you wrote. Your listener function must take three arguments:
- the world
- the x coordinate where the mouse was when the button was released
- the y coordinate where the mouse was when the button was releasedReturns:
undefined (nothing)
$3
Registers your function that listens for mouse pressed events.
- listenerFunction: function the listener function that you wrote. Your listener function must take three arguments:
- the world
- the x coordinate where the mouse was when the wheel was rotated
- the y coordinate where the mouse was when the wheel was rotatedReturns:
undefined (nothing)
$3
Registers your function that listens for mouse pressed events.
- listenerFunction: function the listener function that you wrote. Your listener function must take eight arguments:
- the world
- the x coordinate that the mouse moved to
- the y coordinate that the mouse moved to
- the amount by which the x coordinate changed during this move (may be positive or negative)
- the amount by which the y coordinate changed during this move (may be positive or negative)
- a boolean for mouse button 1 (true if it was pressed, and false if it was not)
- a boolean for mouse button 2 (true if it was pressed, and false if it was not)
- a boolean for mouse button 3 (true if it was pressed, and false if it was not)Returns:
undefined (nothing)
$3
$3
Makes the mouse cursor invisible.Returns:
undefined (nothing)Examples:
`js
hideMouse()
`
$3
Makes the mouse cursor visible - this is only needed if you have previously called hideMouse().Returns:
undefined (nothing)Examples:
`js
showMouse()
`
Keyboard Functions
There are two ways you can get information from the keyboard: Event Listeners and Direct Polling. With an Event Listener, you write a function that gets called automatically when a key is pressed or released. With Direct Polling, you can ask whether a key is pressed whenever you want, which you would typically do during each frame in your update world function.You can check out the list of key names to find the official names of each keyboard key.
$3
$3
Returns whether a given keyboard key is currently pressed or not.
- key: string A string indicating which key to checkReturns:
boolean a boolean where true means that key is currently pressed and false means it is notExamples:
`js
function updateWorld(world) {
if (isKeyPressed("space")) {
fireRockets = true
}
}
`
$3
$3
Registers your function that listens for key pressed events. This function will get called once each time a particular key is pressed.
- listenerFunction: function The listener function that you wrote. Takes one argument: the world.
- key: string A string indicating which key listen forReturns:
undefined nothingExample Listener Function:
`js
function moveDown(world) {
world.myballY = world.myballY + 5
}
`Examples:
`js
function startWorld(world): {
onKeyPress(moveDown, "down")
}
`
$3
Registers your function that listens for any key pressed events. This function will get called once each time any key is pressed.
- listenerFunction: function The listener function that you wrote. Takes twos arguments: the world and the key that was pressedReturns:
undefined nothingExample Listener Function:
`js
function myKeyPressedListener(world, key) {
if sameKeys(key, "right") {
world.myballX = world.myballX + 5
}
if sameKeys(key, "left") {
world.myballX = world.myballX - 5
}
}
`Examples:
`js
function startWorld(world): {
onAnyKeyPress(myKeyPressedListener)
}
`
$3
Registers your function that listens for key released events. This function will get called once each time a particular key is released.
- listenerFunction: function The listener function that you wrote. Takes one argument: the world.
- key: string A string indicating which key listen forReturns:
undefined nothingExamples:
`js
onKeyRelease(spaceBarReleased, "space")
`
$3
Registers your function that listens for any key released events. This function will get called once each time any key is released.
- listenerFunction: function The listener function that you wrote. Takes twos arguments: the world and the key that was releasedReturns:
undefined nothingExamples:
`js
onAnyKeyRelease(myKeyReleasedListener)
`
$3
$3
Checks whether two names for keyboard keys refer to the same key
- key1: string The first key to compare
- key2: string The second key to compareReturns:
boolean a boolean where true means that key is currently pressed and false means it is notExamples:
`js
function myKeyPressedFunction(world, key) {
if sameKeys(key, "right") {
world.myballX = world.myballX + 5
}
}
`
$3
Returns a name for a key
- key: string A number that was passed to your key pressed listener or your key released listener.Returns:
string A string that names the key that was pressed or releasedExamples:
`js
function myKeyPressedFunction(world, key) {
console.log(getKeyName(key))
}
`
Time Functions
$3
Registers a function that listens for timer events. Your listener function will be called over and over after the end of each timed interval.
- listenerFunction: function the name of the listener function that you wrote. Takes one input, the world.
- interval: number the interval between calls to the listener function, measured in millisecondsReturns:
undefined nothingExamples:
`js
onTimer(enemySneezes, 2000)
`
$3
Returns the elapsed time, in milliseconds, since the animation started.Returns:
number the elapsed time, measured in millisecondsExamples:
`js
let currentTime = getElapsedTime()
`
$3
Resets the elapsed time that is used by getElapsedTime.Returns:
undefined nothingExamples:
`js
resetTime()
`
$3
Sets the desired frame rate (in frames per second) for the animation. If you specify a frame rate that is too high, your animation may run at a slower frame rate as limited by your graphics hardware. The frame rate defaults to 60 frames per second.
- framerate: number The frame rate that you want (in frames per second)Returns:
undefined nothingExamples:
`js
setFrameRate(60)
`
$3
Makes your program display the actual frame rate (in frames per second) in the Python Shell window every few seconds as your program runs.
- interval: number The number of seconds between FPS reports. Use 0 to disable displaying FPS values.Returns:
undefined nothingExamples:
`js
displayFPS(2)
`
$3
Returns current frame rate, in frames per second, of your program. This may be lower than the frame rate you asked for if your program has too much work to do during each frame and can’t keep up.Returns:
number The frame rate in FPS (frames per second)Examples:
`js
let fps = getActualFrameRate()
`
Math Functions
These functions convert between angles and rectangular components. All angles are measured in degrees. Positive angles indicate counter-clockwise rotation. A heading angle of 0 degrees points straight right (east) along the positive X axis.
$3
Converts an angle and length into rectangular vector components.
- angle: number the angle of counter-clockwise rotation, in degrees, where zero degrees lies along the positive X axis
- length: number the length of the desired vectorReturns:
array A tuple [x, y] containing the two vector componentsExamples:
`js
let [x, y] = convertToComponents(45, 2)
`
$3
Converts rectangular vector components into an angle in degrees.
- x: number the x component of the vector
- y: number the y component of the vectorReturns:
number The heading angle defined by the given vector, in degrees.Examples:
`js
let angle = convertToAngle(3,4)
`
Other Math Functions
$3
Determines if a point is inside a polygon
- x: number The x coordinate of the given point
- y: number The y coordinate of the given point
- polygon: array The polygon, as an array of [x, y] subarraysReturns:
boolean true if the point is inside the polygon, and false otherwise.Examples:
`js
polygon = [[10, 20], [100, 40], [50, 90]]
if (pointInPolygon(mousex, mousey, polygon)) {
console.log("mouse is inside the polygon")
}
`
Miscellaneous Functions
$3
Returns the width of your windowReturns:
number The width in pixelsExamples:
`js
let width = getWindowWidth()
`
$3
Returns the height of your windowReturns:
number The height in pixelsExamples:
`js
let height = getWindowHeight()
`
$3
If you have already called makeGraphicsWindow, this will return the size of the graphics window you made. If you have not already called makeGraphicsWindow, then it returns the current resolution of the browser window.Returns:
array An array containing the width and height of the window or screen.Examples:
`js
let [width, height] = getScreenSize()
`
$3
Sets the background color or image for your animation.
- background: The color or image to use as a background. If the background is null, then the background will not be erased between frames, so your moving object will leave trails (unless you erase them yourself).Returns:
undefined (nothing)Examples:
`js
setBackground("red")
setBackground([240, 230, 140])
setBackground(loadImage(require("./mybackground.jpg")))
setBackground(null)
`
$3
Sets the title of the window.
- title: string the title for the windowReturns:
undefined (nothing)Examples:
`js
setWindowTitle("Cool Game")
`
$3
Returns a list of the names of all of the built-in colors supported by this library.Returns:
array An array of strings, each of which is the name of a built-in color.Examples:
`js
let colorlist = getColorsList()
`
$3
Returns an array of the names of all of the built-in Fonts supported by this library.Returns:
array An array of strings, each of which is the name of a built-in font.Examples:
`js
let fontlist = getFontList()
`
$3
Computes the number of pixels needed to draw a string
- text: string the x coordinate of the start of the line
- size: number the y coordinate of the start of the line
- bold: boolean true for bold, false for regular (optional; defaults to false)
- italic: boolean true for italic, false for regular (optional; defaults to false)
- font: string the name of the font to use - see getFontList to find out what fonts are available (optional; defaults to the default system font)Returns:
undefined (nothing)Examples:
`js
let [width, height] = sizeString("score: ", 30)
`
$3
Saves a snapshot of the current screen to a file.
- filename: string The filename of the file in which to save the image. The format of the file will be determined by the filename extension.Returns:
undefined (nothing)Examples:
`js
saveScreen("screenshot.jpg")
`
$3
Returns the color of a particular pixel on the screen
- x: number the x coordinate of the pixel
- y: number the y coordinate of the pixelReturns:
array An array containing the color. The tuple will have 4 parts, for the red, green, blue, and opacity components of the color, each of which is a number between 0 and 255.Examples:
`js
let [red, green, blue, opacity] = getScreenPixel(x,y)
``- Pong implementation: https://github.com/soft-boy/graphics.js-example
[npm-downloads-image]: https://badgen.net/npm/dm/@soft-boy/graphics.js
[npm-downloads-url]: https://npmcharts.com/compare/@soft-boy/graphics.js?minimal=true
[npm-install-size-image]: https://badgen.net/packagephobia/install/@soft-boy/graphics.js
[npm-install-size-url]: https://packagephobia.com/result?p=@soft-boy/graphics.js
[npm-url]: https://npmjs.org/package/@soft-boy/graphics.js
[npm-version-image]: https://badgen.net/npm/v/@soft-boy/graphics.js