RocRay: A manual for building native games and interactive apps in Roc§

1. What RocRay is§

RocRay lets you write 2D games, visualizations, creative tools, and other interactive programs in Roc. It draws with raylib, a popular C library for games, and runs on macOS (Intel and Apple silicon), Linux x86-64, and Windows x86-64.

It suits programs that draw a fresh picture many times a second: arcade and puzzle games, simulations, live plots, generative art, and small editors.

RocRay draws in 2D today: shapes, images, and text, with 2D cameras, shaders, and offscreen drawing. 3D models, cameras, and lighting are planned but not yet available.

RocRay is for smaller graphical programs, such as games, visualizations, and interactive tools. It is not meant to compete with large, purpose-built game engines: it has no editor, scene graph, entity system, physics engine, or asset pipeline. Your app keeps its own state and makes every decision itself. RocRay provides drawing, sound, keyboard, mouse and gamepad input, the window, screen recording, files, and networking. If your app needs a scene graph or an entity system, build it in Roc or use a package.

RocRay is also not a GUI toolkit. For desktop applications built from widgets such as buttons, text fields, and layouts, see roc-gui.

If you already know raylib, Coming from raylib shows how its functions and habits map onto RocRay.

1.1. What you write§

A RocRay app is three functions:

• init! runs once, at startup. It chooses the window’s settings, loads what the app needs, and creates the starting state, which RocRay calls the model.

• update! receives the model and what just happened: which keys were pressed, how the mouse moved, and which tasks finished. It returns the next model.

• render! draws the model.

The host, the native program that runs your app, calls them in a loop. One pass around that loop is a host cycle: the host gathers what happened, calls update! once, and then calls render! to draw the result. Each picture render! draws is a frame. Normally every host cycle draws one frame, so a game running at 60 frames a second also runs 60 host cycles a second. The two differ only when the host skips drawing, for example while the window is minimized.

Reading a file or waiting for a network reply can take longer than one host cycle. Slow operations like these run as a task, so the app keeps updating and drawing while it waits. When the task finishes, its result arrives in a later update!.

The app model: init!, update!, and render! explains these pieces in full. You do not need them to run your first example. Glossary defines every term the manual uses.

1.2. What an app can access§

Every app can draw, read input, play sound, print to its terminal, and record itself. Anything more, such as a network service, a directory, another program, an environment variable, or the clipboard, must be declared in the app’s startup settings. So you can see what an app can access by reading its source. Permissions: what your app can access explains how.

1.3. What it looks like§

Three short examples are the best place to start: Hello World, a circle that follows the mouse; Pong, a complete game in one file; and Snake, a grid game you can restart.

These larger apps are also in the repository’s examples/ directory, roughly from simplest to most involved. Each links to its complete Roc source.

Breakout: arcade gameplay, sounds made in code, recording. Watch the recording.

Pixel Workshop: drawing pixels and creating sounds in code. Watch the recording.

Responsive Settings: keyboard, mouse, resizing, display scaling. Watch the recording.

Postcard Studio: generative art and saving larger images. Watch the recording.

Particles: thousands of moving images at once. Watch the recording.

Capture UI Demo: automated controls and GIF recording. Watch the recording.

Live Plot: loading and drawing hundreds of thousands of lines. Watch the recording.

Spark Run: a designed map, characters, music, game states. Watch the recording.

Cave Climb: a designed level, jumping, camera, sound. Watch the recording.

An app can also record itself to a video file, such as this WebM plot recording.

1.4. Stability§

RocRay follows the latest nightly build of the Roc compiler: neither the platform nor its examples name a compiler, and they are tested with the latest nightly every day. Because Roc is still changing, RocRay’s API may also change. Each RocRay release’s notes name the nightly it was built and tested with. Bug reports, documentation improvements, and focused new capabilities are welcome; see Contributing to RocRay.

2. Getting started§

In this chapter you install the Roc compiler, run a finished example, and write a small app of your own that draws a circle under the mouse pointer. You need a terminal and an internet connection. You do not need a copy of the RocRay repository.

Three words come up straight away:

Platform

The part of a Roc program that you do not write. Your app is pure Roc code; the platform supplies everything that touches the outside world, and RocRay is a platform for windows, drawing, sound, and input.

Bundle

The single downloadable file a release publishes the platform as. Your app names it by URL, and the compiler downloads it the first time it builds the app.

Host

The native program inside the bundle that runs your app: it opens the window, calls your code, and carries out what your code asks for.

Glossary defines these and the other terms the manual uses.

2.1. Install the Roc compiler§

Roc is a young language that is still changing, and it is distributed as nightly builds. RocRay follows the latest one: the latest RocRay release is tested with each new nightly, and its release notes also name the nightly it was built and tested with, on a line that begins Built and tested with Roc. Install the latest nightly.

1. Open the latest Roc nightly. Its name looks like nightly-<date>-<commit>.

2. Download the file for your computer. The date and commit in its name match the nightly’s name:

   Computer	File
   Linux, x86-64	roc_nightly-linux_x86_64-<date>-<commit>.tar.gz
   macOS, Apple silicon (M1 and later)	roc_nightly-macos_apple_silicon-<date>-<commit>.tar.gz
   macOS, Intel	roc_nightly-macos_x86_64-<date>-<commit>.tar.gz
   Windows, x86-64	roc_nightly-windows_x86_64-<date>-<commit>.zip

   RocRay does not support ARM Linux.

3. Extract it and put the extracted folder on your PATH, as described for your system below.

2.1.1. Linux and macOS§

Extract the archive in your home directory. It creates a folder with the same name as the file, holding the roc executable:

cd ~
tar -xzf ~/Downloads/roc_nightly-linux_x86_64-<date>-<commit>.tar.gz

Add the folder to your PATH by putting this line at the end of your shell’s startup file (~/.bashrc for bash, ~/.zshrc for zsh, the default on macOS), then open a new terminal:

export PATH="$HOME/roc_nightly-linux_x86_64-<date>-<commit>:$PATH"

Use the folder name you extracted. On macOS it starts with roc_nightly-macos_.

On macOS, the system refuses to run a program downloaded from the internet until you clear its quarantine mark. Clear it once, from inside the folder:

cd ~/roc_nightly-macos_apple_silicon-<date>-<commit>
xattr -d com.apple.quarantine roc

2.1.2. Windows§

1. Right-click the zip file and choose Extract All. Extract it to a folder you will keep, such as C:\roc. The extracted folder contains roc.exe.

2. Open Settings, search for "environment variables", and choose Edit environment variables for your account.

3. Select Path, choose Edit, then New, and enter the folder that contains roc.exe.

4. Close any open terminals and open a new PowerShell window.

2.1.3. Check the install§

Run:

roc version

It prints the compiler’s name:

Roc compiler version nightly-<date>-<commit>

If the terminal says it cannot find roc, the folder is not on your PATH in this terminal; open a new one, or check the path you added.

2.1.4. What your computer needs§

macOS

Nothing else.

Windows

A graphics driver that supports OpenGL 3.3. Any current driver does.

Linux

A glibc-based x86-64 distribution with a desktop. An app built with the default bundle uses X11, which also runs on Wayland desktops through XWayland. At run time it needs the X11 client libraries (libX11, libXrandr, libXinerama, libXcursor, libXi), an OpenGL 3.3 driver such as Mesa, and sound through PulseAudio, PipeWire, or ALSA. A desktop installation has all of these; a minimal or server installation may not.

Each release also publishes a Wayland bundle for Linux. Use the default bundle unless you specifically want native Wayland windows on Linux; the Wayland bundle needs libwayland-client, libxkbcommon, and EGL instead of the X11 libraries, and runs only on Linux. Reference lists both bundles.

2.2. Run an example§

Each release attaches a zip of the examples, named roc-ray-examples-<version>.zip, whose files already name that release’s bundle.

1. Open the RocRay releases page and choose the newest release whose name is a version number, such as 0.10.0. The page also lists dependency releases, such as "macOS linker interfaces"; skip those.

2. Download the zip from that release and extract it.

3. Open a terminal in the extracted folder: the one that contains examples/.

4. Run:

   roc examples/hello_world/main.roc
   

roc with a file name compiles the app and runs it. The first time, it also downloads the RocRay bundle, which takes a few seconds; later runs use the copy the compiler saved.

A window opens with a panel and a circle that follows the pointer. Hold the left mouse button to change its colour, and press Escape to quit. Every RocRay app quits on Escape unless the app turns this off.

Run examples from the extracted folder, as shown. The examples that load images or sounds find them by paths relative to that folder.

If an example fails to compile with errors in RocRay’s own modules, a new nightly may have changed something the release relies on. Check that roc version is the latest nightly; if it is, install the nightly the release notes name after "Built and tested with Roc", and report the failure.

2.3. Build an executable§

roc on its own compiles and runs the app each time. To produce an executable you can run again without compiling, use roc build:

roc build examples/hello_world/main.roc --output=hello_world
./hello_world

On Windows, write --output=hello_world.exe and run .\hello_world.exe. Ship your game explains how to give an app to other people.

2.4. The smallest app§

Make a new folder for your app, anywhere you like, such as hello in your home directory. Create a file named main.roc in it.

