Contributing to Tetris-SQL

Thank you for your interest in Tetris-SQL! Whether you want to add new mechanics (like a "Hold" piece feature, wall kicks, or T-Spins), fix bugs, or optimize the query, contributions are highly welcome.

Setting up a Development Environment

The most effective way to develop and test modifications is to use a Docker volume mount. This allows you to edit the game.sql file on your host machine using your favorite IDE, while executing it instantly in the isolated Postgres container.

1. Start a persistent Dev Container: Map your current directory to the container. 

docker run --name pg_dev -p 5432:5432 -v $(pwd):/tetris-sql -d -e POSTGRES_PASSWORD=postgres postgres:18

2. Prepare the dependencies: 

docker exec pg_dev apt update
docker exec pg_dev apt install -y python3-psycopg2

3. Run the development loop: Now, you can edit game.sql locally. When you want to test a change, simply execute the file in the container:

docker exec pg_dev psql -U postgres -f /tetris-sql/game.sql

Debugging a Massive SQL Query

Debugging a 400-line recursive CTE can be daunting. If you break the syntax or logic, PostgreSQL will usually just throw a generic syntax error or an infinite loop.

Best Practices for Debugging:

  • Isolate CTEs: If you are modifying the collision logic or piece rotation, copy that specific LATERAL join out of the main query. Wrap it in a smaller, non-recursive query where you hardcode the main.board and main.pos variables to test your math independently.
  • Use notify() for Logging: You can inject notify('DEBUG: ' || my_variable::text) inside the SELECT projection of the recursive term to print variable states to the terminal in real-time.
  • Watch the Performance: Any new JOIN or aggregate function you add to the recursive term will execute 60 times a second. Keep logic as tight as possible. Avoid full table scans; rely on array manipulations where possible.

Areas for Improvement

Looking for a project to tackle? Here are some known areas where the game could be improved:

  1. Super Rotation System (SRS): Currently, the game uses a simplified rotation system. Implementing strict SRS wall-kicks (allowing pieces to "bump" away from walls when rotating) would make the game feel much more modern.
  2. Hold Mechanism: Adding the ability to press a key (e.g., Shift / C) to store a piece for later use. This requires expanding the state vector to track the held piece ID and a boolean flag to prevent infinite holding.
  3. Terminal Colors: Experimenting with ANSI color codes in the render string to give different tetrominoes their standard colors (Cyan for I, Yellow for O, etc.).

Submitting a Pull Request

  1. Fork the repository.
  2. Create a feature branch (git checkout -b feature/ansi-colors).
  3. Commit your changes with clear, descriptive commit messages.
  4. Push to the branch and open a Pull Request against the main branch.

License

Tetris-SQL is open-source software licensed under the MIT License. By contributing to this repository, you agree that your contributions will be licensed under the same MIT License.

(See the full LICENSE file in the repository root for details).