# 2025 資訊之芽 Python 語法班一階段大作業 - The Dungeon

## Deadline: 4/13

## Links

- [作業程式連結](https://drive.google.com/file/d/1a0G3_S_l0XB3hhjXurgjydxyIorOfbJC/view?usp=sharing)
- [作業繳交表單連結](https://docs.google.com/forms/d/e/1FAIpQLScS-nfyAAMxesOz_OajVWF3vviSUr7BHrHDMOrPIOKVE50nGg/viewform?usp=preview)
- [投影片連結](https://docs.google.com/presentation/d/1UPVndlXOhOxCe3AjrKp8_mb_ydPR9I8kq6gyGt80ETM/edit?usp=sharing)
- [課程網頁連結](https://tw-csie-sprout.github.io/py2025/)

---

## 事前準備

### 安裝 python3
希望大家都裝好了。
有遇到困難的話可以複習第一週的簡報，或是向講師求助。

### 安裝 [pygame](https://www.pygame.org/docs/)

#### Windows
按下 Win+R，輸入 `cmd` 開啟命令提示字元
輸入以下指令安裝 `pygame` 的遊戲套件

python -m pip install pygame --user

或是

python3 -m pip install pygame --user

#### MacOS/Linux
打開 terminal，輸入以下指令

python3 -m pip install pygame --user

### VSCode Extension: TODO Tree

為了更方便在大作業中定位各項任務需修改的地方，你可以在 VSCode 中安裝與 TODO 關鍵字相關的插件。大作業中的每個任務都有以 `# TODO` 進行標記，利用這些插件就能快速找到需要修改的地方。如果你使用的是 VSCode，我們推薦 [TODO Tree](https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.todo-tree) 插件，相信它能讓你的大作業進行得更加順利。

### 下載作業

到 <a href="#Links" smoothhashscroll>Links</a> 作業程式連結裡下載作業，檔案為壓縮檔，解壓縮後會出現一個資料夾，裡面包括專案的所有程式。

#### 執行方式

打開 `cmd` 或者是 `terminal`，輸入：

cd <放程式的資料夾>

接下來輸入：

python main.py

或是：

python3 main.py

來執行作業程式。

執行成功後，會看到的遊戲視窗如下：


---

## 作業說明
故事背景

> 小芽是一位喜歡看動漫的資工系學生，他最喜歡地下城迷宮冒險題材的動漫。最近，在看完《迷宮飯》之後，他下定決心要自己開發一款相同題材的遊戲。幸運的是，歸功於平常在資工系的訓練，小芽十分習慣熬夜通宵寫程式，也就在幾個不眠不休的夜晚後順利完成了一個簡單的原型。
>
> 當小芽心滿意足的玩著自己做的遊戲時，他的中二病突然發作了，他為遊戲中的「勇者」設計了一套「困境」的劇本，例如：突然無法移動、怪物變強無法被擊退、無法攻擊怪物等等，刪除了相對應的程式碼並十分入戲的覺得自己是「偉大的神聖魔法師」，打算陪著勇者一步一步克服這些困境（其實就是再把程式寫回來）
>
> 然而，由於小芽還只是個學生，他寫程式的習慣不太好，沒有註解也沒有開發的文件，他發現自己無法理解自己之前到底寫了什麼，也忘記刪掉的部分怎麼寫了。在這樣的絕望中，他的中二病好了，從「偉大的神聖魔法師」一職卸任並且拿著他的劇本跟遊戲程式來找你幫忙。現在，請你幫小芽拯救他的勇者，另外，因為這個遊戲只是個「原型」，小芽也希望你能幫他加一些功能，跟他一起將這個遊戲開發的更完整。

### 遊戲內容

- 每局遊戲都會生成一個隨機的迷宮
- 透過上下左右鍵操控勇者在迷宮中移動，空白鍵使用拳頭攻擊
- 迷宮中有弓箭、道具和怪物
- 撿到弓箭後勇者可以使用弓箭攻擊，提升攻擊距離
- 撿到道具可以在一段時間內提升勇者的能力，拳頭：攻擊範圍上升，弓箭：散射
- 怪物會在迷宮中移動，與勇者碰撞時會導致勇者生命值減少，怪物被武器擊中或被玩家撞到都會減少生命值，怪物的生命值只有 2 且在死亡時有機率掉落鑰匙
- 怪物和勇者在受傷時都會被擊退一小段距離
- 勇者的目標是透過擊倒怪物取得鑰匙後走到迷宮的終點，獲得寶藏

### 檔案內容

- `config.py` 中定義了許多遊戲中設定的變數，例如：勇者移動的速度。
- `main.py` 程式的進入點，執行它來開啟遊戲。
- `helper.py` 是放置一些幫手函式的地方，類似通用的工具庫，例如：load_image()
- `controller`/`game_controller.py` 是控制遊戲主要邏輯的地方
- `views`/`renderer.py` 是主要渲染遊戲畫面的地方，包括背景、圖示等
- `models`/`*.py` 包含各種物件的程式，例如 player, item, monster 等

### Tasks

以下是小芽留給你的任務列表與劇本，因為你沒有中二病，你可以照著他給你的順序完成，也可以完全不管他。由於你是接手別人（小芽）的專案，儘管小芽已經盡力在專案中留下線索，有時候你可能還是需要稍微理解任務以外的程式是如何運作的才能更順利的完成任務。在設計上，你能夠透過這些線索並只修改任務指示的地方就能完成專案，但你如果覺得小芽寫的程式不符合你的習慣，你也可以任意修改其他地方，只要能夠完成任務即可。

總分是 125, 包括 100 分基本分以及 25 分加分題，每一題的評分都包括：

- 程式完成度
- 程式穩定性
- 程式乾淨度（可讀性）
- effort (若沒完成該題)
- 創意（加分題的部分）

#### 01. 讓勇者動起來！

> 第一幕：勇者因為迷宮的神秘詛咒而動彈不得，於是他開始向偉大的神聖魔法師（你）祈禱，希望你能幫幫他，讓他能躲避怪物的攻擊

(6pts) 完成 `player.py` 中的 TODO 1

- [ ] (6pts) 讓勇者可以透過上下左右鍵操控移動

#### 02. 讓迷宮活起來！
> 第二幕：勇者的動靜驚醒並激活了迷宮，各種生物與物品開始出現，其中有兇猛的怪物，也有對勇者可能有益的素材

(12pts) 完成 `game_controller.py` 中的 TODO 2

- [ ] (12pts) 完成 spwan_random_pos() 函式，讓迷宮中可以隨機生成怪物、道具等物件

#### 03. 讓勇者學會攻擊！
> 第三幕：勇者被突然出現的怪物嚇到了，並且因為長期沒有食物，營養不良而無力反擊。另外，他在迷宮中找到了弓箭，但它壞了QQ
> 請你，偉大的神聖魔法師，重新賦予他反擊的能力並幫他把那把破弓修好

(12pts) 完成 `weapon.py` 中的 TODO 3, 4

- [ ] (6pts) 讓勇者可以在按下空白鍵時，用拳頭攻擊
- [ ] (6pts) （撿到弓箭以後）讓勇者可以用空白鍵射出箭矢（需要先完成 TODO 2 才能開始做，或是你能找到有設定有弓箭狀態的變數來進行測試）

#### 04. 顯示勇者狀態
> 第四幕：現在，勇者準備好反擊了！但他並不是有勇無謀的莽夫，在進攻之前，他想先知道自己的狀態如何，以便評估情勢。而你，偉大的神聖魔法師，正好有能力幫助他。

(32pts) 完成 `renderer.py` 中的 TODO 5

- [ ] (12pts) 讓勇者的生命值以愛心圖示數量的方式顯示
- [ ] (6pts) 顯示是否已經取得鑰匙
- [ ] (6pts) 顯示是否已經取得弓箭
- [ ] (8pts) 顯示是否有道具效果以及效果剩餘時間

#### 05. 擊退怪物！
> 第五幕：勇者在與怪物的戰鬥中發現，怪物的強度似乎比他記得的更強，他無法擊退他們。於是你，偉大的神聖魔法師，決定再次大發慈悲，幫他削弱怪物的強度。

(12pts) 完成 `game_controller.py` 中的 TODO 6（需要先完成 TODO 2）

- [ ] (6pts) 讓怪物被拳頭或箭矢打到時往合理的方向被擊退
- [ ] (6pts) 讓怪物和勇者相撞時，兩者都往合理的方向被擊退

#### 06. 迷宮進化！
> 第六幕：迷宮的生態系捉摸不定，就在勇者逐漸掌握在迷宮生存的訣竅時，似乎有新的東西出現了，這對勇者會是好消息還是壞消息呢...
> 或許只有你，偉大的神聖魔法師，能告訴我們了！

(20pts) 完成 `item.py` 和 `game_controller.py` 中的 TODO 7 （需要先完成 TODO 2）

透過觀察 `item.py` ，你會發現「道具」的概念其實就是提升或降低某個相關的屬性 (attribute) 或是變數。現在，你可以看看 `config.py` 中定義的各種變數，思考有沒有哪些變數可以拿來做成有趣的道具，例如：提升勇者的移動速度。

- [ ] (12pts) 在 TODO 0 探索 `config.py` 中的變數們，發揮創意，在 item.py 中設計自己的道具（你可以在 assets 中找到還沒有用過的圖片作為你的道具的圖案，但我們也鼓勵大家利用 [itch.io](https://itch.io/game-assets/free/tag-pixel-art) 上的免費素材）
- [ ] (8pts) 在 `game_controller.py` 中把你的道具加進迷宮中，並測試他的效果

#### 07. Extra: Make this your own game!
> 恭喜你成功完成到這，幫小芽拯救了他的勇者！因為你的傑出能力，小芽想要邀請你一起把這款遊戲開發的更豐富更好玩，你要接受挑戰嗎？

(25pts) 發揮你的創意，利用課堂上學到的知識以及 pygame document 為這個遊戲添加你自己的風格，可以是：
1. 為遊戲增加音效、音樂
2. 在 [itch.io](https://itch.io/game-assets/free/tag-pixel-art) 找到自己喜歡的素材並更改遊戲的美術風格
3. 增加更多有趣的道具（可能更複雜的效果，ex: 換武器）
4. 增加其他遊戲機制 （ex: 計時、更多種類的怪物）

任何你做的新功能，或是任何你學到的額外的內容、優化，都可能可以爭取到 Extra 的分數。請在這些內容的前方加上 `# TODO` 的註解，並簡單描述你做了什麼。

---

## 繳交作業

到 <a href="#Links">Links</a> 作業繳交表單連結中繳交作業
繳交檔案需為壓縮檔，將你整個專案資料夾底下的所有檔案放在同一個名為
`[姓名]_sprout-py-proj` 的資料夾底下，壓縮此資料夾成.zip檔後繳交。
e.g. Howard 應該會繳交 `Howard__sprout-py-proj.zip`。
表單回覆會設為可編輯，期間內不滿意/發現有bug都可以修改上傳的檔案。