bipsi game maker

scripting guide

2021/12/18
 intro_
bipsi is a tool for making small lo-fi
games to play in the browser

this guide continues on from the bipsi

user guide to help you understand how to
achieve for sophisticated effects in with
custom javascript code that goes beyond
the capabilities of bipsi's user
interface

bipsi is available at kool.tools/bipsi

if you encounter any bugs or need help

using bipsi, you can contact me on
twitter at @ragzouken, by email at
[email protected]

you can also join the bipsi discord at

with the following invite:
https://discord.gg/mnARVsgSkc
 events_
in bipsi, all of the interactive elements
are specified as events

events sit in a room waiting to be

touched by the player

when touched, they run through a set of

behaviours such as delivering dialogue,
moving the player to another room, etc

each event has a table of data fields

that are used to specify which behaviours
it should perform

the event templates are preset

collections of fields you can use for
convenience, but all events work the same
and you can use any field on any event

you can, however, override this with your

own behaviour
 custom behaviors_
you can add new touch behavior to every
event with an "add-behavior" field of
type "javascript"

the simplest place to put this is on the

player event so that the behavior is
added at the beginning of the game

this code is run every time any event is

touched, but you can have the code check
the touched event's field to decide if it
should do anything

this example is the actual code used to

implement the "exit" behavior:

javascript
let destination = FIELD(EVENT, "exit",
"location");
if (destination) {
MOVE(AVATAR, destination);
}
 custom scripts_
you can augment an event's touch behavior
by giving it a field called "after" or
"before" with type "javascript"

when such an event is touched, the

javascript code will be run before and
after the standard event behaviour for
touch

you can entirely redefine an event's

touch behavior by giving it a field
called "touch" with type "javascript"

this is what the "custom code" event

template contains

when such an event is touched, the

javascript code will be run instead of
the standard event behaviour for touch
 await_
you may not have encountered await before
in javascript. for bipsi it's enough to
understand that writing await before a
function call pauses the script until the
function says it has finished

the SAY function is finished when the

corresponding dialogue pages are closed

this example changes the player to a

mouse after they close the dialogue:

javascript
await SAY("you will become a mouse!");
SET_GRAPHIC(AVATAR, FIELD(EVENT,
"mouse-tile"));

or change as they read the dialogue:

javascript
SAY("you are now a mouse!");
SET_GRAPHIC(AVATAR, FIELD(EVENT,
"mouse-tile"));
 event fields_
the purpose of event fields is to provide
a somewhat convenient way to input
constant values for using in event
scripts

rather than having to type room numbers,

coordinates, dialogue text, etc into
javascript code, you can use the existing
bipsi picking interfaces to add them as
named fields

the "standard" event fields as described

in the user guide are special only
because they are used by the default
event script to decide what to do

when you write a custom touch script you

can choose your own meaning for the event
the fields

but you can also use DO_STANDARD() to

make the standard fields work as normal
 FIELD(S)_
get the value of a field name on an
event--in this case the "title" dialogue
on the player avatar:

code
const title = FIELD(AVATAR, "title");

get an array of the values of a field

name on an event:

code
const dialogues = FIELDS(EVENT, "say");

code
SAY_FIELD("example");
 SAY_
the simplest thing in bipsi scripting is
to queue dialogue:

code
SAY("hello there :)");

for longer dialogue, it's more convenient

to store it as a field on the event, if
we had a dialogue field called "example":

code
let dialogue = FIELD(EVENT, "example");
SAY(dialogue);

there's a shortcut specifically for

SAYing from the current event's fields:

code
SAY_FIELD("example");
 WALK_
the WALK function lets you move events
step by step with a series of directions

the directions understood are:

up, down, left, right, wait: ^ v < > .

this example moves the player avatar to

the right twice, hesitates, then moves
two more steps to the right:

code
await WALK(AVATAR, ">>.>>");

this example moves the touched event

around in a circle:

