Once documentation

1. Saying things

A Once program is a list of steps, one per line, run from the top. The simplest step is say, which prints a line to the Output panel. Text goes inside double quotes.

say "Once upon a time, there was a program."
say 2 + 3

Anything after -- is a note for people, and Once skips it. Inside text, a name in curly braces is replaced by its value.

-- This line is only for you.
set name to "Pip"
say "Hello, {name}! Two and two make {2 + 2}."

2. Keeping things

To keep a value, give it a name with set. To add to a number, use change ... by. Numbers, text, true, false and nothing are the plain kinds of value.

set score to 0
change score by 10
change score by -3
say "The score is {score}."

Lists

A list holds several values in square brackets. Lists count from one, so item 1 of a list is the first thing in it.

set pets to ["cat", "owl", "toad"]
add "fox" to pets
remove "owl" from pets
say item 1 of pets
say "There are {length of pets} pets: {join(pets, ", ")}."
say any of pets

any of picks one at random. You can also write pets[2] for the second item.

Records

A record is a small bundle of named values. Read one with 's, as in English.

set hero to {name: "Mo", hearts: 3}
change hero's hearts by -1
say "{hero's name} has {hero's hearts} hearts left."

3. Choosing

An if does its steps only when something is true. otherwise gives the other path, and every block ends with end.

set apples to random 1 to 10

if apples is 10
  say "A perfect ten!"
otherwise if apples is above 5
  say "Plenty of apples ({apples})."
otherwise
  say "Only {apples}. Time to pick more."
end

You can compare with is, is not, is above, is below, is at least and is at most, or with the signs =, !=, <, >, <= and >=. Join conditions with and, or and not. A one-step if can sit on one line with then, and needs no end.

set hour to 21
if hour is at least 20 and not (hour is 23) then say "Nearly bedtime."

4. Again and again

There are a few ways to repeat steps.

repeat 3 times
  say "Knock."
end

for each n from 1 to 5
  say "{n} little ducks"
end

for each pet in ["cat", "owl"]
  say "Goodnight, {pet}."
end

set x to 1
repeat until x is above 100
  set x to x * 2
end
say x

Inside a loop, stop leaves the loop early and skip jumps to the next turn. Counting can go in steps: for each n from 10 to 0 by -2.

repeat forever runs its steps once per frame, about sixty times a second, until the program ends. It never freezes the page.

5. Your own instructions

Teach Once a new word with to. List its inputs after the name, joined by and. Use it by writing its name with the values in brackets. give back hands a value back.

to greet who
  say "Good morning, {who}."
end

to area width and tall
  give back width * tall
end

greet("Pip")
say "A 3 by 4 rug covers {area(3, 4)} squares."

Instructions can call themselves, which is handy for counting down:

to countdown n
  if n is 0
    say "Lift off!"
  otherwise
    say n
    countdown(n - 1)
  end
end

countdown(3)

Once has some built-in instructions too, like sqrt, round and length. They are all in the appendix. An instruction with one input can be written with of: length of pets is the same as length(pets).

6. Drawing

The preview is 480 wide and 360 tall. The point 0, 0 is the top left corner, and y grows downward. You draw with draw, the name of a shape, and a few settings in any order.

background "#f4e9d2"
draw box at 240, 300 size 480, 120 color "#5f8a55"
draw circle at 380, 80 size 70 color "#d39b2a"
draw line from 120, 250 to 120, 170 color "#2a2118" width 6
draw circle at 120, 150 size 90 color "#3f6788"
draw text "A tree and a sun" at 16, 14 size 26

Colors are text: names like "tomato" and "skyblue", codes like "#3f6788", or rgb(255, 120, 0) and hsl(200, 60, 50). Things you draw stay on the page until you clear it.

Every frame

To animate, put your drawing inside every frame. Its drawings are wiped and redrawn sixty times a second, so they can move.

set x to 0

every frame
  change x by 3
  if x is above 520 then set x to -40
  draw circle at x, 180 + sin(x * 2) * 40 size 40 color "#b5452f"
