The main project is the Actually Useful Statistics Tetris mod. However, the repository also contains disassembly knowledge for tetris, a structure for building NES ips/nes files, and a Lua-based unit/integration test helpers.
Pre-built IPS mod files are available in the releases section of GitHub. They must be applied to the USA Tetris ROM:
Database match: Tetris (USA)
Database: No-Intro: Nintendo Entertainment System (v. 20180803-121122)
File SHA-1: 77747840541BFC62A28A5957692A98C550BD6B2B
File CRC32: 6D72C53A
ROM SHA-1: FD9079CB5E8479EB06D93C2AE5175BFCE871746A
ROM CRC32: 1394F57E
Or the Europe Tetris ROM:
Database match: Tetris (Europe)
Database: No-Intro: Nintendo Entertainment System (v. 20180803-121122)
File SHA-1: 817169B819AADAAE52CCE6B3D8D2FC24270566D7
File CRC32: 8319B091
ROM SHA-1: 66883B9EDDEC933E36B6BFF0479CEFD2434FFB40
ROM CRC32: FDFF80D5
You can use Hasher-js or ROM
Hasher to verify your ROM matches.
It is generally okay if the "ROM" checksum matches, but the "File" checksum
differs. But note that make test will fail.
TAUS provides the in-game statistics:
- DHT: The drought. The number of pieces since the last line
- BRN: The burn. The number of lines cleared since the last tetris
- EFF: The efficiency. The score per lines ignoring the level multiplier. Individual clears have score per lines of: 40 for a single, 50 for a double, 100 for a triple, 300 for a tetris
- TRT: The tetris rate. The percentage of lines cleared that were tetrises
- TRNS: The transition score. The score achieved when leaving the starting level
TAUS provides the post-game statistics:
- EFF LOG: A chart for the EFF progression through the game with each bar cooresponding to the EFF of 10 lines cleared. The EFF presented is not the cumulative EFF to that point, but the EFF of the 10 lines in isolation. It tracks each line clear separately, so if you have cleared 8 lines and then clear a tetris that is considered two lines followed by two more lines
The mod also allows skipping the legal screen.
EFF is similar in purpose to the conventional TRT. Both assume you die because you reach too high of a level (e.g., level 29) and both let you know for "how well are you doing" in the middle of the game. But EFF is a strong predictor of your final score. For example, let's say you start on level 9 and die after 100 lines. If you alternate between tetrises and sets of three singles, your final score will be ~188k. But if you alternate between tetrises and triples, your final score will be ~214k. TRT for each will be 57%, but your EFF was 188 and 214 agreeing with the 14% better score on the second game. If your EFF increases by 10%, then your score increases ~10% for the same number of lines.
The twoplayer mod allows two simultaneous players to play while receiving the same pieces. Garbage is not sent between players by default. The GameGenie code KUTPUX or the twoplayer-garbage IPS enables garbage.
There are two variations of the mod. One shows the next piece on the side, which makes it easier to see with peripheral vision. The other shows it on top, which makes it clearer at-a-glance which next piece belongs to which player.
The handicap mod provides a height-select for Type A. Instead of Type B's garbage within the height area the area is simply off-limits and unusable.
This mod was originally created as a training aid. When used with the twoplayer mod it can level the playing field.
The save-highscores mod changes the mapper of the Tetris ROM to include save-RAM and keeps the high scores in that battery-backed RAM.
The hard-drop mod, originally made by Stephen Sherratt, instantly drops the piece when pressing UP. It was changed to have twoplayer support and compatibility with other TAUS mods.
The hold mod allows saving a piece for later using SELECT. It does not fully support two players.
The 7bag mod chooses pieces so that all pieces are chosen evenly. It is a drop-in replacement for the default piece selection, using no extra memory or code space than the default; it should be highly compatible with other mods.
The playerid mod displays an identifier 1-7 at the top-right of the play screen, which can be chosen by pressing Select at the level-select screen.
The identifier is intended to help identify the game in a recording, like determining which player was playing.
You only need to build if you are making changes or want to try out changes that have not yet been included in a release.
Dependencies (should be in PATH):
- Flips. Flips 1.31 is fine
- cc65. Starting in Debian 10
(Buster) and Ubuntu 18.04 (Bionic) a package is available via
sudo apt install cc65. The Fedora package is available viasudo dnf install cc65. Arch Linux has an AUR package available. - GNU Make. Windows users can use
make.exe(just the one file) from thebin/folder ofmake-*-without-guile-w32-bin.zipavailable at ezwinports - GNU Coreutils and Sed. These are standard on Linux. On Windows they are
provided by Git for Windows when using
the "Git Bash" command line. Note that it uses a Unix directory structure;
the Windows directory structure is within the
/c/directory
On Windows, to modify your PATH, run SystemPropertiesAdvanced.exe. On the
"Advanced" tab click "Environment Variables" and then change Path in your
"User variables" and hit Okay. You will need to restart any terminals for the
changes to take effect.
Manual prep:
- Copy tetris ROM to
tetris.nesin thetausfolder. If the iNES header is different than mentioned above you can still use the ROM, but you need to adjust the header intetris.sto match your rom to make$ make testhappy
Use $ make to build artifacts into build/, which includes disassembling
into build/tetris-PRG.s. $ make test verifies the reassembled version
matches the original. The mod will be generated at build/taus.ips and will
have been applied to build/taus.nes.
tetris-PRG.info is the location for all tetris ROM knowledge. It is used to disassemble tetris into build/tetris-PRG.s. tetris.s and tetris.nes.info contain the pieces to reassemble tetris into a iNES file. Reassembly is able to output debug information.
The main debug output is the .lbl file. It is basic and just contains the labels with their addresses, so doesn't have any more information than tetris-PRG.info. However, it is easy to parse so the file format is used for several other tasks; it is transformed into build/tetris.inc using sed and can be read directly by the Lua testing tools.
NES and IPS files are output directly by the linker, because our .s files define the headers for the formats and the .cfg files specify the ordering of the headers/chunks. The linker is fairly well suited to the job and provides the ability to mix-and-match source files when generating an IPS file, only needing to manually sort the hunks. It is useful to have understanding of the IPS format and how it works. It is basically the simplest possible patch format, only supporting 1:1 replacing, so should be easy to learn.
The Nesdev Wiki has good resources for the various file formats. The .info file format is described in the da65 (disassembler) documentation. The .cfg file format is described in the ld65 (linker) documentation.
To create new IPS mods, use handicap as a template. Make a new .s file with your mod and then modify the Makefile. The .s file is assembled into a .o file and the .o files are linked into an IPS file with the help of a .cfg linker config. The normal structure generates the .cfg from magic metadata in the .o files added by ips.inc. It not too hard to create the .cfg manually, but this tends to be a bit tedious for IPS as each hunk requires two segments and hunks should be sorted.
If your mod is very invasive to Tetris, manually creating the IPS hunks can be
impractical or you may just prefer modifying the Tetris disassembly directly.
In such a case then you can manage a .diff file that is applied to the Tetris
PRG.s disassembly. The .diff is intended to be checked in and is applied to
build/diffhead-YOURFILENAME. You can change the diffhead and make will
re-generate the .diff. Similarly, changing the .diff will re-generate the
diffhead. See twoplayer for an example. If you need to modify the CHR ROM, then
that one part would need to be done as an IPS mod.
