# 2022 資芽 C/C++ 大作業二 - SPEC

> 官網: <https://tw-csie-sprout.github.io/c2022/#!project2.md>
> 北區說明影片:https://youtu.be/sQWKWPVpp0A
> 竹區說明影片:https://youtu.be/A4MZljyXCW4
> 下載連結:https://drive.google.com/drive/folders/1DvY1MNgWOdDTSFjtnFi12IpVjEwAuugw?usp=sharing

[TOC]

## 更新紀錄
5/28 (六) 16:30：更新 AI 作法（參數部分）、補充 list 的介紹

6/18（六）16:30：更新 deadline 時間（7/8）、新增問答表單：https://forms.gle/gCPs5PosLo68Sizr6 （有需求的人請在 6/25 以前填寫完畢）

7/2 (六) 12:00：繳交區：https://forms.gle/hS29RRcz56PAjD8p8

## 介紹

### Space Shooter 遊戲
來源：https://kickingbrains.wordpress.com/2016/08/03/space-shooter-a-simple-c-game-for-windows/
上面是遊戲的畫面，不過這個遊戲只有在 Windows 系統上才有辦法玩。不過沒關係！我們沒有要做這麼簡單的遊戲，我們的遊戲會基於上面的遊戲做修改，而且在 Windows、MacOS、Linux 上面都是有辦法遊玩的！

### 我們要做的遊戲

基本玩法:在一個 80 * 26 的地圖內，2個玩家分別在遊戲的最上方和最下方，目標是將對方打死。
Player1 是畫面下方的戰鬥機，玩法是按 ASDW 移動，按空白鍵發射子彈；Player2 是畫面上方的戰鬥機，玩法是按上下左右鍵移動，按 Enter 發射子彈
過程中可能會隨機生成一些隕石和道具，打掉隕石可以增加經驗值。累積一定經驗值後可以升等；碰到道具可以獲得一些好的效果。
遊戲畫面如下：