The file starts with a header. The header says this file is an app and names the platform it runs on by its bundle URL:

app [Model, program] { rr: platform "BUNDLE-URL" }

Replace BUNDLE-URL with the default bundle’s URL from the release notes. It looks like this, with a release’s version and the bundle’s hash filled in:

https://github.com/lukewilliamboswell/roc-ray/releases/download/<version>/<hash>.tar.zst

The simplest way to get it right is to copy the first line of examples/hello_world/main.roc from the examples zip.

Below the header, add the rest of the app:

import rr.App
import rr.Color
import rr.Draw

Model : { pointer : { x : F32, y : F32 } }

Msg : []

program = { init!, update!, render! }

init! : App.Init(Model, [])
init! = App.init(App.default.with_title("Hello"), |_io| Ok({ pointer: { x: 400, y: 300 } }))

update! : Model, App.Input(Msg), App.Io => Try(Model, [Exit(I64)])
update! = |_model, input, _io| Ok({ pointer: input.devices.mouse.position() })

render! : Model, Draw.Frame => Try({}, [Exit(I64)])
render! = |model, frame| {
	frame.clear!(Color.black)
	frame.circle!({ center: model.pointer, radius: 40, style: Draw.filled(Color.red) })
	Ok({})
}

Run it from the folder that contains main.roc:

roc main.roc

A window titled "Hello" opens, and a red circle follows the mouse pointer. Press Escape to quit.

If the compiler finds a problem, it prints a report that names the file, the line, and what it expected, and the app does not start. To check the file without running it, use roc check main.roc.

2.4.1. Reading the app§

import rr.App makes the platform’s App module available. rr is the name the header gave the platform, and App, Color, and Draw are three of its modules.

Model : { pointer : { x : F32, y : F32 } }

The model is everything your app remembers from one moment to the next. This line says the model is a record with one field, pointer, which holds a position: an x and a y, each an F32 (a 32-bit floating-point number).

Msg : []

Apps that wait for slow work, such as reading a file, receive the results later as messages. Msg lists the kinds of message this app can receive. The empty tag union [] means it receives none.

program = { init!, update!, render! }

The record of three functions the host calls. The header’s [Model, program] gives this record and the Model type to the platform.

init! : App.Init(Model, [])

init! runs once, at startup. App.init takes the window’s settings and a function that builds the first model. Here the settings are the defaults with a different title, and the function returns Ok(...) with the pointer at the window’s centre. The [] in the type lists the errors that function can return: none.

update! : Model, App.Input(Msg), App.Io => Try(Model, [Exit(I64)])

The host calls update! over and over while the app runs. Each call receives the current model, an App.Input describing what happened since the last call, and an App.Io, which the app uses to ask the host for things such as sound or files. It returns the next model wrapped in Ok, or Err(Exit(code)) to quit with that exit code. This one ignores the old model and returns a new one holding the mouse position.

render! : Model, Draw.Frame => Try({}, [Exit(I64)])

After each update!, the host calls render! to draw the new model. Everything it draws goes through frame. It returns Ok({}) when it has finished drawing. It can also return Err(Exit(code)), like update!; a bigger app uses that when a drawing step it depends on fails.

The ! at the end of a name, and the => in its type, mark a function that has effects: besides returning a value, it does something, such as drawing or reading the keyboard. Roc for RocRay explains this and the rest of the syntax.

You do not need to check for Escape yourself. The default settings quit on Escape; Closing the window shows how to change that.

2.5. Where to go next§

1. Read Roc for RocRay if Roc is new to you. It covers exactly the syntax a small RocRay app uses.

2. Follow Your first game, which grows this app into a small game in six steps.

3. Then read The app model: init!, update!, and render!, and the guides for the features your app needs.

Example gallery suggests which examples to read, and the API reference documents every module, type, and function.

3. Roc for RocRay§

This chapter teaches the parts of Roc that a small RocRay app uses, and no more. Read it once before Your first game, and come back to it when you do not understand a line of code. Each section links to the matching page of the Roc language reference, which covers the whole language.

Roc is a functional language. A value never changes once it exists. To "change" something, such as your app’s model, you build a new value from the old one and return it. RocRay is organised around that idea: update! takes the current model and returns the next one.

3.1. Values and blocks§

Give a value a name with =. The name keeps that value for as long as it is in scope, and the compiler warns if you define the same name twice.

speed = 480.F32

title = "Paddle"

lives = 3.U64

480.F32 is the number 480 as an F32, a 32-bit floating-point number. RocRay uses F32 for positions, sizes and times, U64 for counts, and I64 for exit codes. A string goes in double quotes. See Constants and Numbers.

A block is a pair of braces holding some lines of code. It evaluates to its last line, and the names defined inside it are not visible outside:

area = {
	width = 800.F32
	height = 600.F32
	width * height
}

A line starting with # is a comment; ## starts a documentation comment. See Expressions.

3.2. Records§

A record groups named values, called fields. Read a field with a dot. To get a record with one field changed, write .. and the old record, then the fields to replace:

paddle = { x: 340.F32, y: 560.F32, width: 120.F32 }

paddle_x = paddle.x

moved = { ..paddle, x: paddle.x + 10 }

moved is a new record; paddle is unchanged. Apps use this form in almost every update!: Ok({ ..model, score: model.score + 1 }).

When a name already holds the value a field should have, you can write the name alone. { x, y } means { x: x, y: y }:

make_point = |x, y| { x, y }

For a record with one field, add the trailing comma, or write the field in full. roc fmt puts a record with a trailing comma on separate lines, one field per line:

make_score = |score| {
	score,
}

make_score_in_full = |score| { score: score }

See Records.

3.3. Types, type aliases, and nominal types§

A line of the form name : Type states a value’s type. The compiler checks that the value matches. Annotations are optional in Roc, but RocRay’s functions are always annotated, and yours should be, because they make the compiler’s error messages much clearer.

A type alias gives a type a name. It uses a single colon, and the name starts with a capital letter:

Point : { x : F32, y : F32 }

origin : Point
origin = { x: 0, y: 0 }

An alias is only another name: any record with an x and a y of type F32 is a Point. Your app’s Model is usually an alias, such as Model : { paddle_x : F32, score : U64 }.

A nominal type is a new type that is not interchangeable with anything else, even a type with the same contents. It is declared with :=, or with :: when other modules must not see inside it. It can have functions of its own, called methods, in a .{ } block after it:

Lives := U64.{
	lose_one : Lives -> Lives
	lose_one = |Lives.(count)| Lives.(count - 1)
}

Inside the module that declares it, Lives.(count) builds a Lives from a number, or takes one apart. You rarely need to declare a nominal type in a small app, but you use the platform’s all the time. Draw.Frame, Audio.Sound, App.Config and App.Input are nominal types. You cannot build one from its contents; the platform gives you one, such as App.default, and you change it with its methods. See Type aliases and Nominal types.

3.4. Tags, tag unions, and match§

A tag is a capitalised name that is a value in its own right, such as PaddleHit or KeyLeft. A tag union is a type listing the tags a value can be, in square brackets. match chooses what to do for each one:

Event : [PaddleHit, BallLost, Nothing]

points_for : Event -> U64
points_for = |event|
	match event {
		PaddleHit => 1
		BallLost => 0
		Nothing => 0
	}

The compiler checks that a match handles every tag. A branch written _ handles everything the branches above it did not.

A tag can hold values, called its payload:

Shape : [Circle(F32), Box(F32, F32)]

area_of : Shape -> F32
area_of = |shape|
	match shape {
		Circle(radius) => 3.14159 * radius * radius
		Box(width, height) => width * height
	}

RocRay uses tags throughout: keys (KeySpace), options (Capped(60)), and outcomes (Exit(0)). Msg : [] is a tag union with no tags. See Tag unions and Pattern matching.

if and else choose between two values. Both branches must have the same type:

direction_for : Bool, Bool -> F32
direction_for = |left_down, right_down|
	if left_down {
		-1
	} else if right_down {
		1
	} else {
		0
	}

See if and else.

3.5. Functions§

A function is written |arguments| body. Its type lists the argument types, an arrow, and the result type. Call it with parentheses:

double : F32 -> F32
double = |x| x * 2

clamp_speed : F32, F32 -> F32
clamp_speed = |value, limit| if (value > limit) limit else value

double(21) is 42. See Functions.

3.5.1. Pure and effectful functions§

Most functions are pure: the result depends only on the arguments, and calling one does nothing else. A pure function’s type uses a thin arrow, ->.

An effectful function does something beyond returning a value: it draws, plays a sound, reads the keyboard, or writes a file. Its type uses a thick arrow, =>, and its name ends in !:

play_for! : Event, Audio.Sound => {}
play_for! = |event, hit_sound|
	match event {
		PaddleHit => hit_sound.play!()
		_ => {}
	}

Only an effectful function can call another effectful function. So the ! tells you, at a glance, every place where your app interacts with the world outside it. All three RocRay callbacks, init!, update! and render!, are effectful, and the platform’s effectful functions, such as frame.circle! and sound.play!, are the only way your app can draw on the screen or play through the speakers.

