Tirsvad-Udemy-100-days-of-code/023-turtle-crossing
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

MIL-007 README and wiki #34

Merged
Tirsvad merged 1 commits from mil-007-readme-wiki into main 2026-10-13 08:18:38 +02:00
Conversation 0 Commits 1 Files Changed 14
+565 -117
14 changed files with 565 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+125 -117
View File
@@ -1,117 +1,125 @@
# Turtle Crossing # Turtle Crossing
A Turtle Crossing game, the Day 23 capstone of Udemy's *100 Days of Code: The A Turtle Crossing game, the Day 23 capstone of Udemy's *100 Days of Code: The
Complete Python Pro Bootcamp*. Steer the turtle north across a busy road of Complete Python Pro Bootcamp*. Steer the turtle north across a busy road of
randomly generated cars. Each crossing raises the level and the car speed; one randomly generated cars. Each crossing raises the level and the car speed; one
collision ends the game. Written with the Python standard library only. collision ends the game. Written with the Python standard library only.
## Requirements ## Requirements
- Python 3.13 or newer, with `tkinter` (the `turtle` module needs it). - Python 3.13 or newer, with `tkinter` (the `turtle` module needs it).
- `git` to clone the repository. - `git` to clone the repository.
- `pytest` for the tests (development only; the game has no runtime dependencies). - `pytest` for the tests (development only; the game has no runtime dependencies).
- Optional: [Doxygen](https://www.doxygen.nl/) to build the source documentation. - Optional: [Doxygen](https://www.doxygen.nl/) to build the source documentation.
## Set up ## Set up
Clone the repository and create a local virtual environment named `.venv` in Clone the repository and create a local virtual environment named `.venv` in
the project folder. Upgrade `pip` first, then install the development the project folder. Upgrade `pip` first, then install the development
dependencies from `pyproject.toml`. dependencies from `pyproject.toml`.
### Windows powershell ### Windows powershell
```powershell ```powershell
git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing.git git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing.git
cd 023-turtle-crossing cd 023-turtle-crossing
py -3.13 -m venv .venv py -3.13 -m venv .venv
.\.venv\Scripts\Activate.ps1 .\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip python -m pip install --upgrade pip
python -m pip install --group dev python -m pip install --group dev
``` ```
If PowerShell refuses to run the activation script, allow it for this session If PowerShell refuses to run the activation script, allow it for this session
with `Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned`. with `Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned`.
### Linux debian ### Linux debian
```bash ```bash
sudo apt update && sudo apt install -y git python3.13 python3.13-venv python3-tk sudo apt update && sudo apt install -y git python3.13 python3.13-venv python3-tk
git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing.git git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing.git
cd 023-turtle-crossing cd 023-turtle-crossing
python3.13 -m venv .venv python3.13 -m venv .venv
source .venv/bin/activate source .venv/bin/activate
python -m pip install --upgrade pip python -m pip install --upgrade pip
python -m pip install --group dev python -m pip install --group dev
``` ```
If `python3.13` is not in your distribution, install Python 3.13 with your If `python3.13` is not in your distribution, install Python 3.13 with your
preferred tool (for example `pyenv`) and run the same `venv` command with it. preferred tool (for example `pyenv`) and run the same `venv` command with it.
### MacOS ### MacOS
```bash ```bash
brew install python@3.13 python-tk@3.13 git brew install python@3.13 python-tk@3.13 git
git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing.git git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing.git
cd 023-turtle-crossing cd 023-turtle-crossing
python3.13 -m venv .venv python3.13 -m venv .venv
source .venv/bin/activate source .venv/bin/activate
python -m pip install --upgrade pip python -m pip install --upgrade pip
python -m pip install --group dev python -m pip install --group dev
``` ```
## Run ## Run
Activate the `.venv`, then start the game from the project root: Activate the `.venv`, then start the game from the project root:
```bash ```bash
python src/main.py python src/main.py
``` ```
Press the **Up** arrow key to move the turtle forward. Reaching the top edge Press the **Up** arrow key to move the turtle forward. Reaching the top edge
returns the turtle to the start and speeds up the cars. A collision shows returns the turtle to the start and speeds up the cars. A collision shows
`GAME OVER`; click the window to close it. `GAME OVER`; click the window to close it.
## Run the tests ## Run the tests
With the `.venv` active: With the `.venv` active:
```bash ```bash
python -m pytest python -m pytest
``` ```
Tests that need a window are skipped automatically when no display is Tests that need a window are skipped automatically when no display is
available. On a headless Linux machine run `xvfb-run python -m pytest`. available. On a headless Linux machine run `xvfb-run python -m pytest`.
## Continuous integration ## Continuous integration
`.gitea/workflows/ci.yml` runs on every push to `main` and on every pull `.gitea/workflows/ci.yml` runs on every push to `main` and on every pull
request. It sets up Python 3.13, upgrades `pip`, installs the development request. It sets up Python 3.13, upgrades `pip`, installs the development
dependencies and runs `pytest` under a virtual display. dependencies and runs `pytest` under a virtual display.
## Build the source documentation ## Build the source documentation
The source uses Doxygen comments and the `Doxyfile` in the project root. The source uses Doxygen comments and the `Doxyfile` in the project root.
```bash ```bash
doxygen Doxyfile doxygen Doxyfile
``` ```
Open `docs/api/html/index.html` in a browser. Open `docs/api/html/index.html` in a browser.
## Project layout ## Project layout
```text ```text
. .
├── src/ game source: main.py, constants.py, player.py, car_manager.py, scoreboard.py ├── src/ game source
├── tests/ pytest tests │ ├── main.py screen, objects and the game loop
├── docs/ planning and review documents (business case, plan, milestones, reviews) │ ├── constants.py every constant
├── Doxyfile Doxygen configuration │ ├── player.py Player
├── pyproject.toml project configuration and development dependencies │ ├── car_manager.py CarManager
└── .gitea/ continuous integration workflow │ ├── car_shape.py how a car is drawn
``` │ ├── collision.py collision test
│ └── scoreboard.py Scoreboard
All constants live in `src/constants.py`. ├── tests/ pytest tests
├── docs/ planning and review documents (business case, plan, milestones, reviews)
## License ├── wiki/ wiki pages in English, Danish (-da) and Bahasa Malaysia (-ms)
├── Doxyfile Doxygen configuration
GNU Affero General Public License v3.0, see [LICENSE](LICENSE). ├── pyproject.toml project configuration and development dependencies
└── .gitea/ continuous integration workflow
```
All constants live in `src/constants.py`.
## License
GNU Affero General Public License v3.0, see [LICENSE](LICENSE).
wiki/Architecture-da.md
+33
View File
@@ -0,0 +1,33 @@
# Arkitektur
🌐 [English](Architecture) · **Dansk** · [Bahasa Malaysia](Architecture-ms)
## Moduler (`src/`)
| Modul | Ansvar |
| --- | --- |
| `main.py` | Opretter skærmen og objekterne og kører spilløkken |
| `constants.py` | Alle konstanter, defineret ét sted |
| `player.py` | `Player(Turtle)`: `go_up`, `is_at_finish_line`, `go_to_start` |
| `car_manager.py` | `CarManager`: `create_cars`, `move_cars`, `is_hit`, `level_up` |
| `car_shape.py` | Tegningen af en bil: karrosseri, kabine, ruder, forlygte, to hjul |
| `collision.py` | `is_colliding`: ren rektangeltest, uden turtle |
| `scoreboard.py` | `Scoreboard(Turtle)`: niveautekst og `GAME OVER` |
## Designvalg
- **Biler ligner biler.** En bil er en sammensat turtle-form inden for opgavens
fodaftryk på 40 x 20 pixel. Der registreres én form pr. farve, så der ikke
skal bruges billedfiler.
- **Kan testes uden vindue.** Geometrien (`car_components`), kollisionstesten og
reglen for oprettelse er almindelig kode. `CarManager` får en bilfabrik og en
tilfældighedskilde, så testene bruger en falsk bil og en fastlagt terning.
- **Kollision bruger hele bilen.** Spilleren sammenlignes med bilens rektangel,
ikke kun dens midte.
## Dokumentation
Kommentarerne i kilden er Doxygen-kommentarer. Byg dem med `doxygen Doxyfile`.
Plan- og reviewdokumenter ligger i `docs/`.
Tilbage til [Forside](Home-da).
wiki/Architecture-ms.md
+33
View File
@@ -0,0 +1,33 @@
# Seni bina
🌐 [English](Architecture) · [Dansk](Architecture-da) · **Bahasa Malaysia**
## Modul (`src/`)
| Modul | Tanggungjawab |
| --- | --- |
| `main.py` | Mencipta skrin dan objek serta menjalankan gelung permainan |
| `constants.py` | Semua pemalar, ditakrifkan sekali sahaja |
| `player.py` | `Player(Turtle)`: `go_up`, `is_at_finish_line`, `go_to_start` |
| `car_manager.py` | `CarManager`: `create_cars`, `move_cars`, `is_hit`, `level_up` |
| `car_shape.py` | Lukisan sebuah kereta: badan, kabin, tingkap, lampu depan, dua roda |
| `collision.py` | `is_colliding`: ujian segi empat tepat tulen, tanpa turtle |
| `scoreboard.py` | `Scoreboard(Turtle)`: teks tahap dan `GAME OVER` |
## Pilihan reka bentuk
- **Kereta kelihatan seperti kereta.** Sebuah kereta ialah bentuk turtle
gabungan dalam tapak 40 x 20 piksel yang ditetapkan tugasan. Satu bentuk
didaftarkan bagi setiap warna, jadi tiada fail imej diperlukan.
- **Boleh diuji tanpa tetingkap.** Geometri (`car_components`), ujian perlanggaran
dan peraturan penciptaan ialah kod biasa. `CarManager` menerima kilang kereta
dan sumber rawak, jadi ujian menggunakan kereta palsu dan dadu yang ditetapkan.
- **Perlanggaran menggunakan seluruh kereta.** Pemain dibandingkan dengan segi
empat tepat kereta, bukan hanya bahagian tengahnya.
## Dokumentasi
Komen dalam sumber ialah komen Doxygen. Bina dengan `doxygen Doxyfile`.
Dokumen perancangan dan semakan terdapat dalam `docs/`.
Kembali ke [Laman utama](Home-ms).
wiki/Architecture.md
+33
View File
@@ -0,0 +1,33 @@
# Architecture
🌐 **English** · [Dansk](Architecture-da) · [Bahasa Malaysia](Architecture-ms)
## Modules (`src/`)
| Module | Responsibility |
| --- | --- |
| `main.py` | Creates the screen, the objects and runs the game loop |
| `constants.py` | Every constant, defined once |
| `player.py` | `Player(Turtle)`: `go_up`, `is_at_finish_line`, `go_to_start` |
| `car_manager.py` | `CarManager`: `create_cars`, `move_cars`, `is_hit`, `level_up` |
| `car_shape.py` | The drawing of a car: body, cabin, windows, headlight, two wheels |
| `collision.py` | `is_colliding`: pure rectangle test, no turtle needed |
| `scoreboard.py` | `Scoreboard(Turtle)`: level text and `GAME OVER` |
## Design choices
- **Cars look like cars.** A car is a compound turtle shape inside the 40 x 20
pixel footprint of the assignment. One shape is registered per colour, so no
image files are needed.
- **Testable without a window.** Geometry (`car_components`), the collision
test and the spawn rule are plain code. `CarManager` receives a car factory
and a random source, so tests use a fake car and a seeded dice.
- **Collision uses the whole car.** The player is compared with the car's
rectangle, not only with its centre.
## Documentation
Source comments are Doxygen comments. Build them with `doxygen Doxyfile`.
Planning and review documents are in `docs/`.
Back to [Home](Home).
wiki/Home-da.md
+28
View File
@@ -0,0 +1,28 @@
# Turtle Crossing
🌐 [English](Home) · **Dansk** · [Bahasa Malaysia](Home-ms)
Dag 23 i Udemys *100 Days of Code: The Complete Python Pro Bootcamp*: et spil i
Crossy Road-stil. Styr en skildpadde mod nord over en travl vej. Hver
krydsning gør bilerne hurtigere; ét sammenstød afslutter spillet.
| Side | Læs den, når du vil |
| --- | --- |
| [Installation](Install-da) | Klone repositoryet, oprette `.venv` og køre spillet og testene |
| [Spil](Play-da) | Lære reglerne og styringen |
| [Arkitektur](Architecture-da) | Se hvordan koden er delt i moduler, og hvorfor |
## Overblik
- Python 3.13 eller nyere, kun standardbiblioteket ved kørsel.
- Klasserne bruger opgavens navne: `Player`, `CarManager`, `Scoreboard`.
- Alle konstanter ligger i `src/constants.py`.
- Testene køres med `pytest`; kildedokumentationen bygges med Doxygen.
## Links
- [Repository][repo]
- [README][readme]
[repo]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing
[readme]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing/src/branch/main/README.md
wiki/Home-ms.md
+29
View File
@@ -0,0 +1,29 @@
# Turtle Crossing
🌐 [English](Home) · [Dansk](Home-da) · **Bahasa Malaysia**
Hari ke-23 dalam *100 Days of Code: The Complete Python Pro Bootcamp* Udemy:
permainan gaya Crossy Road. Pandu seekor penyu ke utara merentasi jalan yang
sibuk. Setiap kali berjaya melintas, kereta menjadi lebih laju; satu perlanggaran
menamatkan permainan.
| Halaman | Baca apabila anda mahu |
| --- | --- |
| [Pemasangan](Install-ms) | Klon repositori, cipta `.venv` dan jalankan permainan serta ujian |
| [Main](Play-ms) | Mempelajari peraturan dan kawalan |
| [Seni bina](Architecture-ms) | Melihat bagaimana kod dibahagikan kepada modul dan sebabnya |
## Ringkasan
- Python 3.13 atau lebih baharu, hanya pustaka standard semasa dijalankan.
- Kelas menggunakan nama tugasan: `Player`, `CarManager`, `Scoreboard`.
- Semua pemalar berada dalam `src/constants.py`.
- Ujian dijalankan dengan `pytest`; dokumentasi sumber dibina dengan Doxygen.
## Pautan
- [Repositori][repo]
- [README][readme]
[repo]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing
[readme]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing/src/branch/main/README.md
wiki/Home.md
+28
View File
@@ -0,0 +1,28 @@
# Turtle Crossing
🌐 **English** · [Dansk](Home-da) · [Bahasa Malaysia](Home-ms)
Day 23 of Udemy's *100 Days of Code: The Complete Python Pro Bootcamp*: a
Crossy Road style game. Steer a turtle north across a busy road. Every
crossing makes the cars faster; one collision ends the game.
| Page | Read it when you want to |
| --- | --- |
| [Install](Install) | Clone the repository, create the `.venv` and run the game and the tests |
| [Play](Play) | Learn the rules and the controls |
| [Architecture](Architecture) | See how the code is split into modules and why |
## At a glance
- Python 3.13 or newer, standard library only at runtime.
- Classes use the assignment's names: `Player`, `CarManager`, `Scoreboard`.
- All constants live in `src/constants.py`.
- Tests run with `pytest`; source documentation is built with Doxygen.
## Links
- [Repository][repo]
- [README][readme]
[repo]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing
[readme]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing/src/branch/main/README.md
wiki/Install-da.md
+53
View File
@@ -0,0 +1,53 @@
# Installation
🌐 [English](Install) · **Dansk** · [Bahasa Malaysia](Install-ms)
## Krav
- Python 3.13 eller nyere med `tkinter`.
- `git`.
- Valgfrit: Doxygen til kildedokumentationen.
## Windows PowerShell
```powershell
git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing.git
cd 023-turtle-crossing
py -3.13 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install --group dev
```
## Linux Debian
```bash
sudo apt update && sudo apt install -y git python3.13 python3.13-venv python3-tk
git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing.git
cd 023-turtle-crossing
python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --group dev
```
## macOS
```bash
brew install python@3.13 python-tk@3.13 git
git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing.git
cd 023-turtle-crossing
python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --group dev
```
## Kør og test
```bash
python src/main.py
python -m pytest
```
Næste: [Spil](Play-da).
wiki/Install-ms.md
+53
View File
@@ -0,0 +1,53 @@
# Pemasangan
🌐 [English](Install) · [Dansk](Install-da) · **Bahasa Malaysia**
## Keperluan
- Python 3.13 atau lebih baharu dengan `tkinter`.
- `git`.
- Pilihan: Doxygen untuk dokumentasi sumber.
## Windows PowerShell
```powershell
git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing.git
cd 023-turtle-crossing
py -3.13 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install --group dev
```
## Linux Debian
```bash
sudo apt update && sudo apt install -y git python3.13 python3.13-venv python3-tk
git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing.git
cd 023-turtle-crossing
python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --group dev
```
## macOS
```bash
brew install python@3.13 python-tk@3.13 git
git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing.git
cd 023-turtle-crossing
python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --group dev
```
## Jalankan dan uji
```bash
python src/main.py
python -m pytest
```
Seterusnya: [Main](Play-ms).
wiki/Install.md
+53
View File
@@ -0,0 +1,53 @@
# Install
🌐 **English** · [Dansk](Install-da) · [Bahasa Malaysia](Install-ms)
## Requirements
- Python 3.13 or newer with `tkinter`.
- `git`.
- Optional: Doxygen for the source documentation.
## Windows PowerShell
```powershell
git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing.git
cd 023-turtle-crossing
py -3.13 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install --group dev
```
## Linux Debian
```bash
sudo apt update && sudo apt install -y git python3.13 python3.13-venv python3-tk
git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing.git
cd 023-turtle-crossing
python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --group dev
```
## macOS
```bash
brew install python@3.13 python-tk@3.13 git
git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/023-turtle-crossing.git
cd 023-turtle-crossing
python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --group dev
```
## Run and test
```bash
python src/main.py
python -m pytest
```
Next: [Play](Play).
wiki/Play-da.md
+26
View File
@@ -0,0 +1,26 @@
# Spil
🌐 [English](Play) · **Dansk** · [Bahasa Malaysia](Play-ms)
## Styring
| Tast | Handling |
| --- | --- |
| Pil op | Flyt skildpadden ét skridt mod nord. Skildpadden kan ikke gå tilbage, til venstre eller til højre. |
## Regler
1. Biler dukker op i højre kant i tilfældige baner og kører mod venstre. De
øverste og nederste 50 pixel er en sikker zone uden biler.
2. Nå den øverste kant for at komme over. Skildpadden vender tilbage til
start, niveauet stiger med én, og bilerne bliver hurtigere.
3. Berører du en bil, er spillet slut. `GAME OVER` vises i midten; klik på
vinduet for at lukke det.
## Tips
- Vent på et hul: en ny bil oprettes cirka hver sjette billedramme.
- Hvert niveau lægger det samme hastighedstrin til, så senere niveauer kræver
hurtige, korte træk.
Tilbage til [Forside](Home-da).
wiki/Play-ms.md
+26
View File
@@ -0,0 +1,26 @@
# Main
🌐 [English](Play) · [Dansk](Play-da) · **Bahasa Malaysia**
## Kawalan
| Kekunci | Tindakan |
| --- | --- |
| Anak panah atas | Gerakkan penyu satu langkah ke utara. Penyu tidak boleh bergerak ke belakang, kiri atau kanan. |
## Peraturan
1. Kereta muncul di tepi kanan dalam lorong rawak dan bergerak ke kiri. 50
piksel teratas dan terbawah ialah zon selamat tanpa kereta.
2. Sampai ke tepi atas untuk melintas. Penyu kembali ke permulaan, tahap naik
satu dan kereta menjadi lebih laju.
3. Jika menyentuh kereta, permainan tamat. `GAME OVER` dipaparkan di tengah;
klik tetingkap untuk menutupnya.
## Petua
- Tunggu ruang kosong: kereta baharu dicipta kira-kira sekali dalam enam bingkai.
- Setiap tahap menambah langkah kelajuan yang sama, jadi tahap lebih tinggi
memerlukan gerakan pantas dan pendek.
Kembali ke [Laman utama](Home-ms).
wiki/Play.md
+25
View File
@@ -0,0 +1,25 @@
# Play
🌐 **English** · [Dansk](Play-da) · [Bahasa Malaysia](Play-ms)
## Controls
| Key | Action |
| --- | --- |
| Up arrow | Move the turtle one step north. The turtle cannot move back, left or right. |
## Rules
1. Cars appear on the right edge in random lanes and drive left. The top and
bottom 50 pixels are a safe zone with no cars.
2. Reach the top edge to cross. The turtle returns to the start, the level goes
up by one and the cars become faster.
3. Touching a car ends the game. `GAME OVER` is shown in the centre; click the
window to close it.
## Tips
- Wait for a gap: a new car is created on about one frame in six.
- Every level adds the same speed step, so later levels need quick, short moves.
Back to [Home](Home).
wiki/_Sidebar.md
+20
View File
@@ -0,0 +1,20 @@
**Turtle Crossing**
- [Home](Home)
- [Install](Install)
- [Play](Play)
- [Architecture](Architecture)
**Dansk**
- [Forside](Home-da)
- [Installation](Install-da)
- [Spil](Play-da)
- [Arkitektur](Architecture-da)
**Bahasa Malaysia**
- [Laman utama](Home-ms)
- [Pemasangan](Install-ms)
- [Main](Play-ms)
- [Seni bina](Architecture-ms)