mlgame

Name	mlgame JSON
Version	10.4.5.3 JSON
	download
home_page	https://github.com/PAIA-Playful-AI-Arena/MLGame
Summary	A machine learning game framework based on Pygame
upload_time	2024-02-29 07:12:13
maintainer
docs_url	None
author	PAIA
requires_python	>=3.10.0
license
keywords	ai machine learning game framework
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage

            # MLGame
![mlgame](https://img.shields.io/github/v/tag/PAIA-Playful-AI-Arena/mlgame)
![mlgame](https://img.shields.io/pypi/v/mlgame)
  
[![Python 3.9](https://img.shields.io/badge/python->3.9-blue.svg)](https://www.python.org/downloads/release/python-390/)
[![pygame](https://img.shields.io/badge/pygame->2.0.1-blue.svg)](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 數量。

### `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. [系統架構]&#40;./docs/System.md&#41;)


   
# 相關專案

> 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/yen900611/racing_car)
> 6. 迷宮自走車 [Maze Car](https://github.com/yen900611/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": "",
    "docs_url": null,
    "requires_python": ">=3.10.0",
    "maintainer_email": "",
    "keywords": "AI,machine learning,game,framework",
    "author": "PAIA",
    "author_email": "service@paia-tech.com",
    "download_url": "https://files.pythonhosted.org/packages/87/d8/2b4ae699b2e922de062a8ec3487cc7d92ec6e1e82d2bfe5ff88ffaad917b/mlgame-10.4.5.3.tar.gz",
    "platform": null,
    "description": "# MLGame\n![mlgame](https://img.shields.io/github/v/tag/PAIA-Playful-AI-Arena/mlgame)\n![mlgame](https://img.shields.io/pypi/v/mlgame)\n  \n[![Python 3.9](https://img.shields.io/badge/python->3.9-blue.svg)](https://www.python.org/downloads/release/python-390/)\n[![pygame](https://img.shields.io/badge/pygame->2.0.1-blue.svg)](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\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]&#40;./docs/System.md&#41;)\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/yen900611/racing_car)\n> 6. \u8ff7\u5bae\u81ea\u8d70\u8eca [Maze Car](https://github.com/yen900611/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": "",
    "summary": "A machine learning game framework based on Pygame",
    "version": "10.4.5.3",
    "project_urls": {
        "Homepage": "https://github.com/PAIA-Playful-AI-Arena/MLGame"
    },
    "split_keywords": [
        "ai",
        "machine learning",
        "game",
        "framework"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "2e99c96b0f946b8e657b6b10bcad6bdd1148e1da80a17c07570fb7b04cf095cb",
                "md5": "aa159f38bcde27d0dd43298d86811e6c",
                "sha256": "cc9fd0c0d7cd755098073c5e5be6601a45bfbd1b1f684f2cc696497e230cf0d2"
            },
            "downloads": -1,
            "filename": "mlgame-10.4.5.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "aa159f38bcde27d0dd43298d86811e6c",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10.0",
            "size": 45043,
            "upload_time": "2024-02-29T07:12:10",
            "upload_time_iso_8601": "2024-02-29T07:12:10.393214Z",
            "url": "https://files.pythonhosted.org/packages/2e/99/c96b0f946b8e657b6b10bcad6bdd1148e1da80a17c07570fb7b04cf095cb/mlgame-10.4.5.3-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "87d82b4ae699b2e922de062a8ec3487cc7d92ec6e1e82d2bfe5ff88ffaad917b",
                "md5": "cb126dbd5515b533132d6440d0d6b193",
                "sha256": "c2de70cdcbdc33b54a42b36a1aad730707df0d09309ff8b1fb1ec8ac09eb27d5"
            },
            "downloads": -1,
            "filename": "mlgame-10.4.5.3.tar.gz",
            "has_sig": false,
            "md5_digest": "cb126dbd5515b533132d6440d0d6b193",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10.0",
            "size": 118494,
            "upload_time": "2024-02-29T07:12:13",
            "upload_time_iso_8601": "2024-02-29T07:12:13.310168Z",
            "url": "https://files.pythonhosted.org/packages/87/d8/2b4ae699b2e922de062a8ec3487cc7d92ec6e1e82d2bfe5ff88ffaad917b/mlgame-10.4.5.3.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-02-29 07:12:13",
    "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": [],
    "lcname": "mlgame"
}