{"id":14272288,"url":"https://github.com/Broderick-Westrope/tetrigo","last_synced_at":"2025-08-13T20:32:26.712Z","repository":{"id":206755606,"uuid":"717619659","full_name":"Broderick-Westrope/tetrigo","owner":"Broderick-Westrope","description":"Play Tetris in your terminal.","archived":false,"fork":false,"pushed_at":"2025-05-18T00:42:47.000Z","size":14713,"stargazers_count":500,"open_issues_count":6,"forks_count":18,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-08-04T12:32:26.895Z","etag":null,"topics":["bubbletea","cli","go","golang","tetris","tui"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Broderick-Westrope.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-11-12T02:44:11.000Z","updated_at":"2025-08-02T16:22:17.000Z","dependencies_parsed_at":"2024-11-24T06:12:44.993Z","dependency_job_id":"ffd0ec00-0615-4605-9373-01f9cd42ad97","html_url":"https://github.com/Broderick-Westrope/tetrigo","commit_stats":null,"previous_names":["broderick-westrope/tetrigo"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/Broderick-Westrope/tetrigo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Broderick-Westrope%2Ftetrigo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Broderick-Westrope%2Ftetrigo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Broderick-Westrope%2Ftetrigo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Broderick-Westrope%2Ftetrigo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Broderick-Westrope","download_url":"https://codeload.github.com/Broderick-Westrope/tetrigo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Broderick-Westrope%2Ftetrigo/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270305842,"owners_count":24562109,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-13T02:00:09.904Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bubbletea","cli","go","golang","tetris","tui"],"created_at":"2024-08-22T20:01:13.451Z","updated_at":"2025-08-13T20:32:26.693Z","avatar_url":"https://github.com/Broderick-Westrope.png","language":"Go","funding_links":[],"categories":["Go","Applications"],"sub_categories":["Games"],"readme":"# Tetrigo\n\n_teh·tree·go_\n\n![app demo](./docs/readme-demo.gif)\n\nA Golang implementation of Tetris, following the official [2009 Tetris Design Guideline](./docs/2009-Tetris-Design-Guideline.pdf).\n\nThis project consists of three main components, depending on what your goals are:\n\n- **_\"I just want to play Tetris\"_**\n  - The TUI (Text User Interface) in `cmd/tetrigo/` is for you. See the [installation](#installation) section.\n- **_\"I want to create my own Tetris game/UI\"_**\n  - The packages in `pkg/tetris/modes/` are for you. You can reuse these game modes with your own UI.\n- **_\"I want to create my own Tetris game mode\"_**\n  - The packages in `pkg/tetris/` are for you. You can create your own game mode with a custom set of rules and requirements.\n\nYou can find more information on these sections in the [development](#development) section. If you have a suggestion, bug, or feature request, please open a GitHub issue.\n\n## Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Configuration](#configuration)\n- [Data](#data)\n- [Development](#development)\n\n## Installation\n\nTetrigo can be installed by downloading the binary or by building from source. See the instructions below for your preferred method.\n\n### Binary\n\nYou can download the binary corresponding to your operating system from the [releases page on GitHub](https://github.com/Broderick-Westrope/tetrigo/releases).\n\nOnce downloaded you can run the binary from the command line:\n\n```bash\n# Linux or macOS\n./tetrigo\n\n# Windows\ntetrigo.exe\n```\n\nOptionally, you can move the binary to a directory in your `$PATH` to run it from anywhere ([example](https://gist.github.com/nex3/c395b2f8fd4b02068be37c961301caa7)).\n\n### Build From Source\n\nEnsure that you have a supported version of Go properly installed and setup. You can find the minimum required version of Go in the [go.mod](./go.mod) file.\n\nYou can then install the latest release globally by running:\n\n```bash\ngo install github.com/Broderick-Westrope/tetrigo/cmd/tetrigo@v0.1.6\n```\n\n### Build, run or install using Nix\n\nIf you're using [Nix](https://nixos.org), you can do any of the following:\nThe flake installs a wrapper that automatically sets up the database and config in your user’s XDG config directory on first run.\n\n```bash\nnix run github:Broderick-Westrope/tetrigo     # Run the package and delete it\nnix build github:Broderick-Westrope/tetrigo   # Build the package into a result symlink\nnix shell github:Broderick-Westrope/tetrigo   # Create a temporary shell with the tetrigo binary\n```\n\nThis flake also exposes an overlay, so you can use tetrigo as a package in your own Nix projects:\n\n```nix\n{\n  # Import the flake\n  inputs.tetrigo.url = \"github:Broderick-Westrope/tetrigo\"\n\n  outputs = { tetrigo, ... }: {\n    packages.x86_64-linux.default = let\n      # Apply the overlay\n      pkgs = import nixpkgs {\n        system = \"x86_64-linux\";\n        overlays = [ tetrigo.overlays.default ];\n      };\n    # Use the package\n    in pkgs.tetrigo;\n    # Optionally override the package using:\n    # pkgs.tetrigo.override {\n    #   config = {\n    #     max_level = 20;\n    #     keys = {\n    #       force_quit = [\"q\"];\n    #       exit = [\"esc\"];\n    #     };\n    #   };\n    #   dbPath = ./my/custom/location/tetrigo.db;\n    # };\n}\n\n```\n\n\u003e 🛠 The `tetrigo` package accepts `config` and `dbPath` as override arguments.\n\u003e\n\u003e - `config` should be a Nix attribute set mirroring values in [`example.config.toml`](./example.config.toml).\n\u003e - `dbPath` should be a path to a `.db` file.\n\u003e   These are automatically converted into a TOML config and used when the game launches.\n\n## Usage\n\nFor general information on how to play Tetris see [this beginners guide](https://tetris.com/article/33/tetris-tips-for-beginners).\n\n### Controls\n\nThe default game controls are as follows:\n\n- **Move Left**: `A`\n- **Move Right**: `D`\n- **Toggle Soft Drop On/Off**: `S`\n- **Hard Drop**: `W`\n- **Rotate Clockwise**: `E`\n- **Rotate Counter-Clockwise**: `Q`\n- **Hold Tetrimino / Submit menu option**: `Space` or `Enter`\n- **Pause Game / Exit**: `Escape`\n- **Force Quit game**: `Ctrl+C`\n- **Show Controls Help**: `?`\n\nThe game controls can be changed in the configuration file.\n\nThe menu, leaderboard, etc can be navigated using the arrow keys (moving), escape (exit), and enter (submit). These controls are not configurable.\n\n## Configuration\n\n### CLI\n\nStarting Tetrigo with no subcommand or flags will start the game in the menu where you can manually configure simple settings like the player name and game mode:\n\n```bash\n./tetrigo\n```\n\nYou're also able to start the game directly in a game mode (eg. Marathon), skipping the menu:\n\n```bash\n# Start the game in Marathon mode with a level of 5 and the player name \"Brodie\"\n./tetrigo play marathon --level=5 --name=Brodie\n```\n\nTo see more options for starting the game you can run:\n\n```bash\n./tetrigo --help\n```\n\n### TOML\n\nMore complex configuration can be done using a TOML file. If no config file is found sensible defaults will be used.\n\nBy default, Tetrigo will look for the file `./tetrigo/config.toml` within the devices XDG config (or equivalent) directory. The [adrg/xdg](https://github.com/adrg/xdg) defines values `XDG_CONFIG_HOME` for various operating systems (eg. on macOS it is `~/Library/Application Support` directory exists it will be stored there, otherwise in `~/Library/Preferences`). You can specify a different file using the `--config` flag.\n\n```bash\n./tetrigo --config=/path/to/config.toml\n```\n\nAn example configuration file is provided in [`example.config.toml`](./example.config.toml).\n\n## Data\n\nThe game data is stored in a SQLite database. By default, the database is stored in `./tetrigo/tetrigo.db` within the devices XDG data (or equivalent) directory. The [adrg/xdg](https://github.com/adrg/xdg) defines `XDG_DATA_HOME` for various operating systems (eg. on macOS if the `~/Library/Application Support` directory exists it will be stored there, otherwise in `/Library/Application Support`). You can specify a different file path using the `--db` flag.\n\n```bash\n./tetrigo --db=/path/to/data.db\n```\n\n## Development\n\nThis project consists of three main components:\n\n1. `cmd/tetrigo/`: A TUI (Text User Interface) allowing you to play it out of the box. It also serves as a demonstration on how to use the packages and how to create a TUI using [Bubble Tea](https://github.com/charmbracelet/bubbletea).\n2. `pkg/tetris/modes/`: The functionality for different Tetris game modes. This can be used to easily create a Tetris game with your own UI but without needing to know the ruleset.\n3. `pkg/tetris/`: The core Tetris logic, including things like Tetriminimos, the Matrix, and scoring. This can be used to create game modes with your own ruleset and requirements.\n\n[Task](https://taskfile.dev/) is the build tool used in this project. The Task config lives in [Taskfile.yaml](./Taskfile.yaml). Once the Task CLI is installed, you can see all available tasks by running:\n\n```bash\ntask -l\n```\n\nYou can run the TUI using the `run` task:\n\n```bash\ntask run\n```\n\n### Building\n\nYou can build the project using the `build` task:\n\n```bash\ntask build\n```\n\nThis will create a binary in the `bin/` directory which can be run using the instructions in the [Installation](#installation) section.\n\n### Testing\n\nTests can be run using the `test` task:\n\n```bash\ntask test\n```\n\nYou can also use the `cover` task to generate and open a coverage report:\n\n```bash\ntask cover\n```\n\nThe ordered priorities for testing are:\n\n1. `pkg/tetris/`\n2. `pkg/tetris/modes/`\n3. `cmd/tetrigo/`\n\n### TODO\n\n- Add more tests\n  - Add tests for scoring endOnMaxLevel.\n  - Revisit scoring tests.\n- Add the remaining Lock Down options.\n- Check for Lock Down 0.5s after landing on a surface\n  - Also on Soft Drop, but not on Hard Drop.\n  - This resets after each movement \u0026 rotation, for a total of 15 movements/rotations.\n  - See \"Extended Placement Lock Down\" in the design guidelines.\n- Score points from T-Spins\n- SSH Multiplayer (akin to [Gambit](https://github.com/maaslalani/gambit))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBroderick-Westrope%2Ftetrigo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBroderick-Westrope%2Ftetrigo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBroderick-Westrope%2Ftetrigo/lists"}