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

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.0
File Size Uploaded Provenance Actions
refall-1.0.0.tar.gz 16.0 MB With provenance Details for refall-1.0.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for refall 1.0.0
File Actions
refall-1.0.0-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for refall-1.0.0-py3-none-win_amd64.whl
refall-1.0.0-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.0-py3-none-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
refall-1.0.0-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.0-py3-none-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
refall-1.0.0-py3-none-macosx_11_0_x86_64.whl Python 3 none macOS 11.0+ x86-64 Details for refall-1.0.0-py3-none-macosx_11_0_x86_64.whl
refall-1.0.0-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for refall-1.0.0-py3-none-macosx_11_0_arm64.whl

Total release size: 144.4 MB

Release files / refall-1.0.0.tar.gz

Download URL refall-1.0.0.tar.gz
Size 16.0 MB
Tags Source
SHA-256 checksum
How to use checksums
7abf8941c0e96a655e43044124f70aeb6c25d4bb58404441af964810a4851924
BLAKE2b-256 checksum
How to use checksums
0ddd53a1483f428d82e378c2b3c20260b4871945da428f10e65927602ace9fa2
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.0-py3-none-win_amd64.whl

Download URL refall-1.0.0-py3-none-win_amd64.whl
Size 24.0 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
7f410f0b8d1d387d19bfd72a2893175d69ec2c4fa2dc6836e15cf42e56d31545
BLAKE2b-256 checksum
How to use checksums
1d26f46666a8b868207a8dcc378cc3405436489ebc584d384fd32b2528b15577
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.0-py3-none-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL refall-1.0.0-py3-none-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 27.9 MB
Tags Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 Python 3
SHA-256 checksum
How to use checksums
b61d0b4d083ea5686f1f59d80011bbab447014829e167192bc81631885d44934
BLAKE2b-256 checksum
How to use checksums
caa2f989ed7de67eb262db039da09df87f43fb8a65be43a02736e6b1ff1e6520
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.0-py3-none-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl

Download URL refall-1.0.0-py3-none-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
Size 26.6 MB
Tags Linux glibc 2.27+ ARM64 Linux glibc 2.28+ ARM64 Python 3
SHA-256 checksum
How to use checksums
e275df7134d788c7c50077844202d51dbb8cc6538f44afb32c7137a29bb5f5e3
BLAKE2b-256 checksum
How to use checksums
cd23592da890321fcb01db2d180211d23864c7e290c45a10a70632541359ae9d
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.0-py3-none-macosx_11_0_x86_64.whl

Download URL refall-1.0.0-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
31ab05eb2f122d4ca644cf15bfb6687561d9270a8f783f2635a2aeb39b2238a8
BLAKE2b-256 checksum
How to use checksums
eccb8ffc5ea3f0e21071ffef6364f42225bb8a75fb9bd34bea91f62bf28c7c2d
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.0-py3-none-macosx_11_0_arm64.whl

Download URL refall-1.0.0-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
d4f48704df8df5b22024e7b1baeee9886d7b03f86c7bbe18363cca84b02f06a5
BLAKE2b-256 checksum
How to use checksums
512b0ffab69fbbc90b13ca2f48a48530accb162dad70e71409592ca616355331
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.0

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