Skip to main content

Tac²

Status Python Vue.js License

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

  1. Play a move. Place your mark in an available cell of the current small board.
  2. 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.
  3. Win a small board. Complete a horizontal, vertical, or diagonal line of three marks within a small board.
  4. Win the game. Win three small boards in a row, column, or diagonal on the larger grid.
  5. 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.json requirements.
  • 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)

  1. Create your local settings file from the example (the .env file is never committed):
# Windows PowerShell
Copy-Item .env.example .env
# macOS / Linux
cp .env.example .env
  1. Open .env and set your own values: replace change_me with your password in both POSTGRES_PASSWORD and DATABASE_URL (they must match), and put a random value in SECRET_KEY:
poetry run python -c "import secrets; print(secrets.token_urlsafe(32))"
  1. Start PostgreSQL with Docker (Docker Desktop must be running):
docker compose up -d
  1. Create the database tables:
poetry run alembic upgrade head
  1. 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.

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)

Source distribution for tac_two 1.6.0
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)

Table of built distributions (wheels) for tac_two 1.6.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page