(Sprig screen is 1/8" / 160×128 px)

Tutorial

Toolkit

You must be logged in to use this feature!

Maze Game: Characters, Enemies and Maps.

Welcome to part two of the Sprig Batch Jam! This and the next two parts will guide you through making your own maze game. While some code is included in the editor, you’ll be largely creating your own! But never fear; as always we have hints and solutions.
If you haven’t already, click here to view the session that this tutorial is part of.

The Plan!

Make some characters!
Draw up your levels
Add controls to move your player
Make walls actually work
Add logic to make levels and goals work
Wrap-up!

1. Make some characters!

A sprite is anything that is visible on your game, except for text and background.
Your game needs at least three sprites. Create the sprites in code, and design their visuals!

Hints:

What sprites do I need to create?

Each of the tiles/components of the game must be represented as a sprite, such as characters, blocks, enemies, targets, etc. - everything that is drawn on the screen, except for text and backgrounds. Make one sprite for each of the things you’ll need in your game.

How do I create sprites?

Search the toolkit for setLegend to create sprites and assign art to each.

I've tried my best. Show solution.

In Sprig, a sprite is represented by a single letter (a key) and a variable name. Each key and name must be unique!

Repeat for each of your sprites. For this first sprite, the variable name is player and the key is "p"

const player = "p";
const wall = "w";
const goal = "g";

Then, assign art to each sprite using setLegend; the characters after bitmap are backticks.

setLegend(
    [ player, bitmap``],
    [ wall, bitmap``],
    [ goal, bitmap``]
);

Once written in the Sprig editor, click on each of the green bitmap buttons to edit the sprites!

2. Draw up your levels

A maze game needs a variety of levels! Let’s make two levels to play through. Feel free to take creative liberty with these!

Hints:

How do I create levels?

Start by creating a variable to keep track of which level you’re on, like this:

let level = 0;

Then search the toolkit for setMap and take a look at how lists of levels are defined.

When you want to set the current level, use setMap(levels[level]), which sets the current map to the item in the list of levels at the index represented by level.
When level is 0, levels[level] is equivalent to levels[0], because the variable level represents the number 0. levels[level] will always represent the current level, no matter what level is set to.

I've tried my best. Show solution.

First, we’ll need a variable to keep track of which level we’re on. Levels start from zero and count up!

let level = 0;

We’ll store our levels in an array. Arrays are lists of elements which we can use to store all our levels.

const levels = [
    map``,
    map``
];

Click on each of the green map buttons to edit the maps!

PS: We can move to the next level like this:

level = level + 1 // increment the level number by 1
setMap(levels[level]) // update Sprig to the level represented by the level number

3. Add controls to move your player

You need to be able to move your player! Add controls to move in all four directions and to reset the level.

Hints:

How do I add controls?

Search the toolkit for onInput to react to button presses, and take a look at the onInput code already written in the editor!

How can I reset the current level?

Use setMap with the current level (levels[level]) to reset the map!

I've tried my best. Show solution.

For player movement, we’ll want to use an onInput function for each direction, and in each move the player in a different way.

onInput("w", () => {
    getFirst(player).y -= 1; // negative y is upwards
});

onInput("a", () => {
    getFirst(player).x -= 1;
});

onInput("s", () => {
    getFirst(player).y += 1; // positive y is downwards
});

onInput("d", () => {
    getFirst(player).x += 1;
});

To reset the level, we can set the current map to the original current level, like this:

onInput("j", () => {
    setMap(levels[level])
});

4. Make walls actually work

If you’ve tried play-testing your game yet (click the green run button in the corner!), you might’ve noticed that your character can walk through the walls. You’ll want to make your player and walls solid in order to avoid this!

Hints:

How do I make my sprites solid?

Search the toolkit for setSolids!

I've tried my best. Show solution.

Pass your player and wall sprites into setSolids, like this:

setSolids([ player, wall ]); // sprites cannot go inside of these blocks

5. Add logic to make levels and goals work

Let’s make our game actually work! There’s four parts to this step:

Detect if your player is overlapping with a goal
Check if there are more levels left.
If there are still more levels left, move to the next level
If you just finished the last level, show a win screen

Hints:

How can I run code whenever my player overlaps with a goal?

Search the toolkit for afterInput to run code after every button press! We can check if we’re overlapping a goal in this code block.

Then, use tilesWith (again, search the toolkit) to count how many tiles there are that contain both the player and goal. If the length of this array > 0, the player is overlapping a goal.

Finally, use an if/else statement to run certain code when the number of goals covered is above zero, and other code when it’s not.

afterInput(() => {
    const numberOfGoalsCovered = // fill in this part using tilesWith!

    if (numberOfGoalsCovered > 0) {
        // run code when player overlaps with goal
    } else {
        // run other code when player is not on goal
    }
})

How do I check if there are more levels left?

You can use another if statement! Increment the current level number, then check if the level number is a valid level (if its index is less than the number of total levels); if it is, you can progress to the next level, and if not you’ve won the game!

// increment the current level (look back to step 2!)

if (level < levels.length) {
    // change to next level!
} else {
    // show win screen!
}

How do I move to the next level?

After you’ve incremented level by one to change the level number, reset the map by searching the toolkit for setMap, and using it with the current level! This is similar to how you added a reset button in step 3.

How do I show a win screen?

Search the toolkit for addText and have it display something like “you win”!

I've tried my best. Show solution.

// these get run after every input
afterInput(() => {
    const goalsCovered = tilesWith(player, goal); // tiles that both contain the player and goal

    // if at least one goal is overlapping with a player, proceed to the next level
    if (goalsCovered.length >= 1) {
        // increase the current level number
        level = level + 1;

        // check if current level number is valid
        if (level < levels.length) {
            setMap(levels[level]);
        } else {
            addText("you win!", { y: 4, color: color`7` });
        }
    }
});

Page 1/2

The Toolkit

Sprig is a tiny construction kit to build tile based games. The games are written in JavaScript. It was made by Hack Club, a global community of teen coders who believe people learn best by making things they care about and sharing them with others. You can watch this video for an introduction to Sprig website.

Run games by hitting the Run button or pressing Shift+Enter.

Getting Help

If this is your first time using Sprig, try playing through the tutorial. From there, we suggest hacking on any of the current games or starting from scratch.

If you ever need help, have ideas, or want to meet other game-makers, join the community in the #sprig channel on the Hack Club Slack.

Level Design

Sprig games are made up of grids of square tiles.

setLegend(bitmaps)

Tell Sprig what types of sprites are available in your game. Bitmap keys must be a single character. We recommend storing character keys in variables.

const player = "p"
const wall = "w"

setLegend(
  [ player, bitmap`...` ],
  [ wall, bitmap`...` ],
)

To create a new bitmap, type

bitmap`.`

Those are backticks! Click on the highlighted “bitmap” button to edit your drawing.

The order of sprite types in your legend also determines the z-order of drawing them. Sprite types that come first are drawn on top.

setBackground(bitmapKey)

Tiles a bitmap as the background of the game:

setBackground(spriteKey)

This only changes the visuals of the game.

setMap(level)

Designing a level is like drawing a bitmap:

map`...`

The characters in the map come from the order of your bitmap legend. Levels don’t have to be kept track of in a legend, you should store them in a variable yourself. You can call setMap to clear the game and load a new level:

const level = map`...`
setMap(level)

You might want to keep track of multiple levels using an array to switch between them mid-game:

const levels = [
  map`...`,
  map`...`,
  // etc.
]
setMap(levels[0])

// Later:
setMap(levels[1])

setSolids(bitmapKey)

Solid sprites can’t overlap with each other. This is useful for creating things like walls:

const player = "p"
const wall = "w"

setSolids([ player, wall ])

setPushables(pushMap)

Use setPushables to make sprites push other sprites around. The sprite on the left will be able to push all sprites listed on the right.

const player = "p"
const block = "b"

setPushables({ 
  [player]: [ block, player ] 
})

Watch out! Make sure everything you pass to setPushables is also marked as a solid or they won’t be pushed around.

width()

Get the width of the current map.

height()

Get the height of the current map.

User Input

Sprig has eight inputs w, a, s, d, i, j, k, l.

Typically w, a, s, d are used as directional controls.

onInput(type, callback)

Do something when the player presses a control:

onInput("d", () => {
  // Move the player one tile to the right
  getFirst(player).x += 1
})

afterInput(callback)

Runs after every input event has finished being handled. Useful for tasks like checking win states:

afterInput(() => {
  if (getAll(block).length > 0) {
    console.log("you win")
  }
})

Sprites and Tiles

Each tile can contain any number of sprites stacked on top of each other.

Sprites contain:

{
  type
  x
  y
}

You can move the sprite by setting x and y.

The bitmapKey can also be changed to update the rendered graphic and collision rules the sprite will follow.

sprite.y += 1
sprite.type = "p"

You can remove a sprite with sprite.remove().

getTile(x, y)

Returns a list of the sprites in the specified tile.

tilesWith(type, …)

Returns a list of the tiles that contain type.

tilesWith(block)

tilesWith accepts multiple sprite types.

tilesWith(block, player, ...)

addSprite(x, y, spriteType)

Creates a new sprite of the given type.

clearTile(x, y)

Removes all sprites from the specified tile.

getAll(type)

Returns all sprites of the given type. If no bitmap key is specified, it returns all the sprites in the game.

getFirst(type)

Returns the first sprite of a given type. Useful if you know there’s only one of a sprite, such as with a player character.

Shortcut for getAll(type)[0].

Text

addText(string, options = { x, y, color })

You can add text with optional x, y, and color.

In Sprig, each color is represented by a single character. Like bitmap and map, you can use the color keyword to pick a color for your text. A preview of your selected color will also show next to the character.

For example:

addText("hello", { 
  x: 10,
  y: 4,
  color: color`3`
})

clearText()

Clears all text on the screen.

Music and Sound Effects

Sprig comes bundled with a built-in sound engine and sequencer! You can use this to write background music, or with a high BPM to make sound effects.

You can create a tune with the tune keyword. As usual, click on the button to open an editor window.

// Create a tune:
const melody = tune`...`

// Play it:
playTune(melody)

// Play it 5 times:
playTune(melody, 5)

// Play it until the heat death of the universe:
const playback = playTune(melody, Infinity)

// Or make it shut up early:
playback.end()

Infinite loop detection

The Sprig editor will automatically insert a heuristic in your for, while and or do-while loops to detect potential infinite loops. Code looking like

while (condition) {
  // do stuff
}

will become

startTime = performance.now()
while (condition) {if (++_loopIt > 2000 && performance.now() - startTime > 1500) throw new RangeError("Potential infinite loop")
  // do stuff
}

Note that all original line numbers in your code will be preserved.

Change Key Bindings

To remap, select the input field and press your chosen key.

Key w:

Key a:

Key s:

Key d:

Key i:

Key j:

Key k:

Key l:

Maze Game: Characters, Enemies and Maps.

The Plan!

1. Make some characters!

Hints:

2. Draw up your levels

Hints:

3. Add controls to move your player

Hints:

4. Make walls actually work

Hints:

5. Add logic to make levels and goals work

Hints:

The Toolkit

Getting Help

Level Design

setLegend(bitmaps)

setBackground(bitmapKey)

setMap(level)

setSolids(bitmapKey)

setPushables(pushMap)

width()

height()

User Input

onInput(type, callback)

afterInput(callback)

Sprites and Tiles

getTile(x, y)

tilesWith(type, …)

addSprite(x, y, spriteType)

clearTile(x, y)

getAll(type)

getFirst(type)

Text

addText(string, options = { x, y, color })

clearText()

Music and Sound Effects

Infinite loop detection

Session Conflict!

Change Key Bindings