code
await WALK(EVENT, "^^>>vv<<");
 example: fetch quest_
this npc desires collectibles scattered
across the world and will thanks you for
getting them

each collectible adds one to a common

saved value:

javascript
await DO_STANDARD();
let prev = GET("apples", 0);
SET("apples", prev + 1);

and the npc decides what to say based on

the saved value (how many collected):

javascript
let count = GET("apples", 0);
if (count > 3) {
SAY_FIELD("thank-you");
} else {
SAY_FIELD("desire-apples");
}
 example: locked door_
this door blocks your path--unless you
have unlocked it

a key, or a switch, or a friend of the

gatekeeper? after being touched, this
event saves a shared value marking the
door as unlocked

javascript
await DO_STANDARD();
SET("door-1-unlocked", true);

a door, or gatekeeper, or other blockage?

after being touched this event checks for
the door unlocked value and if it's there
removes itself

javascript
await DO_STANDARD();
if (GET("door-1-unlocked")) {
REMOVE(EVENT);
}
 example: status report_
imagine we've been using other events to
track some stat values called "HP" and
"MP" for the player

we want to give the player some way to

see what their stats actually are

we can write some template text:

field
say / dialogue / "YOU HAVE [[HP]]/5
HP AND [[MP]]/5 MP"
 example: exodus_
guests leaving at the end of the party?
walls tumbling after an earthquake?
something happens that removes several
events from the game

add a "leaves" tag to every event we want

to deal with:

field
leaves / tag

use FIND_EVENTS to find all events with

the "leaves" tag and javascript's forEach
to REMOVE each one from the game:

javascript
await DO_STANDARD();
let leavers = FIND_EVENTS("leaves");
leavers.forEach((leaver) => {
REMOVE(leaver);
});
 example: cutscene_
a scene where you enter a tavern
unannounced. the owner is surprised to
hear you enter and walks over to greet
you, then walks you over to where they
were

this is split into a tavern owner event,

tagged with "tavern-owner", who will be
moved

and an invisible event at the door that

triggers the cutscene when you step on
it:

javascript
let owner = FIND_EVENT("tavern-owner");
await SAY_FIELD("surprised");
await WALK(owner, "<<<..vv");
await SAY_FIELD("greet-player");
WALK(owner, "^^>>>");
await WALK(AVATAR, "^^^>>");
 example: menu room_
a room you can enter from multiple places
but leaving takes you back to where you
came from:

entrances to the menu room are events

that store the current avatar location
and then move them into the room:

javascript
SET("return", LOCATION_OF(AVATAR));
MOVE(AVATAR, FIELD(EVENT, "exit"));

exits from the menu room are events that

move the avatar back to the stored
location:

javascript
MOVE(AVATAR, GET("return"));
 example: music_
this is the standard script used to play
music when a "music" field is present

either the field is a file, or the name

of a file field on the library event:

javascript
let music = FIELD_OR_LIBRARY("music");

if (music) {
PLAY_MUSIC(music);
} else if (IS_TAGGED(EVENT,
"stop-music")) {
STOP_MUSIC();
}
 values_
PLAYBACK - the playback object, the
engine running the bipsi game

AVATAR - the player avatar event

EVENT - the event being touched

PALETTE - the palette of the current room

DIALOGUE - await this to pause until

there's no dialogue left on screen
 functions_
await SAY(text) - show a normal dialogue
with the given text

await SAY_FIELD(name) - get the value of

the named field on the touched object and
call SAY with it

await TITLE(text) - show a title dialogue

with the given text

await DELAY(seconds) - await this to

pause for a length of time

MOVE(event, location) - take an event and

place it in another location

await WALK(event, route) - move an event