Keep your game logic in pure functions and call them from update!. Pure functions are easy to test, as Tests with expect shows. See Effectful functions.

3.6. Try, Ok, Err, and ?§

A function that can fail returns a Try: either Ok(value) or Err(error). Its type lists both, and the error is a tag union naming every way it can fail. Audio.gen_tone! returns Try(Audio.Sound, [SoundGenerationFailed, ResourceLimit]).

Writing ? after a call unwraps an Ok, or returns the Err from the enclosing function at once:

Sounds : { hit : Audio.Sound, miss : Audio.Sound }

make_sounds! : {} => Try(Sounds, [SoundGenerationFailed, ResourceLimit])
make_sounds! = |{}| {
	hit = Audio.gen_tone!({ freq: 660, ms: 60 })?
	miss = Audio.gen_tone!({ freq: 160, ms: 300 })?
	Ok({ hit, miss })
}

Because ? can return early, the enclosing function’s error list must include every error its ? calls can produce. When you add a ? on a call that fails in a new way, the compiler tells you to add that error to the list. That is how init! : App.Init(Model, []) grows into init! : App.Init(Model, [SoundGenerationFailed, ResourceLimit]) once init! generates a sound.

RocRay treats one error specially. A callback that returns Err(Exit(code)) ends the app with that exit code. Any other error returned to the host also ends the app, with a message naming the callback and the error. See The ? operator.

3.7. Tuples§

A tuple holds a fixed number of values in order, in parentheses. It is a handy way to return two things from a function. Take it apart by writing the same shape on the left of =:

