Skip to main content

Refall

A falling-block puzzle game across 61 hand-directed universes, each staged by the music: pieces fall on the beat and the pace follows the song. Play the game's Voyage, or any music you like: your own folders or YouTube playlists.

Watch the trailer

uvx refall

Or download the game itself, nothing to install: the Windows .exe, the Linux AppImage or the macOS app (Apple silicon; Intel).

Universes

Each song plays in one of them, in one of its variants.


VECTOR
phosphor beams on a dark CRT

SUMI
ink on washi paper

DIORAMA
a sunlit clay miniature on an island

ABYSS
the deep sea, lit only by living things

SMOKE
a dark stage, slow smoke and one hard spotlight

WATERCOLOR
watercolor on cold-press paper

POLAR NIGHT
a snowfield under the stars, aurora ribbons

RISOGRAPH
a two-ink risograph print

WHITE ROOM
a seamless white studio, matte blocks and soft shadows

KINTSUGI
dark polished stone, ceramic pieces mended with gold

LASER SHOW
every piece projected by its own laser in a dark haze

GARDEN
tiles of earth growing pixel grass and flowers

BIOME
glass cubes of water or seeds bringing a 3D world to life

FLUO
fluorescent paint splashed on a dark wall

MARBLES
glass marbles in square tiles

PRISM
glass cubes in the dark, crossed by slow beams of light

LIGHTSOURCE
dim room where the falling piece is the light

NOTEPAD
a squared notebook drawn by hand in stop motion

CITY
a tower's facade in a night city, its lit rooms the blocks

TOPOGRAPHY
contour map whose terrain is the stack, rain carving it

HEAT
a thermal camera

BLUEPRINT
a technical drawing

RECYCLE
sorting recyclables on a table

ELECTRON
bare silicon dies on a dark substrate

LANTERNS
paper lanterns on a night lake

ORIGAMI
folded paper pieces on a sheet

RAINY WINDOW
a rainy night window, the city blurred behind

BRICKS
glossy toy bricks in a photo studio

CRYSTAL CAVE
gemstone pieces in a geode cave

SWISS POSTER
a vintage travel poster in flat design

LIMBO
black silhouettes in a luminous fog

NEON
glowing watercolor shapes in a spectrum over a painted night skyline

SONAR
sonar echoes lighting a sunken world

GLOWING FOREST
a night forest in relief print and neon inks

DOCKS
a container port at dusk in 3D

BAUHAUS
a Bauhaus poster

CELESTIAL OCEAN
a sea of clouds at night under a big moon

MANGA
a manga color page in ink, screentones and watercolor washes

BRUTALIST
raw concrete under a hard sun in 3D

TILES
a great wall mosaic of tesserae

GIANT TREE
a toon world tree shooting up with every cleared line

MYCELIUM
a glowing fungal network growing over the forest floor at night

MEGACITY
a riverbank hut growing into a megacity

ORBITAL STATION
a space station building itself in orbit

LIBRARY
the blocks are books

SKY WHALE
a koi in a pond growing into a sky whale

PLANKS
wooden plank blocks in a white studio

TIDE POOL
a rock pool at low tide, seen from above

LOST PANDA
a little panda lost in the city at night

TERRARIUM
a sealed glass jar on a windowsill

CORAL REEF
a sunny shallow reef that grows with every cleared line

FRACTAL
an infinite pastel flower

ARCHITECT
a modern villa built over the song by two tower cranes

ISLANDS
a flight over an endless tropical archipelago, like drone footage

RAIN
rain everywhere over a colorful street at dusk

PINK VIBE
a soft pink world of satin ribbons in relief

SHADOW
a little model of the game on a table, lit by a projector

MIRROR
glass cubes in a liminal room, softly lit

RUINS
time runs backwards over the song

PIXEL
native low-resolution pixel art, sixteen colors, dithered skies

GLACIER
ice cubes melting into a rising pool in an ice cave

Every universe, its variants and the transitions: docs/universes.md. To make one: docs/adding-a-universe.md.

Modes

  • Voyage: a campaign of 15 stages, each a few songs in chosen universes, faster and faster, on EASY, NORMAL, HARD or EXPERT.
  • Free play: any folders, files or YouTube playlists, at the difficulty and starting level you pick.

Menu details and the Voyage file format: docs/reference.md.

Install

PyPI

Windows: download Refall-windows-x64.exe and run it: one file, nothing to install.

Linux: download Refall-linux-x86_64.AppImage (aarch64), make it executable (chmod +x Refall-linux-x86_64.AppImage) and run it.

macOS: open Refall-macos-arm64.dmg (Apple silicon; Intel) and drag Refall to Applications. It is not signed by an Apple developer: the first time, right-click it and choose Open (or System Settings > Privacy & Security > Open Anyway).

