Ripple's Bitsy Guide

This is more of a reference guide with some advanced tips than a direct walkthrough of the basics. (Note: This guide is based off Bitsy version 5.3 or lower. Not all guides/links may be up to date.)

Back to Main Site

Contents:

1. Links to Basic Introductions to bitsy
2. Starting Tips and Warnings
3. Advanced Tips and Extended Features
4. Some Debug and Cleanup advice
5. Itch.io uploading tips
6. My personal format guidelines

1. Links to Basic Introductions to bitsy

Two main tutorials for learning the basics would be: Clair Morley's tutorial, and bitsy workshop by @haraiva

There is also a wiki, but it is still in the progress of being filled out: Bitsy Wiki

One of the most important resources in bitsy (as in life) are friends! You can join the discord and ask questions or read pinned posts about various tricks or advice: Bitsy Discord

2. Starting Tips and Warnings

Firstly, don't forget to "save" frequently by downloading your game! So, if you ever make a mistake or accidentally lose your game, you can always load an older game file and work from there. Below you'll find a list of general tips I've made:

DO NOT DELETE ROOM 0. Room 0 is the initial room in your game when you start a new game. Do not accidentally delete the entire room or erase it from the bitsy game data, it will cause serious malfunctions. A good Tip is to Label that first room "Do not delete" and to leave it unused. Make additional rooms and use them instead.
SPRITE PLACING BUG: When placing and unplacing sprites, note that unused sprites can REAPPEAR in the last spot they were placed. To avoid this, place all sprites somewhere in your game. If you have a sprite you don't want to place in your actual game, just put it in a hidden location, like in Room 0 (which you should keep separate from your game to avoid the above case)
DO NOT edit your game while your are test running your game in the bitsy editor (using the "Play" button in the room panel). You can lose changes after you end the testing. Be sure to always stop/end your test run when you are finished testing. Changing the game variables during testing also doesn't usually work.
Tip: You can alt-click to select tile/sprite/items in a room and switch to them. Just hold down alt and click on the tile/sprite/item in a room and you will automaticlly select it (instead of replacing it with something if you had just clicked normally). This is very useful when your game gets big, or rooms get crowded.
Warning: When using the above alt-clicking, be careful switching to a new tile/sprite/item when currently editing something. If you are typing something and alt-click to select something new your changes may not save. Make sure to click outside the dialogue box to save text changes first, then alt-click.
You should often try to duplicate a new set of tiles for each room. Sometimes you might use 1 kind of tile in multiple rooms, but later on, you may want to change it for just ONE room. But if you accidentally change it, it will change that tile for ALL the rooms it's in. Be careful of that.

3. Advanced Tips, Extended Features, and Hacks

So, have you already tried out the basics? Are you used to most of bitsy now and want to explore more options? Then here are some more helpful tips, tools, and advice! For more info refer to the following references: andimlenny's FAQ, and the Bitsy Wiki.

Extended Features are ways to expand what bitsy can do, but you will need to alter the bitsy game data. The bitsy game data is found in a tab in the Tools menu at the top of the bitsy editor.

Hacks can radically alter bitsy to make it do almost anything as long as you can code it. However you can use hacks without knowing coding by applying the wide range of existing hacks. Hacks alter the game file's data (the html file) and require you to first download your game, then edit the file directly. Borksy is a tool for applying a variety of hacks, and makes adding hacks to your game MUCH easier and faster.

Advanced Tips

Learning to do a bit of simple bitsy coding can be very useful. By using "show code" in the dialog panel you can directly type in bitsy code and write conditional triggers and manipulate variables. The coding is done between curly braces "{}" in bitsy. Here are some extra references: Bitsy Variable Tutorial by ayolland. Below are some coding tips:

BRACES {} BUG: Do not leave empty braces "{}" in dialogue with no code inbetween them because it can cause sprites to malfunction and have problems loading.
In one set of coding braces "{}", if a conditional triggers it will then exit that whole block of code. If you want multiple condtionals to check and trigger put them in separate braces.
It is possible to "nest" one conditional inside another. In this way you can chain together multiple conditionals.
Picking up items stores them as a number, however this number cannot be decreased. It is usually more useful keep track of numbers using variables instead. Variables can be added or subtracted to.
Variables can store strings of text by using quotes (""). You can even append text to the variable using "+".(ex. variable1="hot". variable1=variable1+"dog". This then makes the contents of variable1: hotdog.)

Extended Features

Some extended features of bitsy have been documented in different places such as the FAQ, and pinned in the Bitsy Discord. Here is a list of some of them and what they can do.

