you-win: API Reference

Importing

you-win exports the following names:

To import all these names so you can use them in your code, use the following lines:

const uw = require('you-win')
const {Phone, World, Sprite, Text, Polygon} = uw

Assets

Before you can do anything, you need initialise you-win. You do this by calling uw.begin(), which downloads all the files your game needs. We display a progress bar while your files are downloading.

await uw.begin()

The special await keyword is important here: it tells the computer not to carry on with your program until everything has finished loading.

You should call begin() exactly once.

Costumes

A costume is an image that controls how a Sprite looks.

You download them by calling loadCostume() with a name and URL, before you call begin().

If you make a static folder in the same place as your game’s .js file, you can put images inside it, and then use '/<filename>' to load them. For example, if you put my-asteroid.png in the static folder:

uw.loadCostume('asteroid', '/my-asteroid.png')
await uw.begin()

You can also use assets from a Glitch project. Copy their URL into your program:

uw.loadCostume('face', 'https://cdn.glitch.com/f213ed6a-d103-4816-b60d-47c712a926e2%2Fcat_00.png')
await uw.begin()

⚠ Because of security restrictions, you can’t use just any image URL from any website.

To use a costume later, give its name:

var s = new Sprite
s.costume = 'asteroid'

If you load more than one costumes, you-win won’t wait until the first one finishes downloading before downloading the next one. It speeds things up by downloading them all at once (i.e. in parallel).

uw.loadCostume('duck1', '/duck-frame1.png')
uw.loadCostume('duck2', '/duck-frame2.png')
await uw.begin() // waits for duck1 and duck2 to finish downloading

Emoji costumes

Emoji costumes are loaded by default. To use them, just set your Sprite’s .costume attribute to an emoji string:

var s = new Sprite
s.costume = '🙂'

The emoji costumes are sized 32x32 pixels. Most but not all emoji are included.

Emoji make great placeholder graphics for your game, or even final graphics if you like the retro pixel-art theme.

You can also use emoji inside Text.

World

World sets up the screen, manages all the sprites, and emits events such as taps and drags on the background.

Set up the world after calling begin() to load your assets.

// Load everything we need
await uw.begin()

// Make the world
var world = new World
world.title = ''
world.background = 'white'

// Now we can start making Sprites!

It has the following attributes:

World has the following methods:

Sprite

A Sprite is an image in the world that can be moved and rotated and so on.

To make your Sprite appear, you must set its costume.

uw.loadCostume('cat', 'https://cdn.glitch.com/f213ed6a-d103-4816-b60d-47c712a926e2%2Fcat_00.png?1499126150626')
await uw.begin()

var world = new World

var cat = new Sprite
cat.costume = 'cat'

var bigCat = new Sprite
bigCat.costume = 'cat'
bigCat.scale = 2 // twice as big

Sprites have quite a few attributes which you can change. You can also set their initial values when you make the sprite.

Sprites have some useful functions attached to them.

Sprite::forever

forever is really useful function: it lets you do something on every “frame” or “tick” of your game. Usually ticks happen 60 times a second (60 FPS).

Write a forever block like so:

sprite.forever(() => {
    // do stuff
})

Any code after the forever loop isn’t affected:

sprite.forever(() => {
    // This code runs forever.
})

// This code runs once.
// Carry on setting up the game:
var otherSprite = new Sprite

When the Sprite is destroyed, the forever loop will stop.

If you want to stop a forever loop without destroying the Sprite (so that it doesn’t run forever!), you can return false:

player.forever(() => {
    if (player.isTouching(floor)) { // the floor is lava
        // game over!
        return false // stop this loop
    }
    // otherwise, move the player...
})

Text

A Text object is like a Sprite, but instead of a costume, it’s used to display text.

var label = new Text
label.text = 'SCORE: ' + 100

The text has a retro aesthetic. It also supports emoji (using the same emoji set as Sprites can use). Which means that this:

var snowy = new Text
snowy.text = '⛄'

…is quite similar to this:

var snowy = new Sprite
snowy.costume = '⛄'

Text objects have all the same attributes as a Sprite–but instead of a costume, they have the following:

Polygon

A Polygon is like a Sprite, but has a shape instead of a costume. This shape is defined using a list of points. Examples include making a filled rectangle, a triangle with a fill and an outline, and thick lines.

Here’s an example Polygon:

var p = new Polygon
p.points = [[0, 0], [0, 32], [32, 32], [32, 0]]
p.fill = '#007de0'
p.outline = 'black'
p.thickness = 2

Polygons have all the same attributes as a Sprite–but instead of a costume, they have the following:

Rect

A Rect is a special sort of Polygon which, unsurprisingly, is shaped like a rectangle.

Instead of a costume, Rects have the following:

Don’t forget you will need to use new Rect and not new Polygon

Touch Events

An event tells you that something has happened. Both Worlds and Sprites will emit events when they are tapped or dragged.

If a tap overlaps more than one sprite (because the sprites are overlapping), then the sprites are told about the events in order. The front-most one sees the event first.

If a sprite wants to handle an event, it should return true. From then on, no other sprites (nor the world!) will see the event.

There are a few kinds of event:

If you’re testing your game on a computer, mouse clicks and drags will work to simulate touches – but remember that unlike fingers, a mouse pointer can only be in one place at a time!

Detecting taps

world.onTap(e => {
    // make a ball where you clicked
    var ball = new Sprite
    ball.costume = 'beachball'
    ball.posX = e.fingerX
    ball.posY = e.fingerY

    ball.onTap(e => {
        // flip
        ball.flipped = !ball.flipped

        // handle the event
        // - otherwise another ball will get spawned!
        return true
    })
})

Dragging sprites around

var ball = new Sprite
ball.costume = 'beachball'
ball.onDrag(e => {
    // move when dragged
    ball.posX += e.deltaX
    ball.posY += e.deltaY
    return true
})

Touches list

Detecting fingers held down

Sometimes you don’t want to listen for events: you just want to know where fingers are touching the screen, right now. To do this, you can use getFingers().

Phone

Phone provides access to sensors on a smartphone, such as the accelerometer. You can use this to control your game depending on how the phone is held; for example tilting to steer in a racing game.

You need to make a Phone object before you can access the readings:

var phone = new Phone

It has the following attributes which you can get:

Sound

To use sounds, make sure to import {Sound} from 'you-win'.

To load a sound , use loadSound. See Assets for details on the static/ folder and where to put your sound files.

uw.loadSound('moo', '/moo.wav')
await uw.begin()

Before you can play your sound, you must create a Sound object.

var mooNoise = new Sound('moo')

Finally, you can play your sound at the appropriate time.

mooNoise.play()

Maths

Some built-in maths utilities.

Some trigonometric functions. These work in degrees, unlike the ones built-in to JavaScript which use radians.

Random

Some built-in ways of getting random things are included.