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.

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

PyPI

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)

Source distribution for refall 1.0.1
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)

Table of built distributions (wheels) for refall 1.0.1
File Actions
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.28+ x86-64, Linux glibc 2.27+ 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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Security 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.

Select from 6 files

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 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.

Release history Release notifications | RSS feed

This release

1.0.1 This release

6 release files Full provenance

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