An AI that plays NES Tetris at a super-human level. Can play live games in an emulator or on console, and can also be used for analyzing human gameplay or individual board positions.
At it's core, StackRabbit is based on traditional search & heuristic methods, but it achieves high-quality board evaluation through high-depth playouts. (For example, 3000 playouts at depth 10, for each of 8 promising moves.)
Unlike other games like chess, the "opponent" (the game's piece selector) doesn't make its selections adversarially (much as players may feel otherwise). That means that many optimizations like alpha-beta pruning don't apply here. Since any possible upcoming sequence is equally likely (aside from quirks of the NES RNG), we instead take a large sample of possible sequences, and test how well each position turns out when playing out those sequences.
The static eval function was created and tuned with a combination of intentional design (from my own high-level gameplay experience), statistical tuning, A/B testing, and years of experimentation. It has limitations, as any static eval does, but its main purpose is to guide the agent during playouts, not so much to give definitive ratings to positions by themselves.
The quality of evaluation you get from StackRabbit does scale up with more computation time.
In live gameplay, the agent is only guaranteed to get 160ms (10 frames) of thinking time between when the previous piece locks into the stack and the next piece spawns. My recommendation for working under this limitation:
playoutCount = 400, playoutLength = 6
These numbers work on my 2026 Macbook Air M5. You can scale it up or down depending on how strong your processor is. Just keep in mind that the higher the depth (playoutLength), more playouts are needed to reduce the variance.
If your client can afford the wait time, doing a deeper search with much more playouts provides even better analysis. My recommendation:
playoutCount = 3000, playoutLength = 10
At lower depth (depth 3 or less), Stackrabbit can do a fully exhaustive search over all possible upcoming sequences. This has more precision (zero variance from sampling), but due to the lower depth, it has less "wisdom" when evaluating long-term macro decisions.
StackRabbit supports all major input methods (DAS, hypertap, rolling) and can be configured between them, even at runtime. The input speed (often measured in Hz) of tapping and rolling can be configured as well. Note that rolling and tapping are indistinguishable from an agent's perspective, differing only in what Hz values would commonly be associated with each (<15 Hz for tapping, and >15Hz for rolling).
The code generally uses a string inputFrameTimeline to control the input speed. Each character in the string represents one frame, and a "X" means the agent can perform inputs on that frame, and "." means it's on cooldown. For example, "X....." means one input and then 5 frames in between, which comes out to 10 Hz of effective speed.
The Lua script (which handles live gameplay in FCEUX) has a parameter USE_DAS to toggle between DAS and Tap/Rolling.
When USE_DAS is true, the inputFrameTimeline variable controls how fast the agent can "quicktap":
- A value of "X.." or faster allows for 8-high-left quicktaps on 19 speed
- A value of "X...." or faster allows for 7-high-left quicktaps on 19 speed
- A value of "X....." or slower doesn't allow for any quicktaps.
The core computation code lives in src/cpp_modules and is shared by all entrypoints.
There are three main ways to run the StackRabbit backend:
src/wasmcontains instructions for compiling this repo into a WASM binary, which then can be consumed by any Javascript client.src/servercontains a Node.js server which supports many API endpoints, but is primarily only used for live gameplay (via "precompute" requests).entrypoint.cppis a local C++ file that can be run from the command line, for local testing. The test inputs can be configured at the top of the file.
There are a number of different clients for interacting with the main StackRabbit backend:
- TetrisTrainer is a public web client (try it live!) that lets users draw a board and ask AI about the best placements.
fceuxcontains a Lua client for playing in the FCEUX emulator (primary client for running live games with StackRabbit)console_clientcontains a python client that runs on Raspberry Pi to play on a real console.- Any other Javascript client can consume the WASM binary (details in
src/wasm) and call all the major endpoints.
- Node.js: Download here
- FCEUX: Download here
- Python3: Download here
- (Windows-only) Visual Studio Build Tools
-
Clone or Extract:
- Clone this repository or extract the zip file from the releases page.
-
Obtain NES Tetris ROM:
- Legally acquire the ROM for NES Tetris. You can use TetrisGYM.
-
Open Command Line:
- Press
Win + R, typecmd, and press Enter. - Navigate to the folder for Stackrabbit using
cd path/to/stackrabbit.
- Press
-
Install Dependencies:
- Run
node install.jsin the command line.
- Run
-
Start the Application:
- If the previous command runs without errors, execute
npm start.
- If the previous command runs without errors, execute
-
Setup FCEUX:
- Open the FCEUX folder.]
- Add all
.luafiles (excludingitn12.lua,mime.lua, andsocket.lua, put them inC:/path/to/fceux/lua) from the Luasocket repository toC:/path/to/fceux/lua/socket/. (if there is noluafolder, create it and the socket folder inside)
-
Load Tetris ROM:
- In FCEUX, click
File > Openand select the Tetris ROM.
- In FCEUX, click
-
Run Stackrabbit Script:
- In the FCEUX window, go to
File > Lua > New Lua Script Window. - In the new window, browse and run
path/to/stackrabbit/src/fceux/stackrabbit.lua. - Open level 19 and let it start!
- In the FCEUX window, go to
- We may have made some errors, so if you tell us those errors, We will make corrections as soon as possible, Thank You!
- Making the AI: @GregoryCannon
- Making the Tutorial on setting up: @BenP1236691
- Bug fixing the TypeScript: @NguyenQuangMinh0504
- Compiling StackRabbit into web assembly: @timotheeg
- Adding column 9 vits: @fractal161