hyper bouba only has one place to keep things: the state. Everything you write either reads the state or writes to it. Keys are words you choose, and a dot groups related ones together.
Write a script that sets a few keys, then press run (or Ctrl+Enter):
put is how you set a value. The arrow reads left to right: put a number or word into the key. A bare word is a key whose value gets read. Double quotes mean the word itself.
Try changing the value. Change 10 to 42 and run it again.
Reading a key that was never set gives 0. Setting your keys in on init do makes a script easier to read. We will get to that.
put overwrites. add, sub, mul, and div change a key in place. clamp keeps a number between two bounds.
Each of these can read from another key instead of a literal number:
mul uses by. div uses into. clamp names the key first.
Some keys only need to be on or off. set turns one on. unset turns one off. toggle flips it.
toggle on a key that was never set starts at true.
bamagotchi calls two special functions in your script. on init do runs once, when the script first loads. on tick do runs about six times a second, forever. This is your game loop.
The cell above runs init first, then tick once, so you see the result together. Try running it a few times. The values stack each time.
Top-level code runs once, before any entry point. Function definitions are safe to repeat (bamagotchi runs your whole script on every tick), but other top-level commands are not. Put your setup inside on init do.
Name a function on btn.feed do and a button appears in the play view. Tap it and the function runs. Anything you write to ui.* shows up as a labelled stat chip.
The guide can not show buttons for real. Open bamagotchi and paste this script to give it a try.
A signal decouples the thing that happened from the things that react to it. The button emits. The hunger handler, the score handler, and the sound effect each connect themselves to the same signal.
Without signals, on btn.feed do has to call every reaction itself. Add a new reaction tomorrow and you edit the button. Signals let you add a reaction by writing a function and one connect line. The button never changes.
This is the most important rule in bamagotchi. Connect signals inside on init do, never at the top level. Your script runs again on every tick. A connect at the top level adds one more copy of the handler, every tick. At 16 copies the limit stops the growth and no error appears. The handler just runs 16 times per emit instead of once.
Signals carry data. Anything after the signal name becomes a parameter to the handler:
Handlers run in the order you connected them, and all of them finish before emit returns. If a handler calls emit itself, that second signal waits until the first is done. One signal at a time.
when runs one command if the condition is true. unless runs it if the condition is false. For more than one command, call a helper function.
The tests you can write: = and != for equality. < > <= >= for comparing numbers. has for checking if a list or text contains something. matches for seeing if text fits a pattern.
cond picks the first branch that passes. It must end with else. Branches are separated by commas, not newlines.
hyper bouba has no and or or. Chain two functions instead: the first checks one condition, the second checks the other.
A sprite is a 16 by 16 block of pixel art inside your script. X turns a pixel on. . leaves it off. The name after sprite becomes sprites.name, a list of 256 ones and zeros.
sprites.face is a list of 256 ones and zeros. Copying it into display.pixels tells bamagotchi to draw it to the 16 by 16 screen. In the main app, you will see the face. Here in the guide you see the state.
You can use X, #, 1, @, or * to turn a pixel on. Every other character leaves it off.
Build a list with list or range. Add to it with push. Read it with count, sum, first, last.
map changes every item. Inside, the item is called it. each runs a command for every item but changes nothing. filter keeps matching items.
with also gives you the position, counting from zero:
Put a key in curly braces inside double quotes to embed its value. This is how you build status messages:
str.scan pulls values out of text using a template:
{name} reads up to the next fixed part. {name:class} reads a run of one kind of character: digits, alpha, alnum, word, space, notspace. {name:*} takes everything left.
A function is a block of commands with a name. Call it by writing the name. Pass values by naming parameters:
Keys listed after local are removed when the function ends. A ref parameter lets the function write back to the caller's key:
The key you pass to a ref parameter must contain a dot. bump pet.score works. bump score writes nothing and shows no error.
Write multi-line function bodies. A one-line body that ends with end on the same line passes that word on as an argument:
log writes to the console at the bottom of the screen. Keys become their values. Use it while building things to see what is happening:
roll gives you a random number from 1 to n. seed makes the randomness repeat the same way every run, useful while testing:
asssert stops the script and says why if the condition fails. Use it to catch mistakes near where they happened:
From here, the ref tab has every command in detail, and the script tab has a creature waiting for you to build.