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.
uvx refall
On Windows, you can also just download and run the standalone Refall-windows-x64.exe: one file, nothing to install.
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
Windows: download Refall-windows-x64.exe and run it: one file, nothing to install (the first YouTube song fetches yt-dlp, ffmpeg and Deno, about 100 MB, into the game's cache).
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.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| refall-1.0.1.tar.gz | 16.0 MB | With provenance | Details for refall-1.0.1.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| refall-1.0.1-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details for refall-1.0.1-py3-none-win_amd64.whl |
| refall-1.0.1-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.1-py3-none-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
| refall-1.0.1-py3-none-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl | Python 3 | none | Linux glibc 2.27+ ARM64, Linux glibc 2.28+ ARM64 | Details for refall-1.0.1-py3-none-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl |
| refall-1.0.1-py3-none-macosx_11_0_x86_64.whl | Python 3 | none | macOS 11.0+ x86-64 | Details for refall-1.0.1-py3-none-macosx_11_0_x86_64.whl |
| refall-1.0.1-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details for refall-1.0.1-py3-none-macosx_11_0_arm64.whl |
Total release size: 143.9 MB
Release files / refall-1.0.1.tar.gz
| Download URL | refall-1.0.1.tar.gz |
|---|---|
| Size | 16.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
64bf85b147a46702d4531df3750db3a55d4999b14c4ad80d2c279b52efe36af5
|
|
BLAKE2b-256 checksum How to use checksums |
c53acb8c3a5a3b33fd6f46cf9264ef9c76efb42c49ee8e3fcffeb2c3ef6f575a
|
| 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 logRelease files / refall-1.0.1-py3-none-win_amd64.whl
| Download URL | refall-1.0.1-py3-none-win_amd64.whl |
|---|---|
| Size | 24.0 MB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
7fe72382879c93139d9c01479ed0d20d247b0ab977bef4bcbc040a7391d70771
|
|
BLAKE2b-256 checksum How to use checksums |
00549424f8d075b033a1cb157d86adfbc6f00689835e1e8d7a4949f7fa47cfb5
|
| 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 logRelease files / refall-1.0.1-py3-none-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | refall-1.0.1-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 |
0a8edb8627906a5bb8369cd8e3bfe1ed9d2b560754435dfa0555480c0d5714a8
|
|
BLAKE2b-256 checksum How to use checksums |
32072f8ca9ad50b386203892a66b7b0a82bd52650afe1243d45cff206e097818
|
| 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 logRelease files / refall-1.0.1-py3-none-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
| Download URL | refall-1.0.1-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 |
61e43a4db9cb0e334fd06922a1f017545ab2dbd3d16d7990402ec3fe5d937041
|
|
BLAKE2b-256 checksum How to use checksums |
e945e1c514020fddf548f2b30359c674422753b9cb3f5824ab75af518d8ef71a
|
| 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 logRelease files / refall-1.0.1-py3-none-macosx_11_0_x86_64.whl
| Download URL | refall-1.0.1-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 |
12ced414972d50a4025168cea8ca4eab4727acb77547355ffe427f42972887bc
|
|
BLAKE2b-256 checksum How to use checksums |
a99d9ceba99d626dcafdc7553eff86fcc58dca040da8c93587251f8a48ad0a56
|
| 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 logRelease files / refall-1.0.1-py3-none-macosx_11_0_arm64.whl
| Download URL | refall-1.0.1-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 |
6205db68e11a61d3bab6a316bb5d5597e404df683e8e6c300a0b70d3afd136d5
|
|
BLAKE2b-256 checksum How to use checksums |
6b19c3365044e00f96cf3e3f611a2af451cf18656ad02a1b1d3c7202c184a90c
|
| 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 logSecurity for refall 1.0.1
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.
Attestation for refall-1.0.1.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 logA 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.