step by step along a route e.g
".<<.>>^^>>vv"
(walking doesn't touch events)
 functions_
SET(name, value) - set a named value to
be used later

GET(name, fallback) - get a named value,

or the fallback if named value has never

FIELD(event, name, type) - get the value

of the first field on an event with a
particular name and type

FIELDS(event, name, type) - get the

values of all fields on an event with a
particular name and type

SET_FIELDS(event, name, type, ...values)

- replace any existing fields of a
particular name and type on an event with
new values

await DO_STANDARD() - do all the standard

touch behaviour for the event (title,
say, exit, etc)
 functions_
EVENT_AT(location) - get the event
present at a location, if any

LOCATION_OF(event) - get the location of

an event

FIND_EVENT(tag) - get an event in the

game that has a certain tag

FIND_EVENTS(tag) - get all events in the

game that have a certain tag

IS_TAGGED(event, tag) - true if the event

has the named tag

TAG(event, tag) - add the named tag to

the event

UNTAG(event, tag) - remove the named tag

from the event
 functions_
SET_GRAPHIC(event, tile) - shortcut to
set the event's graphic field to another
tile (to change its appearance)

REMOVE(event) - remove an event from the

game

await TOUCH(event) - run the touch

behaviour of an event as if the player
avatar had touched it

await RUN_JS(javascript, event) - run

javascript as if it were a touch running
for a particular event

RESTART() - restart the game

SET_CSS(name, value) - set CSS value on

the root e.g "--page-color"
 functions_
SHOW_IMAGE(id, image, layer, x, y) -
replace any image at this id with a new
image shown at x,y and on or between the
following layers:
0: under everything
1: over tiles but under events
2: over events but under dialogue
3: over everything

HIDE_IMAGE(id) - hide the image being

shown with this id

PLAY_MUSIC(file) - switch looping music

to a music file

STOP_MUSIC() - stop looping music

FIELD_OR_LIBRARY(name) - the named field

on the touched event, if it is a file,
otherwise the field on the library event
whose name matches the text value of the
named field
 functions_
SAMPLE(id, mode, values) - complex
function for stepping through a sequence
over multiple touches

picks a value from a list of values

either shuffled, in a sequence, or
cycling

progress is remembered between event

touches using the given id (this also
allows multiple events to use the same
sequence)

id - named id to remember progress

mode - "shuffle", "cycle", or "sequence"
values - list of values to step through

javascript
let dialogue = SAMPLE("1", "cycle",
["hello", "heya", "hi"]);
await SAY(dialogue);
 custom functions_
you can add custom functions to use in
all touch scripts by adding a new
property to SCRIPTING_FUNCTIONS

if you want to use other scripting

functions or values, reference them with
this. e.g this.PLAYBACK or
this.REMOVE(this.EVENT) etc

this example adds a new function called

"test" that when called in a script with
test("candle") will show dialogue of
"hello candle":

javascript
SCRIPTING_FUNCTIONS.test = function
(name) {
this.PLAYBACK.say("hello " + name);
}
 plugin scripts_
plugins are an experimental feature that
give more powerful control over bipsi by
running custom code before the bipsi game
has even begun loading

add a plugin by choosing import plugin on

the "create event from template" screen
and selecting a javascript file

you can find some plugins javascript

files here:

https://github.com/seleb/bipsi-hacks

https://github.com/Ragzouken/bipsi/blob/m
ain/src/scripts/plugins/html-dialogue.js
 notes_
_________________________________________
_________________________________________
_________________________________________
_________________________________________
_________________________________________
_________________________________________
_________________________________________
_________________________________________
_________________________________________
_________________________________________
_________________________________________
_________________________________________
_________________________________________
_________________________________________
_________________________________________
_________________________________________
_________________________________________
_________________________________________
_________________________________________
_________________________________________
_________________________________________
_________________________________________
 about_
bipsi is a web tool for making simple
browser games in the bitsy style

kool.tools/bipsi

this scripting guide explains how to

begin using bipsi at an advanced level,
for those willing to mess with writing
javascript code

i'm mark wonnacott a.k.a candle, and i

created bipsi

kool.tools