Tac²
A two-player, two-level tic-tac-toe strategy game featuring forced-board moves and a chess clock.
Project Overview
Tac² is a two-player strategy game that expands classic tic-tac-toe into two levels: a large 3×3 grid containing nine smaller tic-tac-toe boards.
The objective is to win three small boards in a row, column, or diagonal on the larger board. Each move determines which small board the opponent must play in next. If the designated board has already been won or is full, the opponent can choose another available board.
The game features a chess clock, with a configurable time limit (e.g., five minutes per player). A player who runs out of time loses the game.
Beyond the core game mechanics, Tac² aims to provide user accounts, an interactive tutorial, multiple game modes, a global leaderboard, and personal statistics.
How to Play
- Play a move. Place your mark in an available cell of the current small board.
- Determine the opponent's next board. The position of your move determines which small board the opponent must play in next. For example, playing in the top-right cell sends the opponent to the top-right small board.
- Win a small board. Complete a horizontal, vertical, or diagonal line of three marks within a small board.
- Win the game. Win three small boards in a row, column, or diagonal on the larger grid.
- Manage your time. Each player has five minutes. Running out of time results in a loss.
If the designated next board has already been won or is full, the opponent may choose another eligible board.
Key Features
The planned features of Tac² include:
- User Authentication and Profiles: User registration, login, and personal profile management.
- Interactive Tutorial (Level 0): A step-by-step introduction to the game rules and mechanics for new players.
- Multiple Game Modes:
- Local Multiplayer: Two players compete on the same device.
- Player vs. Computer: Single-player matches against AI opponents with multiple difficulty levels, such as easy, medium, and hard.
- Online Multiplayer: Players create or join online rooms using a room key.
- Global Leaderboard: A public ranking of players based on their performance and scores against the computer.
- User Statistics: A personal dashboard showing win rates, performance across difficulty levels, and match history.
- Timed Gameplay: A chess clock that limits the time available to each player.
Team
Tac² is developed by:
- Begoyim Kosimova
- Sofia Scardovi
- Martina Samorè
University of Bologna — Digital Transformation Management, A.Y. 2025/2026.
Project Scope
The project focuses on implementing Tac²'s core game mechanics, board-selection rules, win conditions, and timed gameplay.
The final implementation scope and acceptance criteria are defined by the project requirements and documented in the accompanying Software Engineering report.
Proposed Technology Stack
The following technologies are proposed for development. The final implementation may evolve as the project progresses.
- Python: Backend programming language and game logic.
- FastAPI: Backend API framework, including WebSockets for online multiplayer rooms.
- PostgreSQL: Relational database for user accounts, profiles, match records, and statistics.
- FastAPI Users: Authentication and user-management functionality.
- Vue.js: Frontend framework for the interactive user interface.
- JavaScript: Frontend interactions and client-side functionality.
- Poetry: Python dependency and build management.
- pytest: Python testing framework.
- Vitest and Vue Test Utils: Frontend unit testing.
- Playwright: End-to-end browser testing.
- Ruff and Mypy: Python code quality and static analysis.
- Docker and Docker Compose: Application containerisation and local development environment.
- GitHub Actions: Continuous integration and continuous delivery (CI/CD), including automated checks and builds.
Project Structure
The repository separates the Python application from the Vue frontend.
artifact/
├── docs
├── migrations/ # Alembic: creation and changes of the database tables
├── tac_two/
│ ├── __init__.py
│ ├── __main__.py
│ ├── domain/ # core concepts and repository interfaces
│ ├── adapters/ # PostgreSQL models, settings, repository implementations
│ ├── api/ # FastAPI app, routes, schemas, authentication
│ └── frontend/
│ ├── src/
│ │ ├── components/
│ │ ├── views/
│ │ ├── router/
│ │ ├── stores/
│ │ ├── App.vue
│ │ └── main.js
│ ├── e2e/
│ ├── package.json
│ └── vite.config.js
├── tests/
├── pyproject.toml
├── docker-compose.yml
├── alembic.ini
├── .env.example
├── README.md
└── LICENSE
This illustrates the principal project files; additional configuration and source files may be present.
Development Setup
Prerequisites
- Python version supported by
pyproject.toml. - Poetry.
- Node.js compatible with the frontend's
package.jsonrequirements. - npm.
- Docker and Docker Compose (for the PostgreSQL database).
Python Environment
Install the Python dependencies from the repository root:
poetry install
Run the Python test suite:
poetry run poe test
Run the configured static checks:
poetry run poe static-checks
Run Python coverage:
poetry run poe coverage
poetry run poe coverage-report
Generate an HTML coverage report:
poetry run poe coverage-html
Backend (API and database)
- Create your local settings file from the example (the
.envfile is never committed):
# Windows PowerShell
Copy-Item .env.example .env
# macOS / Linux
cp .env.example .env
- Open
.envand set your own values: replacechange_mewith your password in bothPOSTGRES_PASSWORDandDATABASE_URL(they must match), and put a random value inSECRET_KEY:
poetry run python -c "import secrets; print(secrets.token_urlsafe(32))"
- Start PostgreSQL with Docker (Docker Desktop must be running):
docker compose up -d
- Create the database tables:
poetry run alembic upgrade head
- Start the API:
poetry run uvicorn tac_two.api.app:app --reload
The API runs at http://localhost:8000 and its interactive documentation is at http://localhost:8000/docs.
Main routes (version 1):
| Method | Route | What it does |
|---|---|---|
| POST | /api/v1/auth/register |
create an account (email, password, username) |
| POST | /api/v1/auth/login |
log in (form data: username is the email, plus password) and get a token |
| POST | /api/v1/auth/logout |
log out |
| GET | /api/v1/users/me |
data of the logged user (needs the token) |
Frontend Environment
Navigate to the frontend directory:
cd tac_two/frontend
Install the JavaScript dependencies:
npm install
Start the development server:
npm run dev
Run the frontend unit tests:
npm run test:unit -- --run
Build the frontend for production:
npm run build
Run the end-to-end tests:
npm run test:e2e
Playwright may require browser binaries to be installed before the end-to-end tests can run.
Testing and Quality Assurance
Tac² includes testing infrastructure for the Python application and Vue frontend.
- Python tests: pytest.
- Frontend unit tests: Vitest and Vue Test Utils.
- End-to-end tests: Playwright.
- Code quality: Ruff and Mypy.
- Coverage: Python coverage tooling.
The testing strategy should cover the core game rules, including:
- Valid and invalid moves;
- board-selection rules;
- small-board victory conditions;
- overall game victory conditions;
- handling of completed or full boards;
- chess-clock behavior and timeout outcomes;
- relevant frontend interactions and user-visible feedback.
Coverage measurements and acceptance-test results should be documented once the corresponding tests have been implemented and executed.
Build and Code Quality
Run the configured Python static checks from the repository root:
poetry run poe static-checks
Build the frontend:
cd tac_two/frontend
npm run build
These checks help identify static-analysis issues and frontend build errors before changes are merged.
Versioning and Releases
Tac² follows Semantic Versioning:
MAJOR.MINOR.PATCH
Version numbers should be updated consistently across relevant project metadata, the changelog, Git tags, and published releases.
Release automation and the release history will be documented here once configured.
Project Documentation
The accompanying Software Engineering report should document:
- Functional and non-functional requirements;
- user stories and acceptance criteria;
- game rules and domain modelling;
- architecture and design decisions;
- implementation details;
- testing strategy and validation evidence;
- development, build, and deployment instructions;
- licensing decisions and future improvements.
Links to the project report, user guide, developer guide, and release history can be added here when those resources are available.
Third-Party Software
Tac² uses open-source software and third-party dependencies, including Python and Vue.js.
- Python: See the official Python license documentation.
- Vue.js: Vue.js is distributed under the MIT License.
- Other dependencies: Each dependency remains subject to its own license terms and applicable notices.
The licenses of third-party packages should be reviewed and documented where appropriate.
License
Tac² is distributed under the Apache License 2.0.
This permissive open-source license allows use, modification, and redistribution subject to its terms. It also includes an express patent license and requires preservation of applicable notices.
See the LICENSE file for the complete license text.
Metadata
Release files for tac_two 1.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tac_two-1.6.0.tar.gz | 107.5 kB | Without provenance | Details for tac_two-1.6.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tac_two-1.6.0-py3-none-any.whl | Python 3 | none | any | Details for tac_two-1.6.0-py3-none-any.whl |
Total release size: 241.3 kB
Release files / tac_two-1.6.0.tar.gz
| Download URL | tac_two-1.6.0.tar.gz |
|---|---|
| Size | 107.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
677d3404aa6a4ed217b57847c39c8df880283a9014026560dce8474a93d36124
|
|
BLAKE2b-256 checksum How to use checksums |
6a70c6af31f35eb192c1b93ff3e959fdbb9057da49a01a45e64540562ed019c0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.2.1 CPython/3.12.3 Linux/7.0.0-1017-azure
|
Release files / tac_two-1.6.0-py3-none-any.whl
| Download URL | tac_two-1.6.0-py3-none-any.whl |
|---|---|
| Size | 133.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dd512a4fb8f02fe8ad8e38c5f38e0e81504c08ba18d14e1c36136d4cb3b15c1a
|
|
BLAKE2b-256 checksum How to use checksums |
b27b9f5f01129f9c45c8c7988bf5fae4d3a43c8fd75d4ccaa8dc467dcff3c79b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.2.1 CPython/3.12.3 Linux/7.0.0-1017-azure
|
Security for tac_two 1.6.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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.