split_score : U64 -> (U64, U64)
split_score = |score| (score // 10, score % 10)

tens_digit = {
	(tens, _ones) = split_score(42)
	tens
}

See Tuples.

3.8. Methods and static dispatch§

A method is a function that belongs to a type. You call it with a dot after a value of that type: value.method(arguments). The value becomes the first argument. The compiler picks the function from the value’s type, which Roc calls static dispatch:

config = App.default.with_title("Paddle").with_size({ width: 800, height: 600 })

score_text = (42.U64).to_str()

same_text = U64.to_str(42)

App.default is an App.Config, so .with_title("Paddle") calls the with_title method of App.Config, which returns a new config; the next .with_size(...) is called on that one. (42.U64).to_str() and U64.to_str(42) are the same call.

The same holds for the platform’s effects: frame.circle!(...) calls the circle! method of Draw.Frame with frame as its first argument. See Methods.

A string can include a value with ${...}. RocRay’s text drawing uses this with to_str to show a number:

frame.text_at!({ pos: { x: 20, y: 20 }, text: "Score: ${model.score.to_str()}", size: 24, color: Color.white })

See Strings.

3.9. Imports§

The header gives the platform a short name, rr in every RocRay app. An import line makes one of its modules available, and you then use the module’s name in front of what it provides, such as Draw.filled or App.init:

import rr.App
import rr.Audio
import rr.Color
import rr.Draw

The API reference lists every RocRay module and what each provides. See Imports.

3.10. Tests with expect§

An expect at the top level of a file is a test. It must evaluate to true (Bool.True):

expect double(2) == 4

expect points_for(PaddleHit) == 1

expect {
	(tens, ones) = split_score(42)
	tens == 4 and ones == 2
}

roc test main.roc runs every expect and reports the ones that fail. An expect cannot call an effectful function, which is one more reason to keep your game logic pure. Testing your app shows how to test an app’s logic. See Statements.

3.11. What this chapter leaves out§

Roc has more: lists and their functions, for and while loops, variables with var, dictionaries, and more. The RocRay examples use them, and the language reference explains them when you meet them.

4. Your first game§

In this chapter you build Paddle, a small game: bounce a ball off a paddle at the bottom of the screen, score a point for each hit, and lose a life for each miss. You build it in six steps. After each step you have a complete program to run and play with.

Along the way you meet the ideas every RocRay game uses: moving things by time, keeping them on screen, collision, drawing text, sound, and restarting.

Before you start, run the smallest app from The smallest app, and read Roc for RocRay if Roc is new to you.

4.1. How to follow along§

Work in the folder that holds your smallest app. Each step replaces the whole of main.roc except its first line, the header you already have:

app [Model, program] { rr: platform "BUNDLE-URL" }

The listings below start after that line. Paste one in below your header, save the file, and run roc main.roc. Press Escape to quit.

The complete files are in the repository’s docs/tutorial directory, as step1.roc to step6.roc. Their headers point at the repository’s own copy of the platform rather than at a release.

4.2. Step 1: a paddle that moves§

import rr.App
import rr.Color
import rr.Draw

paddle_width = 120.F32

paddle_height = 16.F32

paddle_y = 560.F32

paddle_speed = 480.F32

Model : { paddle_x : F32 }

Msg : []

program = { init!, update!, render! }

init! : App.Init(Model, [])
init! = App.init(App.default.with_title("Paddle"), |_io| Ok({ paddle_x: 340 }))

update! : Model, App.Input(Msg), App.Io => Try(Model, [Exit(I64)])
update! = |model, input, _io| {
	dt = input.time.elapsed_seconds
	direction =
		if input.devices.key_down(KeyLeft) {
			-1
		} else if input.devices.key_down(KeyRight) {
			1
		} else {
			0
		}
	Ok({ paddle_x: model.paddle_x + direction * paddle_speed * dt })
}

render! : Model, Draw.Frame => Try({}, [Exit(I64)])
render! = |model, frame| {
	frame.clear!(Color.black)
	frame.rectangle!({ x: model.paddle_x, y: paddle_y, width: paddle_width, height: paddle_height, style: Draw.filled(Color.white) })
	Ok({})
}

The model is one number: the paddle’s left edge, paddle_x. render! draws a white rectangle there, near the bottom of the window.

Positions are in the window’s logical units. The default window is 800 units wide and 600 tall. x grows to the right and y grows downward, so (0, 0) is the top-left corner and paddle_y = 560 is near the bottom.

The host calls update! once per host cycle, typically 60 or more times a second. Each call reads the arrow keys: input.devices.key_down(KeyLeft) is true while the left arrow key is held. direction becomes -1, 1, or 0.

input.time.elapsed_seconds is how much time has passed since the previous host cycle, such as 0.016 at 60 cycles a second. Multiplying the paddle’s speed by it turns "480 units per second" into "how far to move this cycle". The paddle then moves at the same speed on a fast computer that runs 240 host cycles a second and on a slow one that runs only 30. Move things by time, never by a fixed amount per cycle.

Run it and hold an arrow key. The paddle moves, and it keeps going straight off the edge of the window. Step 2 fixes that.

4.3. Step 2: keep it on the screen§

import rr.App
import rr.Color
import rr.Draw
import rr.Math

screen_width = 800.F32

paddle_width = 120.F32

paddle_height = 16.F32

paddle_y = 560.F32

paddle_speed = 480.F32

# The longest time one cycle may advance the game by, in seconds.
max_dt = 0.05.F32

Model : { paddle_x : F32 }

Msg : []

program = { init!, update!, render! }

init! : App.Init(Model, [])
init! = App.init(App.default.with_title("Paddle"), |_io| Ok({ paddle_x: 340 }))

update! : Model, App.Input(Msg), App.Io => Try(Model, [Exit(I64)])
update! = |model, input, _io| {
	dt = Math.clamp(input.time.elapsed_seconds, 0, max_dt)
	direction =
		if input.devices.key_down(KeyLeft) {
			-1
		} else if input.devices.key_down(KeyRight) {
			1
		} else {
			0
		}
	Ok({ paddle_x: move_paddle(model.paddle_x, direction, dt) })
}

render! : Model, Draw.Frame => Try({}, [Exit(I64)])
render! = |model, frame| {
	frame.clear!(Color.black)
	frame.rectangle!({ x: model.paddle_x, y: paddle_y, width: paddle_width, height: paddle_height, style: Draw.filled(Color.white) })
	Ok({})
}

move_paddle : F32, F32, F32 -> F32
move_paddle = |x, direction, dt|
	Math.clamp(x + direction * paddle_speed * dt, 0, screen_width - paddle_width)

Two things changed.

The paddle’s movement is now a function of its own, move_paddle. It is pure: it takes the old position, the direction, and the time, and returns the new position. Math.clamp(value, low, high) limits a number to a range, so the paddle’s left edge stays between 0 and screen_width - paddle_width.

The elapsed time is clamped too, to at most max_dt, a twentieth of a second. elapsed_seconds is the real time since the previous host cycle. Usually that is a small fraction of a second, but when the computer is briefly busy with something else, or you drag the window, one cycle can report half a second or more. A game that moves by that much in one step makes things jump: a fast ball can pass straight through the paddle without ever touching it. With the clamp, the game slows down briefly instead. Uneven cycle times shows a fixed-step alternative for games that must advance exactly the same way every time.

4.4. Step 3: a ball that bounces§

import rr.App
import rr.Color
import rr.Draw
import rr.Math

screen_width = 800.F32

screen_height = 600.F32

paddle_width = 120.F32

paddle_height = 16.F32

paddle_y = 560.F32

paddle_speed = 480.F32

ball_radius = 10.F32

# The longest time one cycle may advance the game by, in seconds.
max_dt = 0.05.F32

Ball : { pos : Math.Vec2, velocity : Math.Vec2 }

Model : { paddle_x : F32, ball : Ball }

Msg : []

program = { init!, update!, render! }

serve : Ball
serve = { pos: { x: screen_width / 2, y: 120 }, velocity: { x: 220, y: 260 } }

init! : App.Init(Model, [])
init! = App.init(App.default.with_title("Paddle"), |_io| Ok({ paddle_x: 340, ball: serve }))

update! : Model, App.Input(Msg), App.Io => Try(Model, [Exit(I64)])
update! = |model, input, _io| {
	dt = Math.clamp(input.time.elapsed_seconds, 0, max_dt)
	direction =
		if input.devices.key_down(KeyLeft) {
			-1
		} else if input.devices.key_down(KeyRight) {
			1
		} else {
			0
		}
	Ok({
		paddle_x: move_paddle(model.paddle_x, direction, dt),
		ball: move_ball(model.ball, dt),
	})
}

render! : Model, Draw.Frame => Try({}, [Exit(I64)])
render! = |model, frame| {
	frame.clear!(Color.black)
	frame.rectangle!({ x: model.paddle_x, y: paddle_y, width: paddle_width, height: paddle_height, style: Draw.filled(Color.white) })
	frame.circle!({ center: model.ball.pos, radius: ball_radius, style: Draw.filled(Color.yellow) })
	Ok({})
}

move_paddle : F32, F32, F32 -> F32
move_paddle = |x, direction, dt|
	Math.clamp(x + direction * paddle_speed * dt, 0, screen_width - paddle_width)

move_ball : Ball, F32 -> Ball
move_ball = |ball, dt| {
	x = ball.pos.x + ball.velocity.x * dt
	y = ball.pos.y + ball.velocity.y * dt
	off_left = x < ball_radius and ball.velocity.x < 0
	off_right = x > screen_width - ball_radius and ball.velocity.x > 0
	vx = if (off_left or off_right) -ball.velocity.x else ball.velocity.x
	vy = if (y < ball_radius and ball.velocity.y < 0) -ball.velocity.y else ball.velocity.y
	if y > screen_height + ball_radius {
		serve
	} else {
		{ pos: { x, y }, velocity: { x: vx, y: vy } }
	}
}

The model now holds a Ball as well: a position and a velocity, each a Math.Vec2, which is a record with an x and a y. The velocity is in units per second, and serve is where each ball starts: near the top, heading down and to the right.

move_ball moves the ball by its velocity times the elapsed time. When the ball has passed the left or right wall and is still moving toward it, the function flips the sign of the horizontal velocity, which sends the ball back. The top wall does the same for the vertical velocity. Checking the direction as well as the position matters: a ball that is already heading back must not be flipped again, or it would stick to the wall.

Nothing stops the ball at the bottom yet. When it falls below the window, move_ball returns serve and the ball starts again from the top.

render! draws the ball with frame.circle! after the paddle. Later drawing covers earlier drawing, so draw from back to front.

4.5. Step 4: hit the ball and keep score§

import rr.App
import rr.Color
import rr.Draw
import rr.Math

screen_width = 800.F32

screen_height = 600.F32

paddle_width = 120.F32

paddle_height = 16.F32

paddle_y = 560.F32

paddle_speed = 480.F32

ball_radius = 10.F32

speed_up = 1.05.F32

# The longest time one cycle may advance the game by, in seconds.
max_dt = 0.05.F32

Ball : { pos : Math.Vec2, velocity : Math.Vec2 }

Model : { paddle_x : F32, ball : Ball, score : U64 }

Event : [PaddleHit, BallLost, Nothing]

Msg : []

program = { init!, update!, render! }

serve : Ball
serve = { pos: { x: screen_width / 2, y: 120 }, velocity: { x: 220, y: 260 } }

init! : App.Init(Model, [])
init! = App.init(App.default.with_title("Paddle"), |_io| Ok({ paddle_x: 340, ball: serve, score: 0 }))

update! : Model, App.Input(Msg), App.Io => Try(Model, [Exit(I64)])
update! = |model, input, _io| {
	dt = Math.clamp(input.time.elapsed_seconds, 0, max_dt)
	direction =
		if input.devices.key_down(KeyLeft) {
			-1
		} else if input.devices.key_down(KeyRight) {
			1
		} else {
			0
		}
	(next, _event) = advance(model, direction, dt)
	Ok(next)
}

render! : Model, Draw.Frame => Try({}, [Exit(I64)])
render! = |model, frame| {
	frame.clear!(Color.black)
	frame.rectangle!({ x: model.paddle_x, y: paddle_y, width: paddle_width, height: paddle_height, style: Draw.filled(Color.white) })
	frame.circle!({ center: model.ball.pos, radius: ball_radius, style: Draw.filled(Color.yellow) })
	frame.text_at!({ pos: { x: 20, y: 20 }, text: "Score: ${model.score.to_str()}", size: 24, color: Color.white })
	Ok({})
}

advance : Model, F32, F32 -> (Model, Event)
advance = |model, direction, dt| {
	paddle_x = move_paddle(model.paddle_x, direction, dt)
	(ball, event) = move_ball(model.ball, paddle_x, dt)
	next = { ..model, paddle_x, ball }
	match event {
		PaddleHit => ({ ..next, score: next.score + 1 }, event)
		BallLost => ({ ..next, score: 0 }, event)
		Nothing => (next, event)
	}
}

move_paddle : F32, F32, F32 -> F32
move_paddle = |x, direction, dt|
	Math.clamp(x + direction * paddle_speed * dt, 0, screen_width - paddle_width)

move_ball : Ball, F32, F32 -> (Ball, Event)
move_ball = |ball, paddle_x, dt| {
	x = ball.pos.x + ball.velocity.x * dt
	y = ball.pos.y + ball.velocity.y * dt
	off_left = x < ball_radius and ball.velocity.x < 0
	off_right = x > screen_width - ball_radius and ball.velocity.x > 0
	vx = if (off_left or off_right) -ball.velocity.x else ball.velocity.x
	vy = if (y < ball_radius and ball.velocity.y < 0) -ball.velocity.y else ball.velocity.y
	paddle = Math.rect(paddle_x, paddle_y, paddle_width, paddle_height)
	touching = Math.circle_rect(Math.circle({ x, y }, ball_radius), paddle)
	if vy > 0 and touching {
		({ pos: { x, y }, velocity: { x: vx * speed_up, y: -vy * speed_up } }, PaddleHit)
	} else if y > screen_height + ball_radius {
		(serve, BallLost)
	} else {
		({ pos: { x, y }, velocity: { x: vx, y: vy } }, Nothing)
	}
}

The ball now bounces off the paddle. Math.circle_rect reports whether a circle and a rectangle overlap. When the ball touches the paddle while moving down, move_ball sends it back up, a little faster each time (speed_up).

move_ball also says what happened, as an Event: a tag union of PaddleHit, BallLost, and Nothing. It returns the new ball and the event together, as a tuple.

advance holds all of the game logic for one host cycle: move the paddle, move the ball, then count the event. A hit adds a point and a miss resets the score. Like move_paddle and move_ball, advance is pure, and update! just calls it. update! does not use the event yet, and the _ at the start of _event tells the compiler that the value is unused on purpose.

frame.text_at! draws a string with the built-in font. The string is built with ${...}, and model.score.to_str() turns the score into text.

4.6. Step 5: add sound§

import rr.App
import rr.Audio
import rr.Color
import rr.Draw
import rr.Math

screen_width = 800.F32

screen_height = 600.F32

paddle_width = 120.F32

paddle_height = 16.F32

paddle_y = 560.F32

paddle_speed = 480.F32

ball_radius = 10.F32

speed_up = 1.05.F32

# The longest time one cycle may advance the game by, in seconds.
max_dt = 0.05.F32

Ball : { pos : Math.Vec2, velocity : Math.Vec2 }

Model : {
	paddle_x : F32,
	ball : Ball,
	score : U64,
	hit_sound : Audio.Sound,
	miss_sound : Audio.Sound,
}

Event : [PaddleHit, BallLost, Nothing]

Msg : []

program = { init!, update!, render! }

serve : Ball
serve = { pos: { x: screen_width / 2, y: 120 }, velocity: { x: 220, y: 260 } }

init! : App.Init(Model, [SoundGenerationFailed, ResourceLimit])
init! = App.init(
	App.default.with_title("Paddle"),
	|_io| {
		hit_sound = Audio.gen_tone!({ freq: 660, ms: 60 })?
		miss_sound = Audio.gen_tone!({ freq: 160, ms: 300 })?
		Ok({ paddle_x: 340, ball: serve, score: 0, hit_sound, miss_sound })
	},
)

update! : Model, App.Input(Msg), App.Io => Try(Model, [Exit(I64)])
update! = |model, input, _io| {
	dt = Math.clamp(input.time.elapsed_seconds, 0, max_dt)
	direction =
		if input.devices.key_down(KeyLeft) {
			-1
		} else if input.devices.key_down(KeyRight) {
			1
		} else {
			0
		}
	(next, event) = advance(model, direction, dt)
	match event {
		PaddleHit => next.hit_sound.play!()
		BallLost => next.miss_sound.play!()
		Nothing => {}
	}
	Ok(next)
}

render! : Model, Draw.Frame => Try({}, [Exit(I64)])
render! = |model, frame| {
	frame.clear!(Color.black)
	frame.rectangle!({ x: model.paddle_x, y: paddle_y, width: paddle_width, height: paddle_height, style: Draw.filled(Color.white) })
	frame.circle!({ center: model.ball.pos, radius: ball_radius, style: Draw.filled(Color.yellow) })
	frame.text_at!({ pos: { x: 20, y: 20 }, text: "Score: ${model.score.to_str()}", size: 24, color: Color.white })
	Ok({})
}

advance : Model, F32, F32 -> (Model, Event)
advance = |model, direction, dt| {
	paddle_x = move_paddle(model.paddle_x, direction, dt)
	(ball, event) = move_ball(model.ball, paddle_x, dt)
	next = { ..model, paddle_x, ball }
	match event {
		PaddleHit => ({ ..next, score: next.score + 1 }, event)
		BallLost => ({ ..next, score: 0 }, event)
		Nothing => (next, event)
	}
}

move_paddle : F32, F32, F32 -> F32
move_paddle = |x, direction, dt|
	Math.clamp(x + direction * paddle_speed * dt, 0, screen_width - paddle_width)

move_ball : Ball, F32, F32 -> (Ball, Event)
move_ball = |ball, paddle_x, dt| {
	x = ball.pos.x + ball.velocity.x * dt
	y = ball.pos.y + ball.velocity.y * dt
	off_left = x < ball_radius and ball.velocity.x < 0
	off_right = x > screen_width - ball_radius and ball.velocity.x > 0
	vx = if (off_left or off_right) -ball.velocity.x else ball.velocity.x
	vy = if (y < ball_radius and ball.velocity.y < 0) -ball.velocity.y else ball.velocity.y
	paddle = Math.rect(paddle_x, paddle_y, paddle_width, paddle_height)
	touching = Math.circle_rect(Math.circle({ x, y }, ball_radius), paddle)
	if vy > 0 and touching {
		({ pos: { x, y }, velocity: { x: vx * speed_up, y: -vy * speed_up } }, PaddleHit)
	} else if y > screen_height + ball_radius {
		(serve, BallLost)
	} else {
		({ pos: { x, y }, velocity: { x: vx, y: vy } }, Nothing)
	}
}

Audio.gen_tone! makes a short beep at a pitch you choose, in hertz, lasting the number of milliseconds you give. init! makes two, a high one for a hit and a low one for a miss, and keeps them in the model so they are made only once.

Making a sound can fail, so init! uses ? on each call and its error list grows from [] to [SoundGenerationFailed, ResourceLimit]. If either error happens, the app stops at startup and prints which one.

update! now uses the event advance returns. It plays the matching sound with play!, which starts the sound and returns at once. Playing a sound is an effect: a call into the host. update! may call an effect that returns at once, like this one. An effect that has to wait, such as reading a file, belongs in a task instead; Tasks: operations that wait explains why.

4.7. Step 6: lives, game over, and tests§

import rr.App
import rr.Audio
import rr.Color
import rr.Draw
import rr.Math

screen_width = 800.F32

screen_height = 600.F32

paddle_width = 120.F32

paddle_height = 16.F32

paddle_y = 560.F32

paddle_speed = 480.F32

ball_radius = 10.F32

speed_up = 1.05.F32

# The longest time one cycle may advance the game by, in seconds.
max_dt = 0.05.F32

starting_lives = 3.U64

Ball : { pos : Math.Vec2, velocity : Math.Vec2 }

Model : {
	paddle_x : F32,
	ball : Ball,
	score : U64,
	lives : U64,
	hit_sound : Audio.Sound,
	miss_sound : Audio.Sound,
}

Event : [PaddleHit, BallLost, Nothing]

Msg : []

program = { init!, update!, render! }

serve : Ball
serve = { pos: { x: screen_width / 2, y: 120 }, velocity: { x: 220, y: 260 } }

init! : App.Init(Model, [SoundGenerationFailed, ResourceLimit])
init! = App.init(
	App.default.with_title("Paddle"),
	|_io| {
		hit_sound = Audio.gen_tone!({ freq: 660, ms: 60 })?
		miss_sound = Audio.gen_tone!({ freq: 160, ms: 300 })?
		Ok({
			paddle_x: 340,
			ball: serve,
			score: 0,
			lives: starting_lives,
			hit_sound,
			miss_sound,
		})
	},
)

update! : Model, App.Input(Msg), App.Io => Try(Model, [Exit(I64)])
update! = |model, input, _io| {
	if model.lives == 0 {
		if input.devices.key_pressed(KeySpace) {
			Ok(new_game(model))
		} else {
			Ok(model)
		}
	} else {
		dt = Math.clamp(input.time.elapsed_seconds, 0, max_dt)
		direction =
			if input.devices.key_down(KeyLeft) {
				-1
			} else if input.devices.key_down(KeyRight) {
				1
			} else {
				0
			}
		(next, event) = advance(model, direction, dt)
		match event {
			PaddleHit => next.hit_sound.play!()
			BallLost => next.miss_sound.play!()
			Nothing => {}
		}
		Ok(next)
	}
}

render! : Model, Draw.Frame => Try({}, [Exit(I64)])
render! = |model, frame| {
	frame.clear!(Color.black)
	frame.rectangle!({ x: model.paddle_x, y: paddle_y, width: paddle_width, height: paddle_height, style: Draw.filled(Color.white) })
	frame.circle!({ center: model.ball.pos, radius: ball_radius, style: Draw.filled(Color.yellow) })
	frame.text_at!({ pos: { x: 20, y: 20 }, text: "Score: ${model.score.to_str()}", size: 24, color: Color.white })
	frame.text_at!({ pos: { x: 680, y: 20 }, text: "Lives: ${model.lives.to_str()}", size: 24, color: Color.white })
	if model.lives == 0 {
		frame.text_at!({ pos: { x: 230, y: 280 }, text: "Game over. Press Space.", size: 32, color: Color.red })
	}
	Ok({})
}

# The rules of the game. These functions are pure, so `roc test` can check them.

new_game : Model -> Model
new_game = |model| {
	..model,
	paddle_x: 340,
	ball: serve,
	score: 0,
	lives: starting_lives,
}

advance : Model, F32, F32 -> (Model, Event)
advance = |model, direction, dt| {
	paddle_x = move_paddle(model.paddle_x, direction, dt)
	(ball, event) = move_ball(model.ball, paddle_x, dt)
	next = { ..model, paddle_x, ball }
	match event {
		PaddleHit => ({ ..next, score: next.score + 1 }, event)
		BallLost => ({ ..next, lives: next.lives - 1 }, event)
		Nothing => (next, event)
	}
}

move_paddle : F32, F32, F32 -> F32
move_paddle = |x, direction, dt|
	Math.clamp(x + direction * paddle_speed * dt, 0, screen_width - paddle_width)

move_ball : Ball, F32, F32 -> (Ball, Event)
move_ball = |ball, paddle_x, dt| {
	x = ball.pos.x + ball.velocity.x * dt
	y = ball.pos.y + ball.velocity.y * dt
	off_left = x < ball_radius and ball.velocity.x < 0
	off_right = x > screen_width - ball_radius and ball.velocity.x > 0
	vx = if (off_left or off_right) -ball.velocity.x else ball.velocity.x
	vy = if (y < ball_radius and ball.velocity.y < 0) -ball.velocity.y else ball.velocity.y
	paddle = Math.rect(paddle_x, paddle_y, paddle_width, paddle_height)
	touching = Math.circle_rect(Math.circle({ x, y }, ball_radius), paddle)
	if vy > 0 and touching {
		({ pos: { x, y }, velocity: { x: vx * speed_up, y: -vy * speed_up } }, PaddleHit)
	} else if y > screen_height + ball_radius {
		(serve, BallLost)
	} else {
		({ pos: { x, y }, velocity: { x: vx, y: vy } }, Nothing)
	}
}

expect move_paddle(0, -1, 0.5) == 0
expect move_paddle(screen_width - paddle_width, 1, 0.5) == screen_width - paddle_width

expect {
	falling = { pos: { x: 400, y: screen_height }, velocity: { x: 0, y: 300 } }
	(_, event) = move_ball(falling, 0, 0.1)
	event == BallLost
}

expect {
	above_paddle = { pos: { x: 400, y: paddle_y - ball_radius }, velocity: { x: 0, y: 300 } }
	(ball, event) = move_ball(above_paddle, 350, 0.01)
	event == PaddleHit and ball.velocity.y < 0
}

The player now has three lives. A miss costs one, and the score no longer resets. When the last life is gone, update! stops advancing the game, and render! shows "Game over". Pressing Space calls new_game, which returns the model to its starting state but keeps the sounds.

key_pressed(KeySpace) is true only on the host cycle when Space went down, while key_down stays true for as long as a key is held. Use key_pressed for actions that happen once per press. Input, time, and the window covers the keyboard and mouse in full.

update! only calls advance while at least one life is left, so next.lives - 1 never goes below zero. A U64 cannot hold a negative number, and subtracting past zero stops the app.

At the end of the file are four tests. Because the game logic is in pure functions, a test can call them directly, with any situation you like. Run the tests with:

roc test main.roc

4.8. Run it without a window§

A built RocRay app can also run headless: without a window, graphics or sound, for a set number of host cycles. Nothing is drawn, but init! and update! run as usual, so this catches a crash in the game’s logic:

roc build main.roc --output=paddle
./paddle --host-headless --host-headless-frames=60

The repository checks every step of this chapter this way. Testing your app covers headless runs and scripted key presses.

4.9. Where to go next§

Some ideas for changing Paddle:

• Make the ball start in a random direction. Randomness shows how to use randomness.

• Add a row of bricks for the ball to break. The Breakout example does this.

• Draw the paddle with rounded corners using frame.rounded_rectangle!. See Drawing.

Then read The app model: init!, update!, and render!, which explains init!, update! and render! in full, and the Pong example, a larger game built the same way.

5. Example gallery§

The repository’s examples/ directory holds complete apps and focused recipes. This chapter helps you choose which to read. It assumes you have run an example, as Run an example shows.

Each example is a directory with a main.roc. Choose the one closest to what you want to build and copy its directory. For the released examples, download the examples zip described in Run an example. The examples in the repository name the platform in the checkout instead, and may use APIs that have not been released yet; Run examples against your checkout shows how to run them.

Run every command from the directory that contains examples/, so the paths the examples use for their files resolve. To try an example, run it with roc:

roc examples/snake/main.roc

To build an executable you can run again, use roc build:

roc build examples/snake/main.roc --output=snake
./snake

Every example quits when you press Escape unless its header says otherwise.

5.1. Start here§

Work through these in order. Each one adds a little to the one before it.

1. Hello World (hello_world): the complete app loop (init!, update!, and render!) with drawing and the pointer, and nothing else.

2. Move Box (move_box): a box moved with the arrow keys. It introduces moving by speed times elapsed time, and a pure function tested with expect. Your first game grows the same idea into a whole game, one step at a time; Move Box shows the finished result on one page, ready to copy.

3. Sprite and Sound (sprite_and_sound): a picture and a sound loaded from files. It introduces a permission, an asset store, and loaded resources.

4. Pong (pong): one player against a computer paddle. It combines movement, collision, input, scoring, and sounds made in code in one approachable file.

5. Snake (snake): a grid game split across a few modules, with a fixed simulation step and seeded randomness.

6. Task Sleep (task_sleep): one task that waits, and the message it sends back. Read it before adding files, networking, or any other operation that waits.

Then pick a direction:

• A game: Breakout, then Spark Run or Cave Climb.

• A tool or an app interface: Pixel Workshop, Responsive Settings, or Input Inspector.

• Files, networking, or storage: the examples under Tasks that wait.

• A particular drawing technique: the Focused recipes.

5.2. Small apps worth copying§

5.3. Tasks that wait§

Use these when copying the Task.spawn!(input, || ...) pattern described in Tasks: operations that wait. A task’s return value arrives as one Msg on a later input.messages.

5.4. Larger showcases§

Use these to see several systems working together in one app.

5.5. Focused recipes§

Use these as focused references, not starter projects.

5.6. Conventions used here§

• Each app names its three functions' parameters the same way: init! takes io, update! takes model, input, io and reads devices through devices = input.devices, and render! takes model, frame.

• Keep application state in Model; compute the next model from App.Input in pure helper functions that update! calls.

• Load and prepare long-lived resources once in init!, then keep them in the model instead of recreating them every host cycle.

• Derive layout and view-only values with pure helpers. Use frame.size!() for the surface being drawn to instead of copying input.window.size into the model.

• Move by elapsed time, and clamp it: after a pause, one host cycle can report a second or more.

• Call host effects directly from update! when they return immediately; use Task.spawn!(input, || ...) for anything that waits, and update the model with its result when it arrives as a message on a later input.messages.

• Give each kind of task its own Msg variant. Add an id only when several tasks of the same kind may be running at once.

• Keep game logic in pure functions so roc test can check them without calling effectful update!.

• Let App.default handle Escape. An app that needs Escape for itself sets with_exit_key(NoExitKey) and says why, as Input Inspector does.

• Keep capture, scripted input, and headless runs out of ordinary interaction: an example never saves, records, or quits by itself during an interactive run.

Exhaustive API probes and invalid-input cases belong in the repository’s test/ directory, where they can be explicit without making an example harder to understand.

5.7. Recording the gallery§

The animations in the repository README are recorded by the examples themselves. Breakout, Pixel Workshop, Responsive Settings, Postcard Studio, Particles, Spark Run, and Live Plot each take a --record-demo argument:

roc examples/breakout/main.roc -- --record-demo

The window stays hidden, a scripted demo plays through the app’s normal input path, and the recording is written to examples/gallery/<directory>.gif. The app exits once the file is written. Every one of these apps follows the same shape: a demo_recording value, started in init! when the argument is present, and a pure demo_finished that ends the run when input.capture reports the recording Finished or Failed.

5.8. Permissions in the examples§

An example declares, in its startup config, anything it accesses beyond its own resources, as Permissions: what your app can access describes. Nothing is passed on the command line.

Every other example declares nothing. Printing, drawing, audio, sounds and textures made in code, a dropped file, and captures written beneath the output directory all need no declaration.

The recording examples list PermissionDenied among the errors init! can return. It comes from Capture.Writer.start!, whose result type includes it; the io that init! receives always has permission to record, so in these examples it does not occur.

6. The app model: init!, update!, and render!§

Every RocRay app has the same shape: three functions that the host calls at the right moments. This chapter explains what each one receives, what it may do, and what it returns. Every later guide builds on it.

The three functions are separate because each has one job. init! sets things up once. update! is the only place where the model changes, so you always know where to look for a change. render! only draws the model, so what you see on screen always matches the app’s state. Anything slow runs outside update! and render!, so the window never freezes while the app waits. Why it is shaped this way explains each of these rules.

It assumes you have run the smallest app in Getting started.

6.1. A complete app§

Here is a whole app. It draws a red dot under the pointer and counts your clicks. The rest of this chapter takes it apart.

app [Model, program] { rr: platform "BUNDLE-URL" }

import rr.App
import rr.Color
import rr.Draw
import rr.Text

Model : {
    title : Text.Prepared,
    pointer : { x : F32, y : F32 },
    clicks : U64,
}

Msg : []

program = { init!, update!, render! }

init! : App.Init(Model, [ResourceLimit])
init! = App.init(
    App.default.with_title("Clicker"),
    |_io| {
        font = Draw.default_font!()
        title = Text.from("Click anywhere", font).size(32).prepare!()?
        Ok({ title: title, pointer: { x: 400, y: 300 }, clicks: 0 })
    },
)

update! : Model, App.Input(Msg), App.Io => Try(Model, [Exit(I64)])
update! = |model, input, _io| {
    mouse = input.devices.mouse
    clicks = if mouse.button_pressed(Left) model.clicks + 1 else model.clicks
    Ok({ ..model, pointer: mouse.position(), clicks: clicks })
}

render! : Model, Draw.Frame => Try({}, [Exit(I64)])
render! = |model, frame| {
    frame.clear!(Color.black)
    model.title.draw!(frame, { pos: { x: 400, y: 40 }, color: Color.white, align: (Top, Center) })
    frame.text_at!({ pos: { x: 20, y: 560 }, text: "Clicks: ${model.clicks.to_str()}", size: 20, color: Color.white })
    frame.circle!({ center: model.pointer, radius: 18, style: Draw.filled(Color.red) })
    Ok({})
}

Replace BUNDLE-URL as The smallest app describes. Press Escape or close the window to quit.

The app’s header, app [Model, program], gives two things to the platform: the type of its state, Model, and program, a record of its three callbacks. Msg is the type of the messages its tasks send back; this app starts no tasks, so Msg is the empty tag union [].

A name ending in ! is an effectful function: calling it can do something beyond computing a value, such as drawing or opening a window. Its type uses => where a pure function’s uses ->. See Functions in the Roc language reference.

6.2. The loop§

The host calls the three callbacks in a loop:

init! runs once. After that, each time around the loop is one host cycle: the host gathers everything that happened since the previous cycle into one input, calls update! exactly once with it, and then normally calls render! with the model update! returned. Each call to render! produces one frame: one image in the window. A headless or minimized run may skip drawing, but it never calls update! twice with the same input.

6.3. The model§

The model is your app’s state: everything it needs to remember from one cycle to the next. You choose its type and name it Model. The clicker keeps a prepared title, the pointer position, and a count:

Model : {
    title : Text.Prepared,
    pointer : { x : F32, y : F32 },
    clicks : U64,
}

Only update! produces a new model. The host keeps the model between calls, but never reads or changes it. Keep long-lived resources you create in init!, such as textures, fonts, sounds, prepared text, and file handles, in the model rather than creating them again every cycle.

6.4. init!: configuration and the first model§

init! pairs a startup configuration with a function that builds the first model:

init! : App.Init(Model, [ResourceLimit])
init! = App.init(
    App.default.with_title("Clicker"),
    |_io| {
        font = Draw.default_font!()
        title = Text.from("Click anywhere", font).size(32).prepare!()?
        Ok({ title: title, pointer: { x: 400, y: 300 }, clicks: 0 })
    },
)

The function returns a Try: Ok(model) to start the app, or Err(...) to stop it. The ? after prepare!() returns early with the error if preparing the text fails; see Operators.

The second type argument of App.Init lists every error the function may return. Here it is ResourceLimit, the one error prepare! can produce. When you call something else with ?, add its errors to this list; the compiler names any that are missing. Returning Err(Exit(code)) quits before the first frame with that exit code. Any other error stops the app with a message naming init! and the error.

6.4.1. The startup configuration§

App.default is an 800 by 600 window titled "RocRay", capped at 240 frames per second, that quits when Escape is pressed. Change it with its with_* methods. A method is a function called with a dot on a value, like App.default.with_title("Clicker"); see Static dispatch.

A configuration that depends on the command line uses App.init_for_args instead of App.init. Its first argument is a pure function from the complete argument list to a Config, chosen before the window exists:

init! = App.init_for_args(
    |args| if List.contains(args, "--record") { App.default.with_visible(Bool.False) } else { App.default },
    |_io| Ok(initial_model),
)

Here initial_model stands for whatever first model your app builds.

6.4.2. What init! can do§

The function init! runs receives App.Io, the app’s access to host services (files, the network, printing, and so on). init! is the one place an app may wait for the outside world without a task: loading a texture or reading a file there simply delays startup until the result is ready, before the first frame is drawn.

A few effects are legal only in init!, because they return information that is fixed when the app starts:

• io.args!() returns the command line, with the host’s own --host-* switches removed. Keep what you need from it in the model.

• io.entropy!() gets a random number from the operating system to seed a random generator (see Randomness).

• io.default_font!() returns the font configured with with_default_font.

• io.env().read!(name) reads a declared environment variable.

6.5. update!: one input in, one model out§

update! : Model, App.Input(Msg), App.Io => Try(Model, [Exit(I64)])
update! = |model, input, _io| {
    mouse = input.devices.mouse
    clicks = if mouse.button_pressed(Left) model.clicks + 1 else model.clicks
    Ok({ ..model, pointer: mouse.position(), clicks: clicks })
}

update! receives the current model, one App.Input, and the same App.Io that init! had. It returns Ok with the next model, or Err(Exit(code)) to stop the app with that exit code. { ..model, pointer: ... } is a copy of model with some fields replaced; see Records.

App.Input contains everything the host collected for this cycle:

update! may call host effects directly: play a sound, resize the window, print a line, start a recording. Those happen immediately, in the order they are written. What update! must not do is wait. An effect that can wait, such as reading a file, sending a request, or sleeping, is refused in update!. Run it in a task instead, and its result arrives in a later input. Tasks: operations that wait shows how.

6.6. render!: draw the model§

render! : Model, Draw.Frame => Try({}, [Exit(I64)])
render! = |model, frame| {
    frame.clear!(Color.black)
    model.title.draw!(frame, { pos: { x: 400, y: 40 }, color: Color.white, align: (Top, Center) })
    frame.text_at!({ pos: { x: 20, y: 560 }, text: "Clicks: ${model.clicks.to_str()}", size: 20, color: Color.white })
    frame.circle!({ center: model.pointer, radius: 18, style: Draw.filled(Color.red) })
    Ok({})
}

render! receives the model update! just returned and a Draw.Frame. Everything it draws goes through that frame. It returns {}, not a model: it cannot change the app’s state. Drawing covers what a frame can draw.

Because render! gets no input, anything that moves on screen must be read from the model. An animation keeps its clock in the model, advanced in update! from input.time.elapsed_seconds.

6.7. Where each kind of code goes§

One rule covers almost every case:

• Drawing goes in render!.

• Anything that waits (files, the network, sleeping) goes in a task, or in init! before the app starts.

• Everything else (reading input, changing the model, playing a sound, starting a task) goes in update!.

If you break the rule, the app stops at once with a message that names the effect you called, the callback you called it from, and where it belongs. For example, reading a file from update! stops the app and tells you to move the read into a task. Details: which effects are legal where lists the rule for every kind of effect.

6.8. Closing the window§

An app ends when update! returns Err(Exit(code)). The user can also end it:

• Pressing the exit key ends the app at once, before update! sees the press. App.default uses Escape; change it with with_exit_key(ExitKey(key)), or turn it off with with_exit_key(NoExitKey) when the app needs Escape for itself, such as to open a pause menu.

• Clicking the window’s close button closes the window. By default the app ends at once, and update! never sees it happen.

Ending at once suits most games. But tasks that are still running when the app ends are cancelled, so an app with unsaved work needs a chance to finish it first. Such an app, for example one that saves the game, can ask to be notified instead, with with_close_request(Deliver). The window then stays open, and the next input has input.window.close_requested set to Bool.True for one cycle. A request is never lost. The app decides when to end by returning Err(Exit(code)):

Msg : [Saved(Try({}, Files.WriteError))]

update! = |model, input, _io| {
    saved = List.any(input.messages, |msg| match msg { Saved(_) => Bool.True })
    if saved {
        # The save finished, successfully or not: now end the app.
        Err(Exit(0))
    } else if input.window.close_requested and !model.saving {
        # Write the save file on a task, and keep running until it finishes.
        saves = model.saves
        text = encode_save(model)
        Task.spawn!(input, || Saved(saves.write_text!("save.txt", text)))
        Ok({ ..model, saving: Bool.True })
    } else {
        Ok(model)
    }
}

Here model.saves is a writable directory handle opened in init! (see Files, assets, and databases), and encode_save is the app’s own pure function that turns the model into text. Tasks: operations that wait explains Task.spawn!. An app that must not lose a save can show an error and keep running on Saved(Err(_)) instead of exiting.

The exit key is not a close request. It ends the app directly, with or without Deliver, and so does a press of it scripted in a test (see Testing your app). With App.default, Escape still quits without saving. An app that must save on every way out also sets with_exit_key(NoExitKey) and handles the key it wants in update!.

When the app exits, tasks still running are cancelled. That is why the save waits for its message before exiting, rather than exiting straight away.

6.9. Messages§

Msg is the type of the values your tasks return. An app that starts no tasks writes Msg : []. One that loads a level might write:

Msg : [LevelLoaded(Try(Str, Files.ReadTextError))]

Finished tasks' messages arrive in input.messages. update! applies each one to the model in turn, usually with List.fold and a pure helper:

Ok(List.fold(input.messages, model, apply_message))

Tasks: operations that wait explains where messages come from and shows apply_message in full.

6.10. Keep the decisions pure§

update! is effectful, so roc test cannot call it. Keep the decisions it makes in pure functions that take the model and input: which message changes what, whether to quit, and which tasks to start. Then let update! carry out what they decide. Those functions are ordinary Roc and can be tested with expect. Testing your app shows how to build inputs and resources for such tests.

6.11. Why it is shaped this way§

If you have written a game in C, you know the classic loop:

while (!WindowShouldClose()) {
    PollInput();
    UpdateGame(GetFrameTime());
    BeginDrawing();
    DrawGame();
    EndDrawing();
}

RocRay’s loop is the same loop: update! is UpdateGame, and render! is DrawGame. What RocRay adds are a few rules about what each part may do. Each rule has a benefit:

• Nothing waits in update! or render!. In the C loop, one careless fopen or HTTP request in the middle of a level makes the game freeze for as long as the disk or network takes. In RocRay that call is refused, so a cycle can only be as slow as your own code and the drawing it asks for. Waiting happens on a task, and the loop keeps going.

• Everything that changes arrives in the input. Keys, time, finished tasks, and window events all arrive in update! as data. A test can build an input by hand, a headless run can script one, and a recording can reproduce one. The same model and the same inputs lead to the same decisions.

• render! only draws. A frame shows exactly the model update! produced, so a screenshot or a recording shows what the game actually decided. That is also why render! cannot read the clock: a frame that read the time would differ from one recording to the next.

• Tasks run one at a time, on the same thread as your callbacks. Nothing runs in parallel with your code, so there are no locks, no data races, and no half-updated model.

• Decisions are made in pure functions. Code that does not call the host can be tested with expect, without a window, a GPU, or a sound card.

Roc’s type system cannot express "this function may be called from update! but not from render!", so these rules are checked when the app runs: the first time a callback breaks one, the app stops with a message naming the effect, the callback it was called from, and the fix. Run your app early and often, and read the message when it happens.

If you need something before the game can start, such as a file that must be read first, do it in init!, which is allowed to wait.

6.12. Details: which effects are legal where§

This section is a reference; the one-line rule above covers most apps. The host checks every effect against the current callback so that the rules in Why it is shaped this way always hold: nothing waits in update! or render!, and render! only draws.

The host always knows which callback it is inside: init!, update!, render!, or a task. It calls this the phase. Every effect states the phases it is legal in, in its API documentation, using one of a few rules:

render! is deliberately narrow. It must draw exactly the model update! produced, so that a frame, a screenshot, or a recording is an exact picture of what the app decided. An effect that changes host state, or reads something that differs from run to run such as the clock or a file, would break that. So it is refused in render! even when it does not wait. The few queries in the table above are allowed because they cannot change what happens next, and reading them allocates nothing.

io.exit!(code) is for places that cannot return Err(Exit(code)), such as a task. The app ends after the current cycle finishes.

6.13. Further reading§

• Architecture states these rules precisely and explains why RocRay chose them.

• The App page of the API reference documents every configuration method and App.Input field.

7. Input, time, and the window§

Each host cycle, update! receives an App.Input describing what happened since the previous cycle. This chapter covers the keyboard, mouse, gamepads, typed text, time, the window, and dropped files. It assumes The app model: init!, update!, and render!.

7.1. Two kinds of information§

An input contains two different kinds of information, and the difference matters when you read it:

• A state sample is the latest value at the moment the cycle began: whether a key is held, where the pointer is, how far a gamepad stick is pushed.

• An interval event is something that happened since the previous input: a key press, a release, a click, a wheel notch, a typed character.

A key tapped quickly between two cycles is never held at a cycle boundary, but the press and the release still arrive as events. RocRay records keyboard, mouse-button, wheel, and text events as the window system delivers them, so every such event appears in the next input; none is silently lost.

7.2. The keyboard§

Read keys through the devices snapshot:

devices = input.devices
jump = devices.key_pressed(KeySpace)     # went down this cycle
running = devices.key_down(KeyLeftShift) # held right now
released = devices.key_released(KeyW)    # came up this cycle

Keys are tags such as KeySpace, KeyW, KeyLeft, and KeyEnter; the Keys page of the API reference lists them all.

key_pressed and key_released mean "at least once since the previous input". Several presses of the same key in one interval count as one. When the count or the order matters, read devices.events instead (see The ordered event record). A double tap is one example. Text editing is another, where a key press can come between two typed characters.

By default, Escape is the exit key: it ends the app before update! sees the press, so you do not check for it yourself. An app that wants Escape for something else, such as a pause menu, turns that off with App.default.with_exit_key(NoExitKey). The window’s close button still ends the app; Closing the window shows how to handle it yourself.

7.2.1. Typed text§

devices.text_input holds the Unicode codepoints typed since the previous input, in the order typed and according to the user’s keyboard layout. Use it for a name entry box or a chat line, rather than working out characters from key presses. Up to 32 codepoints are delivered per input; if more were typed, the rest are discarded and devices.text_input_overflow is set.

7.3. The mouse§

mouse = input.devices.mouse
pointer = mouse.position()           # { x, y } in window coordinates
held = mouse.button_down(Left)
clicked = mouse.button_pressed(Left)
scroll = mouse.wheel_delta()         # every notch this interval, summed

Positions use the same logical coordinates as drawing: x grows to the right and y grows downward, starting from the window’s top-left corner. mouse.delta() is the movement since the previous input.

Change the cursor’s shape with Mouse.set_cursor! and its mode with Mouse.set_cursor_mode!(Hidden) or Mouse.set_cursor_mode!(Locked). Both are legal in init!, update!, and tasks.

7.4. Gamepads§

The host samples up to four gamepads once per cycle. They are named One, Two, Three, and Four, following the operating system’s numbering; a single controller is almost always One. input.devices.gamepad(id) returns Connected(pad), where pad is a view you can query, or Disconnected:

stick = match input.devices.gamepad(One) {
    Connected(pad) => pad.left_stick()
    Disconnected => { x: 0, y: 0 }
}

Buttons use layout-neutral names: FaceDown is the bottom face button, whatever its label says. So pad.button_pressed(FaceDown) is "jump" on any controller.

Gamepad buttons are state samples only. The host compares this cycle’s sample with the previous one to compute button_pressed and button_released, so a press and release that both happen between two samples is not seen. At 60 cycles a second, that is a tap shorter than about 17 milliseconds. This is rare for a deliberate press, but it can happen when a player presses a button very rapidly, or when the frame rate drops. For anything that must never be missed, use a held button, not a single press or release. Gamepads never appear in devices.events.

7.5. The ordered event record§

devices.events lists every key press and release, click, wheel notch, and typed character since the previous input, in the order they arrived, across all of those sources:

Event : [
    KeyPressed(Keys.Key),
    KeyReleased(Keys.Key),
    ButtonPressed(Mouse.Button, { x : F32, y : F32 }),
    ButtonReleased(Mouse.Button, { x : F32, y : F32 }),
    Wheel({ x : F32, y : F32 }),
    Text(U32),
]

Each click includes the pointer position where it happened. The list holds up to 256 events per input; if more arrive, the rest are discarded and devices.events_overflow is set. The combined values (key_pressed, the wheel sum, text_input) are still updated when the list is full.

7.6. Time§

input.time describes this cycle:

• elapsed_seconds is how much time passed since the previous cycle, in seconds. The first cycle reports 0.

• cycle_count counts cycles from zero.

Move things by speed times elapsed time, and they move at the same speed whatever the frame rate. With plain records:

dt = input.time.elapsed_seconds
position = {
    x: model.position.x + model.velocity.x * dt,
    y: model.position.y + model.velocity.y * dt,
}

The Math module has the same arithmetic ready-made. Make a vector with Math.vec2(x, y) and store it as a Math.Vec2; its methods add, sub, scale, length, and normalize then read as one line:

# With position : Math.Vec2 and velocity : Math.Vec2 in the model:
position = model.position.add(model.velocity.scale(dt))

Time.now!() reads the wall clock as a UTC Time.Timestamp, for things like naming a save file. It does not wait, and it is legal in init!, update!, and tasks. Use input.time, not the wall clock, for animation and movement.

7.6.1. Uneven cycle times§

elapsed_seconds is the real time between two cycles, and it varies. A cycle is usually a few milliseconds, but the operating system decides: while the user drags the window, or while you pause the app in a debugger, no cycles run, and the next cycle reports all the time that passed, possibly several seconds. The host reports that value as it is, without limiting it, because only the app knows how it should handle a long pause. So a simple position + velocity * dt can move a player straight through a wall.

The simplest protection is to clamp the elapsed time before you use it, so one cycle never advances the game by more than a limit you choose. Paddle in Your first game uses a twentieth of a second, and most examples use a quarter:

dt = Math.clamp(input.time.elapsed_seconds, 0, 0.25)

Physics and collision work best with a fixed step: the game always advances by exactly the same small amount, say 1/60 of a second, and runs as many of those steps each cycle as fit in the elapsed time. Because every step is the same size, the result does not depend on how fast the computer is or how uneven the cycles are: the same input always moves things the same way, and no single step is large enough to carry an object through a wall.

Leftover time is kept in the model for the next cycle. Each of those advances is a simulation step, and one host cycle may run zero, one, or several of them:

step_seconds : F32
step_seconds = 1 / 60

## Run as many whole steps as fit in `banked`, the time saved so far,
## and return the time left over.
run_steps : World, F32 -> (World, F32)
run_steps = |world, banked| {
    if banked < step_seconds {
        (world, banked)
    } else {
        run_steps(simulate(world), banked - step_seconds)
    }
}

# In update!:
dt = Math.clamp(input.time.elapsed_seconds, 0, 0.25)
(world, accumulator) = run_steps(model.world, model.accumulator + dt)
Ok({ ..model, world: world, accumulator: accumulator })

Here World is the part of your model that the game logic updates, and simulate is your own pure function that advances it by one step. Snake moves its snake this way. Architecture explains the difference between a host cycle and a simulation step.

Some runs report a fixed elapsed_seconds rather than a measured one. A headless run (see Testing your app) reports exactly 1/60 of a second every cycle, and a recording with FixedStep timing reports exactly one recording frame’s worth (see Screenshots and recordings). Those are the runs you can repeat and get the same result, provided the input, the random seed, and any task results are the same too.

7.6.2. Randomness§

Keep a Random.State in the model and take random values from it with pure generators, so a run can be reproduced from its seed. Seed it once in init!, from io.entropy!() for a run that should vary, or from a constant for one that must reproduce:

# In init!:
rng = Random.seed(U64.to_u32_wrap(io.entropy!()))

Each call to Random.step returns a value and the next state. Keep the state, or the next call returns the same value again:

x = Random.step(model.rng, Random.f32(0, 800))
Ok({ ..model, rng: x.state, star: { x: x.value, y: 0 } })

Random.f32(low, high) gives an F32, ready to use as a position. The integer generators, such as Random.bounded_i32(0, 9), give integers; convert one before mixing it with positions, for example I32.to_f32(column.value) * 60.

7.7. The window§

input.window reports:

• size, the window’s { width, height };

• focused, whether it has keyboard focus;

• minimized, whether it is minimized. A minimized window still runs cycles, so an app that should pause while minimized checks this.

• close_requested, whether the user asked to close it this cycle. It is only ever set when the app asked for close requests with with_close_request(Deliver); see Closing the window, which shows how to save before the app ends.