# MLGame
[](https://www.python.org/downloads/release/python-390/)
[](https://github.com/pygame/pygame/releases/tag/2.0.1)
---
這是一個遊戲ＡＩ競賽的框架，依照此框架所開發的遊戲，可以透過ＡＩ來玩遊戲，並進行ＡＩ競賽。
Table of Contents
=================
# ! 重要 !
1. 此次更新為大幅度更新專案架構，原有的指令方式、遊戲皆無法執行，因此請注意遊戲與MLGame的搭配。
# 使用方式
[//]: # (TODO demo gif)
## 終端機範例
- 列出 help 文件
```shell
python -m mlgame -h
```
- 命令列格式
```shell
python -m mlgame [options] <game_folder> [game_params]
```
- 執行打磚塊遊戲
```shell
python -m mlgame \
-f 120 -i ./path/to/ai/ai_client_file_name.py \
./path/to/game/arkanoid \
--difficulty NORMAL --level 3
```
- AI和遊戲的資料夾路徑可以使用`相對路徑`或是`絕對路徑`
- 遊戲參數`game_params`須參考各個遊戲
## 位置引數(Positional Argument)
- `game_folder`
- `required`
- 遊戲資料夾所在的路徑，此路徑下需有`config.py`
## 功能性引數(Functional Argument)
### `options`
- `--version` 顯示MLGame版本號
- `-h`, `--help`
- 提供參數的說明
- `-f` `FPS`, `--fps` `FPS`
- 設定遊戲的遊戲更新率(frame per second)，遊戲預設為每秒更新30次。
- `default` : `30`
- `-1`, `--one-shot`
- 表示遊戲只執行一次，沒有加上這個參數，遊戲皆會不斷重新執行。
- `default` : `False`
- `--nd`, `--no-display`
- 加上此參數就不會顯示螢幕畫面。
- `default` : `False`
- `--ws_url` `WS_URL`
- 加上此參數，會建立一個websocket connection，並將遊戲過程中的資料傳到指定的路徑，若路徑失效，則遊戲無法啟動。
- `-i` `AI_Client`, `--input-ai` `AI_Client`
- 指定要玩遊戲的AI，AI的檔案中，需要包含`MLPlay`這個class。
- 若有多個玩家，可直接參考下方案例，路徑可以使用絕對路徑與相對路徑。
```
-i ./path/to/ai/ai_01.py -i ./path/to/ai/ai_02.py
```
- AI數量需符合遊戲需求，每個遊戲都會有最小值與最大值，不足的會以最後一個AI自動補足，多的會自動刪去。
- 遊戲若需要2個AI，給到1個AI則會同時扮演1P 2P
- 遊戲若需要2個AI，給到3個AI則會自動排除最後一個
- `-o` `output_folder`, `--output-folder` `output_folder`
- 將遊戲過程儲存到特定資料夾中，會自動建立一個時間戳記資料夾來儲存每一幀的圖片。
- 此資料夾需要可讀寫，並且為有效路徑。
- 若是沒有加上 `-1` ，會不斷的紀錄遊戲結果。
- 此選項會影響到執行效能，開啟後覺得卡頓屬於正常現象。
- `-r` `progress-folder`, `--progress-folder` `progress-folder`
- 將遊戲每個 frame 儲存到特定資料夾中，會自動建立一個時間戳記資料夾來儲存各 frame 的內容，以檔案分開。
- 可透過 `-p`, `--progress-frame-frequency` 指定一個檔案內的 frame 數量。
- 檔案內容為 json，檔案名稱代表此檔案由哪個 frame 開始紀錄。
- 此資料夾需要可讀寫，並且為有效路徑。
- `-p` `progress-frame-frequency`, `--progress-frame-frequency` `progress-frame-frequency`
- 與 `-r`, `--progress-folder` 搭配。
- 可指定一個檔案內的 frame 數量。
- `--ns` , `--no-sound`
- 預設會開啟音效設定，加上此參數會關閉音效。
- `--debug`
- 顯示debug 資訊，並紀錄`debug.log`檔案
### `game_params`
- `optional`
- 執行遊戲的參數依照每個遊戲有所不同，格式為`--name_of_params` `value_of_params`
- type
- int : `0` `1` `-1` `1.5`
- str : `"0"` `"hello"` `"NORMAL"`
- list: `0,1` `-1,1000,111` `abc,cde,12`
- path: `./relative_path_to_file/file.txt`,`/absoulute_path_to_file/file.dat`
# 畫面控制
- 遊戲執行可以使用 `I` `J` `K` `L` 進行平移
- 使用 `U` `O`放大縮小
- 使用 `H` 開啟或關閉部分資訊
- 使用 `P` 暫停遊戲畫面，暫停期間，遊戲邏輯不會運作，但仍可以調整畫面。
[//]: # (# 其他)
[//]: # ()
[//]: # (1. [系統架構](./docs/System.md))
# 相關專案
> 1. [PAIA-Desktop](https://github.com/PAIA-Playful-AI-Arena/Paia-Desktop)
> 2. 範例遊戲 [easy_game](https://github.com/PAIA-Playful-AI-Arena/easy_game)
> 3. 打磚塊 [arkanoid](https://github.com/PAIA-Playful-AI-Arena/arkanoid)
> 4. 乒乓球 [pingpong](https://github.com/PAIA-Playful-AI-Arena/pingpong)
> 5. 賽車 [Racing Car](https://github.com/PAIA-Playful-AI-Arena/racing_car)
> 6. 迷宮自走車 [Maze Car](https://github.com/PAIA-Playful-AI-Arena/maze_car)
# Future Work
1. [ ] Non-python Client Support
2. [ ] test case
4. [ ] 遊戲開發文件
5. [ ]
## Change Log
View [CHANGELOG.md](./CHANGELOG.md)
Raw data
{
"_id": null,
"home_page": "https://github.com/PAIA-Playful-AI-Arena/MLGame",
"name": "mlgame",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10.0",
"maintainer_email": null,
"keywords": "AI, machine learning, game, framework",
"author": "PAIA",
"author_email": "service@paia-tech.com",
"download_url": "https://files.pythonhosted.org/packages/5c/f3/579852793373d462ab0e97b1265dae7cf545585bd86d6aa005027f44ceb8/mlgame-10.5.2.tar.gz",
"platform": null,
"description": "# MLGame\n\n\n \n[](https://www.python.org/downloads/release/python-390/)\n[](https://github.com/pygame/pygame/releases/tag/2.0.1)\n\n---\n\u9019\u662f\u4e00\u500b\u904a\u6232\uff21\uff29\u7af6\u8cfd\u7684\u6846\u67b6\uff0c\u4f9d\u7167\u6b64\u6846\u67b6\u6240\u958b\u767c\u7684\u904a\u6232\uff0c\u53ef\u4ee5\u900f\u904e\uff21\uff29\u4f86\u73a9\u904a\u6232\uff0c\u4e26\u9032\u884c\uff21\uff29\u7af6\u8cfd\u3002\n\nTable of Contents\n=================\n# ! \u91cd\u8981 !\n1. \u6b64\u6b21\u66f4\u65b0\u70ba\u5927\u5e45\u5ea6\u66f4\u65b0\u5c08\u6848\u67b6\u69cb\uff0c\u539f\u6709\u7684\u6307\u4ee4\u65b9\u5f0f\u3001\u904a\u6232\u7686\u7121\u6cd5\u57f7\u884c\uff0c\u56e0\u6b64\u8acb\u6ce8\u610f\u904a\u6232\u8207MLGame\u7684\u642d\u914d\u3002\n\n# \u4f7f\u7528\u65b9\u5f0f\n\n[//]: # (TODO demo gif)\n\n## \u7d42\u7aef\u6a5f\u7bc4\u4f8b\n- \u5217\u51fa help \u6587\u4ef6\n ```shell\n python -m mlgame -h\n ```\n\n- \u547d\u4ee4\u5217\u683c\u5f0f\n ```shell\n python -m mlgame [options] <game_folder> [game_params]\n ```\n - \u57f7\u884c\u6253\u78da\u584a\u904a\u6232\n ```shell\n python -m mlgame \\\n -f 120 -i ./path/to/ai/ai_client_file_name.py \\\n ./path/to/game/arkanoid \\\n --difficulty NORMAL --level 3\n ```\n - AI\u548c\u904a\u6232\u7684\u8cc7\u6599\u593e\u8def\u5f91\u53ef\u4ee5\u4f7f\u7528`\u76f8\u5c0d\u8def\u5f91`\u6216\u662f`\u7d55\u5c0d\u8def\u5f91` \n - \u904a\u6232\u53c3\u6578`game_params`\u9808\u53c3\u8003\u5404\u500b\u904a\u6232 \n\n## \u4f4d\u7f6e\u5f15\u6578(Positional Argument)\n- `game_folder`\n - `required` \n - \u904a\u6232\u8cc7\u6599\u593e\u6240\u5728\u7684\u8def\u5f91\uff0c\u6b64\u8def\u5f91\u4e0b\u9700\u6709`config.py`\n\n\n## \u529f\u80fd\u6027\u5f15\u6578(Functional Argument) \n### `options`\n- `--version` \u986f\u793aMLGame\u7248\u672c\u865f\n- `-h`, `--help`\n - \u63d0\u4f9b\u53c3\u6578\u7684\u8aaa\u660e\n- `-f` `FPS`, `--fps` `FPS`\n - \u8a2d\u5b9a\u904a\u6232\u7684\u904a\u6232\u66f4\u65b0\u7387(frame per second)\uff0c\u904a\u6232\u9810\u8a2d\u70ba\u6bcf\u79d2\u66f4\u65b030\u6b21\u3002\n - `default` : `30`\n- `-1`, `--one-shot`\n - \u8868\u793a\u904a\u6232\u53ea\u57f7\u884c\u4e00\u6b21\uff0c\u6c92\u6709\u52a0\u4e0a\u9019\u500b\u53c3\u6578\uff0c\u904a\u6232\u7686\u6703\u4e0d\u65b7\u91cd\u65b0\u57f7\u884c\u3002 \n - `default` : `False`\n- `--nd`, `--no-display`\n - \u52a0\u4e0a\u6b64\u53c3\u6578\u5c31\u4e0d\u6703\u986f\u793a\u87a2\u5e55\u756b\u9762\u3002 \n - `default` : `False`\n- `--ws_url` `WS_URL`\n - \u52a0\u4e0a\u6b64\u53c3\u6578\uff0c\u6703\u5efa\u7acb\u4e00\u500bwebsocket connection\uff0c\u4e26\u5c07\u904a\u6232\u904e\u7a0b\u4e2d\u7684\u8cc7\u6599\u50b3\u5230\u6307\u5b9a\u7684\u8def\u5f91\uff0c\u82e5\u8def\u5f91\u5931\u6548\uff0c\u5247\u904a\u6232\u7121\u6cd5\u555f\u52d5\u3002\n- `-i` `AI_Client`, `--input-ai` `AI_Client`\n - \u6307\u5b9a\u8981\u73a9\u904a\u6232\u7684AI\uff0cAI\u7684\u6a94\u6848\u4e2d\uff0c\u9700\u8981\u5305\u542b`MLPlay`\u9019\u500bclass\u3002\n - \u82e5\u6709\u591a\u500b\u73a9\u5bb6\uff0c\u53ef\u76f4\u63a5\u53c3\u8003\u4e0b\u65b9\u6848\u4f8b\uff0c\u8def\u5f91\u53ef\u4ee5\u4f7f\u7528\u7d55\u5c0d\u8def\u5f91\u8207\u76f8\u5c0d\u8def\u5f91\u3002\n ```\n -i ./path/to/ai/ai_01.py -i ./path/to/ai/ai_02.py \n ```\n - AI\u6578\u91cf\u9700\u7b26\u5408\u904a\u6232\u9700\u6c42\uff0c\u6bcf\u500b\u904a\u6232\u90fd\u6703\u6709\u6700\u5c0f\u503c\u8207\u6700\u5927\u503c\uff0c\u4e0d\u8db3\u7684\u6703\u4ee5\u6700\u5f8c\u4e00\u500bAI\u81ea\u52d5\u88dc\u8db3\uff0c\u591a\u7684\u6703\u81ea\u52d5\u522a\u53bb\u3002\n - \u904a\u6232\u82e5\u9700\u89812\u500bAI\uff0c\u7d66\u52301\u500bAI\u5247\u6703\u540c\u6642\u626e\u6f141P 2P\n - \u904a\u6232\u82e5\u9700\u89812\u500bAI\uff0c\u7d66\u52303\u500bAI\u5247\u6703\u81ea\u52d5\u6392\u9664\u6700\u5f8c\u4e00\u500b\n- `-o` `output_folder`, `--output-folder` `output_folder`\n - \u5c07\u904a\u6232\u904e\u7a0b\u5132\u5b58\u5230\u7279\u5b9a\u8cc7\u6599\u593e\u4e2d\uff0c\u6703\u81ea\u52d5\u5efa\u7acb\u4e00\u500b\u6642\u9593\u6233\u8a18\u8cc7\u6599\u593e\u4f86\u5132\u5b58\u6bcf\u4e00\u5e40\u7684\u5716\u7247\u3002\n - \u6b64\u8cc7\u6599\u593e\u9700\u8981\u53ef\u8b80\u5beb\uff0c\u4e26\u4e14\u70ba\u6709\u6548\u8def\u5f91\u3002\n - \u82e5\u662f\u6c92\u6709\u52a0\u4e0a `-1` \uff0c\u6703\u4e0d\u65b7\u7684\u7d00\u9304\u904a\u6232\u7d50\u679c\u3002\n - \u6b64\u9078\u9805\u6703\u5f71\u97ff\u5230\u57f7\u884c\u6548\u80fd\uff0c\u958b\u555f\u5f8c\u89ba\u5f97\u5361\u9813\u5c6c\u65bc\u6b63\u5e38\u73fe\u8c61\u3002\n- `-r` `progress-folder`, `--progress-folder` `progress-folder`\n - \u5c07\u904a\u6232\u6bcf\u500b frame \u5132\u5b58\u5230\u7279\u5b9a\u8cc7\u6599\u593e\u4e2d\uff0c\u6703\u81ea\u52d5\u5efa\u7acb\u4e00\u500b\u6642\u9593\u6233\u8a18\u8cc7\u6599\u593e\u4f86\u5132\u5b58\u5404 frame \u7684\u5167\u5bb9\uff0c\u4ee5\u6a94\u6848\u5206\u958b\u3002\n - \u53ef\u900f\u904e `-p`, `--progress-frame-frequency` \u6307\u5b9a\u4e00\u500b\u6a94\u6848\u5167\u7684 frame \u6578\u91cf\u3002\n - \u6a94\u6848\u5167\u5bb9\u70ba json\uff0c\u6a94\u6848\u540d\u7a31\u4ee3\u8868\u6b64\u6a94\u6848\u7531\u54ea\u500b frame \u958b\u59cb\u7d00\u9304\u3002\n - \u6b64\u8cc7\u6599\u593e\u9700\u8981\u53ef\u8b80\u5beb\uff0c\u4e26\u4e14\u70ba\u6709\u6548\u8def\u5f91\u3002\n- `-p` `progress-frame-frequency`, `--progress-frame-frequency` `progress-frame-frequency`\n - \u8207 `-r`, `--progress-folder` \u642d\u914d\u3002\n - \u53ef\u6307\u5b9a\u4e00\u500b\u6a94\u6848\u5167\u7684 frame \u6578\u91cf\u3002\n- `--ns` , `--no-sound` \n - \u9810\u8a2d\u6703\u958b\u555f\u97f3\u6548\u8a2d\u5b9a\uff0c\u52a0\u4e0a\u6b64\u53c3\u6578\u6703\u95dc\u9589\u97f3\u6548\u3002\n- `--debug` \n - \u986f\u793adebug \u8cc7\u8a0a\uff0c\u4e26\u7d00\u9304`debug.log`\u6a94\u6848\n \n\n### `game_params`\n- `optional` \n- \u57f7\u884c\u904a\u6232\u7684\u53c3\u6578\u4f9d\u7167\u6bcf\u500b\u904a\u6232\u6709\u6240\u4e0d\u540c\uff0c\u683c\u5f0f\u70ba`--name_of_params` `value_of_params`\n- type \n - int : `0` `1` `-1` `1.5` \n - str : `\"0\"` `\"hello\"` `\"NORMAL\"`\n - list: `0,1` `-1,1000,111` `abc,cde,12` \n - path: `./relative_path_to_file/file.txt`,`/absoulute_path_to_file/file.dat` \n\n# \u756b\u9762\u63a7\u5236\n- \u904a\u6232\u57f7\u884c\u53ef\u4ee5\u4f7f\u7528 `I` `J` `K` `L` \u9032\u884c\u5e73\u79fb\n- \u4f7f\u7528 `U` `O`\u653e\u5927\u7e2e\u5c0f\n- \u4f7f\u7528 `H` \u958b\u555f\u6216\u95dc\u9589\u90e8\u5206\u8cc7\u8a0a\n- \u4f7f\u7528 `P` \u66ab\u505c\u904a\u6232\u756b\u9762\uff0c\u66ab\u505c\u671f\u9593\uff0c\u904a\u6232\u908f\u8f2f\u4e0d\u6703\u904b\u4f5c\uff0c\u4f46\u4ecd\u53ef\u4ee5\u8abf\u6574\u756b\u9762\u3002\n\n\n[//]: # (# \u5176\u4ed6)\n\n[//]: # ()\n[//]: # (1. [\u7cfb\u7d71\u67b6\u69cb](./docs/System.md))\n\n\n \n# \u76f8\u95dc\u5c08\u6848\n\n> 1. [PAIA-Desktop](https://github.com/PAIA-Playful-AI-Arena/Paia-Desktop)\n> 2. \u7bc4\u4f8b\u904a\u6232 [easy_game](https://github.com/PAIA-Playful-AI-Arena/easy_game)\n> 3. \u6253\u78da\u584a [arkanoid](https://github.com/PAIA-Playful-AI-Arena/arkanoid)\n> 4. \u4e52\u4e53\u7403 [pingpong](https://github.com/PAIA-Playful-AI-Arena/pingpong)\n> 5. \u8cfd\u8eca [Racing Car](https://github.com/PAIA-Playful-AI-Arena/racing_car)\n> 6. \u8ff7\u5bae\u81ea\u8d70\u8eca [Maze Car](https://github.com/PAIA-Playful-AI-Arena/maze_car)\n\n# Future Work\n\n1. [ ] Non-python Client Support\n2. [ ] test case\n4. [ ] \u904a\u6232\u958b\u767c\u6587\u4ef6\n5. [ ] \n\n## Change Log\n\nView [CHANGELOG.md](./CHANGELOG.md)\n",
"bugtrack_url": null,
"license": null,
"summary": "A machine learning game framework based on Pygame",
"version": "10.5.2",
"project_urls": {
"Homepage": "https://github.com/PAIA-Playful-AI-Arena/MLGame"
},
"split_keywords": [
"ai",
" machine learning",
" game",
" framework"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9f8a97890cb67653f0a54500ca8103216dd183348e72913b51e6810015af0703",
"md5": "52298fb7bd6e07008179de5288e0fd1b",
"sha256": "98646d899b2630bc3d76f5b38bd326bfad61659047cafdf09282be745a2572b9"
},
"downloads": -1,
"filename": "mlgame-10.5.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "52298fb7bd6e07008179de5288e0fd1b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10.0",
"size": 49057,
"upload_time": "2024-10-12T02:03:08",
"upload_time_iso_8601": "2024-10-12T02:03:08.935640Z",
"url": "https://files.pythonhosted.org/packages/9f/8a/97890cb67653f0a54500ca8103216dd183348e72913b51e6810015af0703/mlgame-10.5.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5cf3579852793373d462ab0e97b1265dae7cf545585bd86d6aa005027f44ceb8",
"md5": "7b06c5b903af51c1bbbd38395614de90",
"sha256": "c8cbf0f262dc3ce16ec28bcb15dca81aa026c20eb4ea32e6c966101a08eb306f"
},
"downloads": -1,
"filename": "mlgame-10.5.2.tar.gz",
"has_sig": false,
"md5_digest": "7b06c5b903af51c1bbbd38395614de90",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10.0",
"size": 116832,
"upload_time": "2024-10-12T02:03:12",
"upload_time_iso_8601": "2024-10-12T02:03:12.112417Z",
"url": "https://files.pythonhosted.org/packages/5c/f3/579852793373d462ab0e97b1265dae7cf545585bd86d6aa005027f44ceb8/mlgame-10.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-12 02:03:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PAIA-Playful-AI-Arena",
"github_project": "MLGame",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"requirements": [
{
"name": "pygame",
"specs": [
[
"==",
"2.0.1"
]
]
},
{
"name": "pandas",
"specs": [
[
"==",
"1.4.1"
]
]
},
{
"name": "pydantic",
"specs": [
[
"==",
"1.9.0"
]
]
},
{
"name": "websockets",
"specs": [
[
"==",
"10.2"
]
]
},
{
"name": "orjson",
"specs": []
}
],
"lcname": "mlgame"
}
JSON