end

7. Things that move

A shape made with new stays on screen by itself. You can keep it in a name, read its settings with 's, and change them while the program runs. It also understands a few more settings:

set gravity to 0.4
set ball to new circle at 100, 60 size 40 color "#b5452f" moving 3, 0 bouncy 0.9 solid
new box at 300, 260 size 160, 24 color "#2a2118" fixed solid

every frame
  draw text "x is {round(ball's x)}" at 12, 10 size 20
end

Setting gravity pulls every shape that isn't fixed. A shape's settings are x, y, dx, dy, size, width, height, color, bouncy, solid, fixed, hidden, angle and, for text, text. You can also give it settings of your own, like set ball's points to 5. remove ball takes it off the screen.

To ask whether two shapes overlap, use touches. The word edge means the border of the preview.

set coin to new circle at 400, 180 size 26 color "gold" fixed
set bug to new box at 40, 180 size 30 color "#5f8a55" moving 2, 0

every frame
  if bug touches coin
    remove coin
    set bug's dx to 0
    draw text "Got it!" at 190, 100 size 32
  end
end

8. Listening

A when block waits for something to happen, then runs its steps. Click the preview first so it gets keyboard input.

set hero to new box at 240, 300 size 40 color "#3f6788" bouncy 0

when key "space" is pressed
  set hero's dy to -9
end

when mouse is clicked
  new circle at mouse's x, mouse's y size 16 color "tomato"
end

set gravity to 0.5

every frame
  if holding "left" then change hero's x by -4
  if holding "right" then change hero's x by 4
end

holding "left" is true for as long as the key is down. Keys are named "left", "right", "up", "down", "space", "enter", or a letter like "a". The mouse is mouse's x, mouse's y and mouse's down.

You can also listen for shapes meeting. It happens once, at the moment they first touch.

set ball to new circle at 60, 60 size 30 moving 4, 3 bouncy
set wall to new box at 400, 180 size 20, 360 color "#2a2118" fixed

when ball touches edge
  play sound "click"
end

when ball touches wall
  set ball's dx to -4
  play sound "boop"
end

9. Sounds

play note plays a musical note by name, like "C4" (middle C), "F#5" or "Bb3". Add for to set how long it lasts in seconds, wave to change its voice ("triangle", "sine", "square" or "sawtooth"), and volume from 0 to 1.

for each n in ["C4", "E4", "G4", "C5"]
  play note n for 0.3
  wait 0.25 seconds
end
play note "C3" for 1 wave "sawtooth" volume 0.3

play sound plays one of the ready-made sounds: "beep", "boop", "coin", "jump", "pop", "hit", "boom" and "click".

10. Time, and the end

wait pauses for some seconds, while everything else keeps running. every 2 seconds repeats its steps on a clock. time is the seconds since the program started, and frame counts the frames.

say "Ready..."
wait 1 seconds
say "Steady..."
wait 1 seconds
say "Go!"

every 0.5 seconds
  new circle at random 20 to 460, 0 size 14 color "skyblue" moving 0, 3
end

every frame
  draw text "{round(time, 1)} seconds" at 12, 10 size 20
end

To end the program, write the end. Everything stops.

set hits to 0
set ball to new circle at 240, 60 size 30 moving 5, 4 bouncy

when ball touches edge
  change hits by 1
  play note 60 + hits
  if hits is 8 then the end
end

Reference: built-in instructions

Angles are in degrees. Lists count from one.

Names that are always there

width and height of the preview, mouse, edge, gravity, time, frame and pi.

When something goes wrong

Once explains mistakes in plain words. It shows the line, underlines the part it got stuck on, and often guesses what you meant:

set score to 0
say scroe

Run the example above to see the problem it reports.

On the command line

Programs are saved as .once files. With Node installed, the once command runs them in a terminal (everything except drawing and sound), checks them for mistakes, or turns one into a single web page you can share. To install it, and the VS Code extension, see the README.

once run main.once
once check main.once
once export main.once -o main.html