## 如何看懂程式在做什麼
### 資料夾架構
你在下載完你要用的資料夾之後，你可能會看到這些東西：（以下僅列出一部分，你可能會用到or好奇的東西）
- bin：你的遊戲在編譯後，會被放到bin資料夾裡面
- image：裡面有各種遊戲物件的圖檔，你可能會需要新增or減少or修改裡面的東西。
- src：主要的程式碼都在裡面，你在作業中需要改的東西也幾乎都在這裡面。以下是 src 裡面的內容：
- main.cpp：遊戲的主程式
- engine：內含遊戲引擎相關的程式碼，包括遊戲的開始畫面、進行畫面、結束畫面等
- object：內含遊戲物件相關的程式碼，你可以在裡面看到玩家、子彈、隕石、道具等物件的各種屬性
- AI：AI相關。後面會介紹到
- utils：一些 debug 用或者畫圖用的 function 會被寫在裡面。
- Makefile (只有 Windows 沒有)：為了讓我們能更方便的編譯程式 (只要輸入一個make就可以全部編譯完）而寫成的檔案。如果要新增自己的程式碼需要將其加入才可以編譯。
- build.bat、run.bat (只有 Windows 有)：跟Makefile功能類似的東西。如果要新增自己的程式碼需要將其加入才可以編譯。
- include、lib、mingw64 (只有 Windows 有)：為了讓遊戲能夠正常編譯而放的東西。作業中不需要看懂或額外修改裡面的內容。
- hw.cpp：純粹講師之前自己寫的草稿，可以不用理它。（當然你如果想自己玩玩看也OK）

### 程式架構
本遊戲使用 allegro5 做圖形界面開發，主要程式架構如上圖。
遊戲一開始會去呼叫不同的 scene 來進行遊戲。每個 scene 會有 4 個 function。
- draw 繪製場景
- destroy 釋放資源
- start_event_loop 處理鍵盤資訊並定期呼叫 update 和 draw
- update 所有你想要做到的遊戲邏輯請在這個 function 內完成

### 遊戲運作方式
在遊戲開始後，main function會呼叫相應的遊戲場景的start_event_loop
在loop裡面會有一個event_queue，而我們的timer會在每1/FPS秒丟一個event進去，或是我們的鍵盤會在我們按下或離開按鍵時給一個event，所以我們的遊戲會定期的去拿event_queue來判斷使用者有沒有進行甚麼特殊操作，如果沒有的話就是一般的渲染和更新遊戲。
### 遊戲中的 Object

而遊戲內玩家、隕石、子彈、道具，皆爲 Object，藉由操控 Object 的移動碰撞來進行遊戲。
- 每個 Object必定有以下參數以及 function。
- x 代表該 Object 的x位置
- y 代表該 Object 的y位置
- speedX 代表該 Object 的x軸速度
- speedY 代表該 Object 的y軸速度
- destroy 釋放資源
- update 當遊戲想要更新該物件時呼叫此 function

- 玩家（太空船）。以下介紹太空船的幾個重要的參數：

- 血量（hp）（界在 0~100 之間，開局時是 100 。若是歸零就輸了）
- 子彈威力（bullet_power）（敵人被打到時所造成的傷害。正整數，開局時是 3 。）
- 經驗值（exp）（界在 0~100 之間，開局時是 0 。每打掉一個隕石會加 20 ，滿 100 時會讓子彈威力加 1 ）
- 能量（energy）（界在 0~100 之間，開局時是 100 。每個 fram 會回復 1 ，每射一發子彈會消耗 20 ，如果能量小於 20 就無法發射）
- 所需冷卻時間（bullet_cool）（界在 0~5 之間，開局時是 0 。射子彈後會變成 5 ，每個 fram 會減少 1 ，如果非 0 就無法發射。換句話說，每 5 個 fram 最多只能發射一發子彈）

- 隕石：每個 fram 會隨機在地圖邊界的某些地方生成，然後直線飛向地圖內。玩家若是撞到，血量會減3。若是用子彈打掉，經驗值會加20。遊戲越後期，生成的隕石數量越多。

- 子彈：玩家每個 fram 可以向正前方花費 20 點能量發射一發。子彈打到對手可對對手造成傷害（傷害值由玩家的子彈威力而定）。打到隕石可以加 20 經驗值。

- 道具：每個 fram 會有一定的機率生成於場地的某處，玩家碰到的話可以獲得效果。以下是道具種類：

- 補血包（紅色藥水）：玩家撿到時，HP+30
- 經驗包（紫色藥水）：玩家撿到時，子彈威力+1
- 能量包（綠色藥水）：玩家撿到時，energy+100

### AI做法
#### 功能要求
請將你的AI model繼承AI資料夾裡面的model.hpp，並實作裡面兩個函數。
- initial 在遊戲初始化時會呼叫，主要實作一些你的AI model需要初始化參數的部分
- update 在遊戲每次更新時會呼叫，用來決定你的戰鬥機行為，回傳為一個整數array，代表你AI操作的key_state，其key_state表示法跟allegro5的[key code](https://liballeg.org/a5docs/trunk/keyboard.html#allegro_keyboard_state)一樣

initial 和 update 可以根據場上的資訊來當作參數，以下我們列出兩種可以拿來參考的做法，這兩座做法你可以選一個適合自己的，或是你有這之外的其他想法也可以自己做做看：

#### 實作方法一：以GameMap作參數
- 遊戲中座標軸中 x 是朝右的、 y 是朝下的
- 記得從 0 開始數，地圖大小為80*26
由於遊戲是從terminal版本移植過來的，在原本的terminal版本所有的座標都是整數，但allegro比較精緻可支援float的座標軸，所以為了保證遊戲的品質在移動和撞擊判斷等是利用浮點數做計算。
而如果仔細看一下繪製的功能，會發現我們將原本正方形的座標系統畫成長方型，code部分會將x軸長度乘scale，y軸長度乘兩倍的scale，其原因是因為terminal在繪製一個字元時就是長方形的。
而要傳給model的GameMap請將每個Object座標轉換成int後再依照對應物件所在位置繪製GameMap。
##### 繪製規則
請產生出80*26的char陣列其中沒有任何Object的地方以\0表示其餘參考下面
- 非自己操作的戰鬥機: 3 * 3的*
- 自己操作的戰鬥機: 3 * 3的&
- 隕石: 1 * 1的o
- 子彈: 1 * 1的.
- 藥水A: 1 * 1的 A(第二個藥水為B，第三個為C以此類推)
最後大致會產生一個如下圖的二維陣列
(請忽略邊框和中線)
用這樣子的 char 的二維陣列，就可以知道現在場面上的狀態，進而讓電腦決定下一步該怎麼行動。

#### 實作方法二：以object_list作參數
object_list 是一個存著遊戲中各個物件資料的 list（list也是 STL 的其中一種，下面會介紹），你也可以根據 object_list 之中的內容來當參數，讓你的AI決定他接下來的行動。

### 另外你需要知道的Allegro 5 的 function。
[al_load_ttf_font](https://www.allegro.cc/manual/5/al_load_ttf_font)
[al_draw_rectangle](https://www.allegro.cc/manual/5/al_draw_rectangle)
[al_draw_line](https://www.allegro.cc/manual/5/al_draw_line)
[al_draw_text](https://www.allegro.cc/manual/5/al_draw_text)
[al_destroy_bitmap](https://www.allegro.cc/manual/5/al_destroy_bitmap)
[al_destroy_font](https://www.allegro.cc/manual/5/al_destroy_font)
[其他功能](https://www.allegro.cc/manual/5/)
### 補充list
list大概是長的像上面這張圖的東西，一個node裡面會紀錄資料和前後連結的指標，而我們可以透過紀錄頭node並透過每個node的指標來跑過所有資料。
那他跟vector有甚麼差別呢?vector可以任意查找某個位置的資料，但list只能從頭開始跑，直到找到你要找的那個位置才能找到資料。但同時list刪除資料只要修改指標就好，而vector在移除時要移動後面整個資料的位置。
所以在遊戲中objec_list需要大量的加入和移除object，但卻不太需要找尋某個位置的object是甚麼，所以我們選擇使用list來做儲存。
而我們要用到的只有list的幾個小功能
1. push_back(data) 插入一個data到list的尾端
2. erase(iterator) 移除iterator指到的資料，並會回傳接上來的資料的iterator
[更多List的用法請看這](https://www.cplusplus.com/reference/list/list/)

## 如何玩遊戲？
### 環境設定與編譯遊戲
請先看看你的電腦是 Windows，Linux，還是 Mac，然後找到對應的說明。

#### windows
請到[下載連結](https://drive.google.com/drive/folders/1DvY1MNgWOdDTSFjtnFi12IpVjEwAuugw?usp=sharing)，下載 HW2_windows.zip（檔案有點大，可能需要一段時間），然後把這個 .zip檔解壓縮之後放到桌面。

請點開以下檔案來編譯程式

./build.bat

請點開以下檔案來跑遊戲

./run.bat

build.bat介紹

:關掉提示
@echo off 
:設定mingw也就是之後g++的路徑
set PATH=%PATH%;%cd%\mingw64\bin
:刪除舊的檔案
del .\bin /Q
:創立資料夾
md .\bin
md .\bin\object
:編譯其他檔案
g++ .\src\object\potion.cpp -c -o .\bin\object\potion.o -Wall -Wextra -std=c++17 -Isrc -Iinclude 
g++ .\src\object\asteroid.cpp -c -o .\bin\object\asteroid.o -Wall -Wextra -std=c++17 -Isrc -Iinclude 
g++ .\src\object\bullet.cpp -c -o .\bin\object\bullet.o -Wall -Wextra -std=c++17 -Isrc -Iinclude 
g++ .\src\object\player.cpp -c -o .\bin\object\player.o -Wall -Wextra -std=c++17 -Isrc -Iinclude 
md .\bin\engine
g++ .\src\engine\end.cpp -c -o .\bin\engine\end.o -Wall -Wextra -std=c++17 -Isrc -Iinclude 
g++ .\src\engine\menu.cpp -c -o .\bin\engine\menu.o -Wall -Wextra -std=c++17 -Isrc -Iinclude -lallegro 
g++ .\src\engine\mainGame.cpp -c -o .\bin\engine\mainGame.o -Wall -Wextra -std=c++17 -Isrc -Iinclude 
g++ .\src\engine\scene.cpp -c -o .\bin\engine\scene.o -Wall -Wextra -std=c++17 -Isrc -Iinclude 
md .\bin\utils
g++ .\src\utils\imageProcess.cpp -c -o .\bin\utils\imageProcess.o -Wall -Wextra -std=c++17 -Isrc -Iinclude 
g++ .\src\utils\log.cpp -c -o .\bin\utils\log.o -Wall -Wextra -std=c++17 -Isrc -Iinclude 
:將所有檔案link在一起
g++ .\src\main.cpp -o .\bin\main.exe .\bin\object\potion.o .\bin\object\asteroid.o .\bin\object\bullet.o .\bin\object\player.o .\bin\engine\end.o .\bin\engine\menu.o .\bin\engine\mainGame.o .\bin\engine\scene.o .\bin\utils\imageProcess.o .\bin\utils\log.o -Wall -Wextra -std=c++17 -Isrc -Iinclude -lallegro -lallegro_font  -lallegro_image -lallegro_ttf -lallegro_primitives -Llib
pause

run.bat介紹

:設定library的路徑
set PATH=%PATH%;%cd%\mingw64\bin
:執行程式
start .\bin\main.exe

#### linux(ubuntu)
請到[下載連結](https://drive.google.com/drive/folders/1DvY1MNgWOdDTSFjtnFi12IpVjEwAuugw?usp=sharing)，下載 HW2_linux.zip，然後解壓縮之後把解壓縮後的資料夾放到桌面。

打開shell輸入以下指令來做前置安裝

sudo apt-get install make g++
sudo add-apt-repository ppa:allegro/5.2
sudo apt-get install liballegro*5.2 liballegro*5-dev

在shell輸入以下指令進入 HW2_linux 資料夾

cd Desktop
cd HW2_linux

在shell輸入以下指令編譯程式

make

在shell輸入以下指令跑遊戲

./bin/main

Makefile介紹

//設定include資料夾
INCLUDE_PATH = src/ 
//設定編譯參數
CPP_FLAGS = -Wall -Wextra -std=c++17
//設定有哪些檔案要先編譯成.o檔
_OBJS = bin/utils/log.o\
		bin/utils/imageProcess.o\
 		bin/engine/scene.o\
		bin/engine/menu.o\
		bin/engine/mainGame.o\
		bin/engine/end.o\
		bin/object/player.o\
		bin/object/bullet.o\
		bin/object/asteroid.o\
		bin/object/potion.o
//link allegro的library
ALLEGRO_OPTIONS = -I/usr/include/x86_64-linux-gnu -lallegro_font -lallegro -lallegro_ttf -lallegro_primitives -lallegro_image

all: bin/main

clean:
	rm -rf bin/
	rm hw.out
// 開始編譯
bin/main: src/main.cpp $(_OBJS)
	g++ $^ -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

bin/utils/log.o: src/utils/log.cpp
	mkdir -p bin/utils
	g++ $^ -c -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

bin/utils/imageProcess.o: src/utils/imageProcess.cpp
	mkdir -p bin/utils
	g++ $^ -c -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

bin/engine/mainGame.o: src/engine/mainGame.cpp
	mkdir -p bin/engine
	g++ $^ -c -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

bin/engine/scene.o: src/engine/scene.cpp
	mkdir -p bin/engine
	g++ $^ -c -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

bin/engine/menu.o: src/engine/menu.cpp
	mkdir -p bin/engine
	g++ $^ -c -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

bin/engine/end.o: src/engine/end.cpp
	mkdir -p bin/engine
	g++ $^ -c -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

bin/object/player.o: src/object/player.cpp
	mkdir -p bin/object
	g++ $^ -c -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

bin/object/bullet.o: src/object/bullet.cpp
	mkdir -p bin/object
	g++ $^ -c -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

bin/object/asteroid.o: src/object/asteroid.cpp
	mkdir -p bin/object
	g++ $^ -c -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

bin/object/potion.o: src/object/potion.cpp
	mkdir -p bin/object
	g++ $^ -c -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

#### mac
請到[下載連結](https://drive.google.com/drive/folders/1DvY1MNgWOdDTSFjtnFi12IpVjEwAuugw?usp=sharing)，下載 HW2_mac.zip，然後解壓縮之後把解壓縮後的資料夾放到桌面。

打開終端機，輸入以下指令來做前置安裝

brew install allegro
brew install pkg-config

在終端機輸入以下指令進入 HW2_mac 資料夾

cd Desktop
cd HW2_mac

在終端機輸入以下指令編譯程式

make

在終端機輸入以下指令跑遊戲

./bin/main

Makefile介紹

//設定include資料夾
INCLUDE_PATH = src/ 
//設定編譯參數
CPP_FLAGS = -Wall -Wextra -std=c++17
//設定有哪些檔案要先編譯成.o檔
_OBJS = bin/utils/log.o\
		bin/utils/imageProcess.o\
 		bin/engine/scene.o\
		bin/engine/menu.o\
		bin/engine/mainGame.o\
		bin/engine/end.o\
		bin/object/player.o\
		bin/object/bullet.o\
		bin/object/asteroid.o\
		bin/object/potion.o
//link allegro的library
ALLEGRO_OPTIONS = -I/usr/include/x86_64-linux-gnu -lallegro_font -lallegro -lallegro_main -lallegro_ttf -lallegro_primitives -lallegro_image

all: bin/main

clean:
	rm -rf bin/
	rm hw.out
// 開始編譯
bin/main: src/main.cpp $(_OBJS)
	g++ $^ -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

bin/utils/log.o: src/utils/log.cpp
	mkdir -p bin/utils
	g++ $^ -c -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

bin/utils/imageProcess.o: src/utils/imageProcess.cpp
	mkdir -p bin/utils
	g++ $^ -c -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

bin/engine/mainGame.o: src/engine/mainGame.cpp
	mkdir -p bin/engine
	g++ $^ -c -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

bin/engine/scene.o: src/engine/scene.cpp
	mkdir -p bin/engine
	g++ $^ -c -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

bin/engine/menu.o: src/engine/menu.cpp
	mkdir -p bin/engine
	g++ $^ -c -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

bin/engine/end.o: src/engine/end.cpp
	mkdir -p bin/engine
	g++ $^ -c -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

bin/object/player.o: src/object/player.cpp
	mkdir -p bin/object
	g++ $^ -c -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

bin/object/bullet.o: src/object/bullet.cpp
	mkdir -p bin/object
	g++ $^ -c -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

bin/object/asteroid.o: src/object/asteroid.cpp
	mkdir -p bin/object
	g++ $^ -c -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

bin/object/potion.o: src/object/potion.cpp
	mkdir -p bin/object
	g++ $^ -c -o $@ $(CPP_FLAGS) -I$(INCLUDE_PATH) $(ALLEGRO_OPTIONS)

### 玩遊戲
如果你的檔案成功跑起來了，你應該會看到如下的畫面：
這就代表你的環境設置完成，可以開始玩遊戲(X)寫作業(O)了。按ASDW、空白鍵、上下左右、Enter，就可以操控了。

### 注意
[更多allegro安裝](https://github.com/liballeg/allegro_wiki/wiki/Quickstart)
如果之後有要新增其他檔案，請一定也要加入編譯成.o檔案再跟main.cpp一起link產生執行檔才能用喔。

## 你需要做什麼？
### 1. 送分嗎？ (20%)
1. 成功跑起遊戲(10%)
2. 更改各種(大於等於2個) icon (5%)
3. 讓P1跟P2各勝利一次並截圖寫入報告 (5%)
### 2. 好像有BUG (10%)
1. 遊戲有個小 BUG 在結束程式時無法正常結束，請把它修正並在報告中描述你怎麼修正和發現的。
(如果在程式結束時有log出successful finish就代表你完成了，請不要把delete mainGame刪除掉，這樣會看到successful finish但不會有分喔，也請不要亂移動log的位置。)
### 3. 大AI時代 (20%) bonus(10%)
1. 請修改遊戲讓遊戲可以透過 Model class 中 update 回傳的值來控制對手玩家(10%)
(請在報告中描述你的程式要怎麼讓AI model控制，比如model程式碼的檔名)
2. 如果有做四人遊戲請同時支援對手2個 Model 的操控(5%)
3. 在AI資料夾裏面有個Model請繼承他並設計自己的AI(5%)
4. bonus 打贏助教的Model(未來會再公布Model)(10%)
### 4. 四人遊戲比較好玩 (10%)
1. 請將遊戲設計爲四人遊戲(5%)
2. 在雙人遊戲中同隊的角色不會互相撞到，但子彈會打到隊友並且會正確的扣血(5%)
### 5. 新增子彈種類 (20%)
1. 請爲每一個玩家設計他自己獨特的子彈 (5%) * 4
(example: 被子彈射中後會每秒會扣hp持續5秒)
### 6. 新增道具種類 (20%)
1. 請設計不同的道具 (5%) * 4
(example: 吃到會產生無敵效果10秒)
### bonus (10%)
1. 設計一些你覺得好玩的機制並在報告中描述

## 繳交作業
到這個表單繳交：https://forms.gle/hS29RRcz56PAjD8p8
- 上傳程式檔案
1. 為了避免檔案過大請將bin資料夾刪除，windows同學請將mingw64、lib、include資料夾刪除
2. 將整個資料夾壓縮成zip檔案
- 實作報告
1. 報告格式請繳交pdf檔案
2. 如果有特殊編譯方式請在報告中描述(如果你有包任何其他的檔案請一併繳交)
3. 報告內容包含每一項作業你做到了甚麼，並且簡述你怎麼做到的
(報告字越多不會越多分喔~)
**Deadline 7/8** （要早點開始做哦～）
## FAQ
- 遊戲說某某檔案not fund
- linux請檢查開啟路徑在作業最開始資料夾，其他人請檢查你是否有刪除或改變檔案名字，或是大小寫不對
- g++ not found
- 如果你是用windows最好用cmd開不要用powershell開
- va_list not declare
- 如果是用windows修改build.bat的第二行為

- 繳交作業是否有規定檔名？
    - 沒有
    
###### tags: `資訊之芽`