Extended Palette: Allows you to have MORE than just 3 colours by altering the bitsy game data. NOTE: If you have a room with tiles/sprites/items that use the extended palette, Do Not choose a non-extended palette for the room or it will cause the malfunctions in the room. You may not be able to see the room name or palette options.
Extended Animation: You can include more than 2 frames in an animation by altering the bitsy game data.
Stacking Colours: You can have more than 3 colours in a SINGLE tile by manually setting tiles/sprites/items to overal in a single location in a room. To do this you must set the coordinates manually of multiple tiles/sprites/items in the game data in a room to overlap, and you must additionally use an Extended Palette and the Transparency Hack.
Item Stacking: You can stack multiple items on top of each other by manually setting each items coordinates in a room by altering the bitsy game data. Only the bottom/last item (in the room's item list in the game data) will visually display, and when walking over top of it the items will trigger one at a time each time you walk over, starting with the first item and going down to the last.
Dialogue Linking: You can link the SAME dialogue section to multiple sprites/items. This is done by manually adjusting the bitsy game data. This can have some advantages, like if you don't want to rewrite certain dialogue, or if you want the same trigger to happen across multiple sprites/items.

Hacks

A good way to start out using hacks is to use Borksy which can automatically adds in hacks to your file, instead of having to manually cut and paste in hack code.

If you're interested in going beyond Borksy and the set of hacks it offers, you can find a full list of hacks at the github repository.

Below is some advice for various hacks:

It is a good idea to Reset Borksy Settings after each game (or when starting a new game). This is so that you do not accidentally hold over old settings which can break your game. Though, be careful not to reset too early and lose your settings because you might want to make post-release changes to your game.
For larger projects it is good practice to copy Borksy settings to another document for safety sake in case Borksy somehow resets, or you just want to leave a game and come back to it later.
For certain cases when hacks refer to the palette tag, palettes are numbered from 0 t0 9 (0-9), then from a to z (a-z). There is no "palette 10" or above.
In Bitsymuse, do not keep the default setting for playing music in rooms because it does not work, it is just an example.

4. Some Debug and Cleanup advice

For more complicated games you will want a way to safetly and efficiently test it for bugs. Here are some notes on some common procedures I take to debug my games. After your game is finished it is also important to reverse any changes you made for testing purposes, and cleanup any lose ends. Below are my tips for debugging and cleanup.

Debug Tips:

These are tips for testing your game, and for making it easier to edit it.

Sometimes I use invisible sprites or items to make trigger certain events. However when you place them, you can lose track of where they are. This is why I sometimes draw a placeholder image for them just so I can see them when I place them or need to move them.
One trick to hide the avatar is to change its colour to be identical to the background colour. For testing purposes you can make the avatar visible again by simply changing the avatar colour.
If you want to test a conditional trigger based on a variable but don't want to play through your whole game, you can just directly change the starting value of the variable in the Inventory panel.
You can check which tiles in your room are impassable walls by toggling a button in the Room panel.
It is usually good practice to add in an extra "else" statement with each conditional to check for bugs. So, in the case that a variable becomes a strange value that your conditional cannont handle, you will output something that says: "Error, variable1=## in SpriteName conditional."

Cleanup tips:

Before releasing your game here are some checks to make sure your game is reset to the correct initial state. Often you will make changes for debug purposes (as above), so these cleanup tips are heavily tied to those.

Remember to then erase any placeholder image before releaseing your game. (used if you make placeholder images for invisible sprites/items)
Return colour palette to normal. (used if you altered your palette to make your avatar visibile when it should be invisible.)
Return all variables to their correct initial values.
Return all tiles to be walls/not-walls. (sometimes you make tiles non-walls to test and explore places)
It is a good idea to Reset Borksy Settings after each game (or when starting a new game). This is so that you do not accidentally hold over old settings which can break your game. Though, be careful not to reset too early and lose your settings because you might want to make post-release changes to your game.
Before you close your game, you might want to take some pictures of your game in action to use as a cover image for when you upload it.

5. Itch.io uploading tips

There are lots of places you might upload your game, but a one popular place is itch.io(link). Here are some tips when thinking about uploading to itch.io:

Set the game size to make sure it won't appear too small or squashed by setting the viewport dimensions to 512x512 pixels in the embed options when editing your game page.
Take some screen captures or make some gifs using "record gifs" in bitsy to add to your game page.
In the description for your game add info on bitsy: controls, interacting, credits, etc.
Make sure to mention your references for outside material or help you used
List and credit the hacks you used

6. My personal format guidelines

These are just my personal preferences. Having a set format helps people playing your game differentiate text for characters talking or for narration and makes it easier and clearer for them to understand what's going on.

When somone is talking, put their name in caps. (ex. BILL: Hello Mr. Tree.)
When narrating the story, put it between square braces. (ex. [Bill runs away from many wasps.])
Give NPCs separate concluding text. This also makes sure that they don't keep adding more to a quest completion variable.
Put changes to variables after text. So, when inventory is decreased it happens after talking is completed.