blayyyyyk/marIOkart

# MarI/O Kart **目录** 1. [安装指南](#installation-guide) 2. [使用指南](#usage-guide) 1. [数据集收集](#dataset-collection) 1. [录制 .dsm](#recording-dsm) 2. [录制 .sav](#recording-sav) 2. [训练模型](#training-the-model) 1. [监督学习](#supervised-learning) 2. [强化学习 (实验性)](#reinforcement-learning) 3. [评估模型](#evaluating-the-model) 4. [调试工具](#debugging-tools) 3. [使用 MarioKart DS Memory API](#working-with-the-mariokart-ds-memory-api) 4. [使用 Gymnasium](#working-with-gymnasium) ## 安装指南 1. 克隆仓库 ``` git clone https://github.com/blayyyyyk/marIOkart.git ``` 2. 安装依赖 ``` pip install -r requirements.txt ``` ## 使用指南 本项目的所有工具均可通过以下命令运行。 ``` cd [name of repo directory] python src/main.py ``` ### 数据集收集 对于我们的监督学习训练 pipeline，我们需要带有标签的速通玩家数据训练样本。目前，我们训练模型根据一组观测数据预测速通玩家的输入。 **录像回放** 我们的训练环境使用一个名为 DeSmuME 的 Nintendo DS 模拟器。利用 DeSmuME 内置的录像回放功能，我们可以将一系列控制器输入加载到游戏开始时，模拟器将使用逐帧的预录制输入实时回放游戏。在此回放过程中，我们的脚本将收集并预计算观测数据以保存到文件中。然后，我们的模型必须根据此观测数据预测玩家的控制器输入。 #### 录制 `.dsm` `record.py` 用于使用 desmume 兼容的录像文件录制数据集。 ``` usage: record.py [-h] [--dest DEST] [--num-proc NUM_PROC] [--process] [--scale SCALE] [--device DEVICE] [--verbose] source [source ...] positional arguments: source Movie files (.dsm) or Game saves (.sav) to collect observation datasets from. Can either be individual files, a list of files, or a directory of acceptable files. options: -h, --help show this help message and exit --dest DEST, -o DEST Where to output the datasets to --num-proc NUM_PROC maximum number of subprocesses to spawn --process when flag is enabled, will make a call to process() before collecting datasets --scale SCALE specify the scale of the gtk window --device DEVICE PyTorch device name (ex. 'cpu', 'mps', 'cuda') --verbose, -v Enable verbose console logging for debugging ``` #### 录制 `.sav` `.sav` 文件是 MarioKartDS 特有的游戏存档文件。从存档文件中，你可以提取所谓的“幽灵输入”(ghost inputs)，它们来自计时赛，其作用本质上与 `.dsm` 文件相同，但幽灵输入是游戏内部的。要从 `.sav` 文件录制训练数据集，你必须首先提取所有幽灵输入并使用 `process.py` 将其转换为 `.dsm` 文件 `process.py` - 从 `.sav` 文件中提取所有 `.dsm` 文件。 ``` usage: process.py [-h] [--device DEVICE] [--verbose] source [source ...] positional arguments: source Game saves (.sav) to extract ghost inputs from. Can either be individual files, a list of files, or a directory of acceptable files. options: -h, --help show this help message and exit --device DEVICE PyTorch device name (ex. 'cpu', 'mps', 'cuda') --verbose, -v Enable verbose console logging for debugging ``` ### 训练模型 我们正在尝试各种类型的学习方法。我们目前正致力于使用速通数据的监督学习，以及不直接使用速通数据的强化学习。 #### 监督学习 `train.py` - 在指定模型上使用监督学习运行训练 pipeline。 ``` usage: train.py [-h] [--model-name MODEL_NAME] [--course-name COURSE_NAME] [--epochs EPOCHS] [--lr LR] [--batch-size BATCH_SIZE] [--split-ratio SPLIT_RATIO] [--seq-len SEQ_LEN] [--device DEVICE] [--verbose] source [source ...] positional arguments: source List of training data sources to use options: -h, --help show this help message and exit --model-name MODEL_NAME The name of the model to record a checkpoint of after training --course-name COURSE_NAME, -c COURSE_NAME --device DEVICE PyTorch device name (ex. 'cpu', 'mps', 'cuda') --verbose, -v Enable verbose console logging for debugging Training Hyperparameters: --epochs EPOCHS, -e EPOCHS Number of training epochs. --lr LR Learning rate --batch-size BATCH_SIZE Batch size --split-ratio SPLIT_RATIO Ratio of training data to split into train and test sets --seq-len SEQ_LEN Size of the sequence length of the training samples ``` #### 强化学习 ``` usage: train_rl.py [-h] [--epochs EPOCHS] [--course {f8c,yf,ccb,lm,dh,ds,wp,sr,dkp,ttc,mc,af,ws,pg,bc,rr,rmc1,rmmf,rpc,rlc1,rdp1,rfs,rbc2,rbp,rkb2,rcm,rlc2,rmb,rci2,rbb,rsg,ryc}] [--device DEVICE] [--verbose] [--scale SCALE] movie_source [movie_source ...] {ppo,dqn,a2c} positional arguments: movie_source movie files to perform menu naviagtion before training {ppo,dqn,a2c} training algorithm options: -h, --help show this help message and exit --epochs EPOCHS number of training epochs --course {f8c,yf,ccb,lm,dh,ds,wp,sr,dkp,ttc,mc,af,ws,pg,bc,rr,rmc1,rmmf,rpc,rlc1,rdp1,rfs,rbc2,rbp,rkb2,rcm,rlc2,rmb,rci2,rbb,rsg,ryc} --device DEVICE PyTorch device name (ex. 'cpu', 'mps', 'cuda') --verbose, -v Enable verbose console logging for debugging --scale SCALE specify the scale of the gtk window ``` ### 评估模型 `eval.py` - 在带有显示窗口的基于 gym 的游戏环境中以纯推理模式运行模型。需要 `.dsm` 文件来控制初始菜单导航。 ``` usage: eval.py [-h] [--scale SCALE] [--device DEVICE] [--verbose] model_name movie_source [movie_source ...] positional arguments: model_name name of model to evaluate movie_source the file(s) or director(ies) containing movie replays to source menu controls during evaluation (accepted files: .dsm) options: -h, --help show this help message and exit --scale SCALE specify the scale of the gtk window --device DEVICE PyTorch device name (ex. 'cpu', 'mps', 'cuda') --verbose, -v Enable verbose console logging for debugging ``` ### 调试工具 该程序还支持在游戏环境中接收用户输入。如果你正在测试用于显示游戏内数据的自定义视觉覆盖层，这会很有用。 `debug.py` - 用于人类用户输入或录像回放 (`.dsm`) 的调试模式 ``` usage: debug.py [-h] [--scale SCALE] [--device DEVICE] [--verbose] mode movie-source [movie-source ...] positional arguments: mode debugging mode for debug tool. available modes (movie, play) movie-source the file(s) or director(ies) containing movie replays to source menu controls during evaluation (accepted files: .dsm) options: -h, --help show this help message and exit --scale SCALE specify the scale of the gtk window --device DEVICE PyTorch device name (ex. 'cpu', 'mps', 'cuda') --verbose, -v Enable verbose console logging for debugging ``` ## 使用 MarioKart DS Memory API 在底层，我们使用一个名为 `py-desmume` 的流行库。它是一个用于与 DeSmuME C API 交互的 Python 库。我们 fork 了这个 Python 项目并集成了自定义功能，用于从内存访问游戏属性。这不仅实现了 *100 倍* 的内存读取性能提升，还允许用户以直观且面向对象的方式访问内存属性。 **安装** ``` pip install py-desmume-mkds ``` **示例用法** ``` from desmume.emulator_mkds import MarioKart import torch emu = MarioKart() emu.open('pathtorom.nds') # 为模拟器创建窗口 window = emu.create_sdl_window() # 尽可能快地运行模拟直到退出 while not window.has_quit(): window.process_input() # Controls are the default DeSmuME controls, see below. emu.cycle() window.draw() # checks if a race has started if not emu.memory.race_ready: continue # access the player's current kart position kart_position: torch.Tensor = emu.memory.driver.position # access the player's current boost timer boost_timer: float = self.emu.memory.driver.boostTimer # access the player's current race_progress race_progress: float = emu.memory.race_status.driverStatus[0].raceProgress ``` ## 使用 Gymnasium

标签：AI游戏代理, Apex, DeSmuME模拟器, Gymnasium, KCL解析器, MarI/O, NKM解析器, Python, PyTorch, 人工智能, 任天堂DS, 内存API, 凭据扫描, 强化学习, 数据集收集, 无后门, 机器人流程自动化, 机器学习, 深度学习, 游戏自动化, 用户模式Hook绕过, 电子游戏, 监督学习, 神经网络, 计算机视觉, 逆向工具, 速度通关, 马里奥赛车DS