Fog Letters

《雾灯邮差》是一个用于 Python 基础综合课设的轻量化横版箱庭探索游戏。

玩家扮演一名小镇邮差，在雾雨笼罩的横版小镇中送信、收集物品、触发 NPC 事件，并最终修复灯塔。

Project Goals

• Use Python basics in a complete project.
• Build a small playable Pygame prototype.
• Use MySQL for users, saves, inventory, events, logs, and CRUD demos.
• Keep the scope small enough for a 5-person course project.

Tech Stack

• Python 3.10+
• Pygame
• pymysql
• python-dotenv
• MySQL

Quick Start

Install dependencies:

pip install -r requirements.txt

Run a smoke test:

python main.py --smoke-test

Check the local database connection:

python main.py --db-check

Run the menu:

python main.py

The console menu supports:

• player registration and login
• automatic creation and loading of one current save
• save summary display and logout
• administrator-only item listing and save search
• launching the Pygame prototype after login

The initial local administrator is admin with password admin. This account is for course-project setup and should not be reused outside the local development database.

MySQL Setup

1. Copy .env.example to .env and fill in the local MySQL password.
2. Import db/schema.sql with MySQL Workbench or the mysql client.
3. Run python -m db.seed_items to import the six default catalog items.
4. Run python main.py --db-check.

Local configuration:

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=replace_with_your_local_password
MYSQL_DATABASE=fog_letters

.env is ignored by Git. Never commit a real database password. The project can start without MySQL, but login, saves, and admin CRUD need a working database.

See docs/database_setup.md for initialization, verification, and troubleshooting steps.

Project Documents

• docs/requirements_design.md: functional, data, quality, and acceptance requirements.
• docs/interface_contracts.md: shared interface names, compatibility boundaries, reserved responsibilities, and implementation freedom.
• docs/team_project_guide.md: complete concept, granular task pool, collaboration rules, assets, and milestones.

Current Version

The engineering skeleton and database-backed user flow are complete:

• CLI main menu
• Config module
• Core model classes
• MySQL helper
• Registration, login, session, permission checks, and password hashing
• Automatic first-save creation and existing-save loading
• One current save per user, enforced by MySQL
• A GameContext bridge from login state to Pygame and back to the save service
• File and MySQL operation logs
• Administrator item listing and save search
• Minimal Pygame prototype
• Unit and MySQL integration tests

For an existing development database, apply new numbered SQL files from db/migrations/ before running the latest code.

Run the unit tests:

python -m unittest discover -v

Recommended Next Step

Build the first complete gameplay chain:

login -> enter town square -> talk to NPC -> pick up item -> finish event -> save progress