These three fetch yt-dlp, ffmpeg and Deno (about 100 MB, into the game's cache) at the first YouTube song.

Packages for Linux, macOS and Windows are on PyPI. Run them with uv as above, or install them:

pipx install refall        # or: uv tool install refall
refall

YouTube needs a JavaScript runtime (Deno or Node.js) on your system.

Controls

Keyboard and gamepad both work, at the same time.

Action Keyboard Gamepad
Move ← → D-pad / left stick
Soft / hard drop ↓ / Space Down / Up
Rotate ↑ or X (Z or J to rotate left) A (B/X to rotate left)
Hold C / Shift (tap) LB / RB
Slow motion (when the gauge is full) V / E ZL / ZR (LT / RT)
Next universe (with --universe: its next variant, a new seed) T Y
Next song N / Tab / Enter / PageDown Back
Pause (its menu: continue, the controls, back to the menu; Q quits at once) Esc / P Start
Fullscreen F / F11

Testing keys, gamepad mappings and playing from a phone: docs/reference.md.

Tools

  • refall-scope [songs...]: see what the game hears (structure, beats, spectrum).
  • refall-voyage-viewer [campaign]: watch the computer play through a campaign.

Both ship with the package (uvx --from refall refall-scope). Every option and how the music drives the game: docs/reference.md.

Build from source

sudo apt install cmake g++ libglfw3-dev libglew-dev    # Debian/Ubuntu
cmake -S . -B build && cmake --build build -j
./build/refall

-DREFALL_DISABLED_UNIVERSES="" also builds the universes left out by default (see docs/universes.md).

License

Refall is free for any noncommercial use (personal, education, research, non-profit) under the PolyForm Noncommercial License 1.0.0. For commercial use, contact the author. Fonts and bundled libraries keep their own licenses (see LICENSE). Contributions are welcome: see CONTRIBUTING.md.

Metadata

Release files for refall 1.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for refall 1.0.2
File Size Uploaded Provenance Actions
refall-1.0.2.tar.gz 16.0 MB With provenance Details for refall-1.0.2.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for refall 1.0.2
File Actions
refall-1.0.2-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for refall-1.0.2-py3-none-win_amd64.whl
refall-1.0.2-py3-none-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl Python 3 none Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 Details for refall-1.0.2-py3-none-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
refall-1.0.2-py3-none-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl Python 3 none Linux glibc 2.28+ ARM64, Linux glibc 2.27+ ARM64 Details for refall-1.0.2-py3-none-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
refall-1.0.2-py3-none-macosx_11_0_x86_64.whl Python 3 none macOS 11.0+ x86-64 Details for refall-1.0.2-py3-none-macosx_11_0_x86_64.whl
refall-1.0.2-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for refall-1.0.2-py3-none-macosx_11_0_arm64.whl

Total release size: 143.9 MB

Release files / refall-1.0.2.tar.gz

Download URL refall-1.0.2.tar.gz
Size 16.0 MB
Tags Source
SHA-256 checksum
How to use checksums
6914273655b9c88e84f8992b149d3af35a6bf6137259b8995a6a5ef097c1d3d1
BLAKE2b-256 checksum
How to use checksums
95963ad483d572d06a454e7e28804b80cbb46123f1b1ed2d270d71b21dc7f722
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / refall-1.0.2-py3-none-win_amd64.whl

Download URL refall-1.0.2-py3-none-win_amd64.whl
Size 24.0 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
744058474b686a486997580a9268f2d90d5197841ff2808cb73c218e01e7f3dd
BLAKE2b-256 checksum
How to use checksums
c13a865cc206d2a80478cb27828a728e06c4461a16498b7987eff94e2cedf8d7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / refall-1.0.2-py3-none-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL refall-1.0.2-py3-none-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 27.6 MB
Tags Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 Python 3
SHA-256 checksum
How to use checksums
8d21d3922d87202b7c2e28edc0116cf0a24b9a708f633c8b2989b45aa8a5e4f6
BLAKE2b-256 checksum
How to use checksums
2628c41f832410af78fff260374189a8932f32984499c1c8714f9ff85b7ed7d8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / refall-1.0.2-py3-none-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl

Download URL refall-1.0.2-py3-none-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
Size 26.4 MB
Tags Linux glibc 2.27+ ARM64 Linux glibc 2.28+ ARM64 Python 3
SHA-256 checksum
How to use checksums
03cf1def574b8e22d9b483f7ba307515b162deb64d33fb996fb3689b0e7e09f8
BLAKE2b-256 checksum
How to use checksums
5312e4b2c7d65b40ead0a3986465d3008148d898b4cc180dde61e0db83f6c83f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / refall-1.0.2-py3-none-macosx_11_0_x86_64.whl

Download URL refall-1.0.2-py3-none-macosx_11_0_x86_64.whl
Size 25.5 MB
Tags Python 3 macOS 11.0+ x86-64
SHA-256 checksum
How to use checksums
e67a863727dcf9718f28cacea2a24f20d9308fdf732e8965a62647d8fde67672
BLAKE2b-256 checksum
How to use checksums
a08f279d86ad111f746f44c81ac72a8e701f1cf4f1cd13cd432813ff6b78842d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / refall-1.0.2-py3-none-macosx_11_0_arm64.whl

Download URL refall-1.0.2-py3-none-macosx_11_0_arm64.whl
Size 24.5 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
0c7271c9b7c4d04237789bd508b647f79163b18629db777c093f3420353dcebe
BLAKE2b-256 checksum
How to use checksums
3fdb591a0bf9db7f8a19deb87fc1c1b6bb880049a9cf44c343e04bee9287df02
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for refall 1.0.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 6 files in this release have been uploaded with provenance metadata.

Select from 6 files

Attestation for refall-1.0.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page