Boxoban游戏引擎
该存储库为Boxoban提供了一个基于Python的游戏引擎，Boxoban是一款受Sokoban启发的推盒益智游戏。该引擎允许加载游戏关卡、表示游戏状态、识别有效动作和采取行动。
安装
要使用 BoxobanGame 在您自己的项目中创建类，您首先需要安装它。在终端中导航到此存储库的根目录。
建议使用虚拟环境：
uv venv
source .venv/bin/activate # On Windows use `.venv\Scripts\activate`然后，安装软件包。对于常规安装：
uv pip install .对于可编辑的安装（允许您对源代码进行更改并立即反映出来）：
uv pip install -e .安装后，您可以导入游戏类，如下例所示。
游戏表现
游戏在网格上进行。以下符号用于表示游戏元素：
#：墙-无法通行。@：Player-由用户控制的角色。$：盒子-玩家可以推动的物体。.：Target-箱子的目的地方块。+：玩家在目标上-玩家当前位于目标方块上。*：Box on Target-一个盒子当前位于目标方块上。
游戏的目标是推动所有盒子($)在所有目标方格上(.).当一个盒子在目标上时，它表示为 *.
BoxobanGame 类
发动机的核心是 BoxobanGame 类，位于 boxoban_mcp.game 一旦安装。
初始化和加载游戏
您可以通过多种方式加载游戏：
- 从字符串：
from boxoban_mcp import GameLoader # For loading
# from boxoban_mcp import BoxobanGame # If you need to type hint or refer to the game class directly
board_string = "####\\n#@$.#\\n####"
# Represents:
# ####
# #@$.# (Player, Box, Target)
# ####
game = GameLoader.load_game_from_string(board_string) # Returns a BoxobanGame instance- 从文件中：
谜题文件可以包含由分号和谜题编号分隔的多个谜题（例如。， 0\nPuzzleData0;1\nPuzzleData1). 如果在本地找不到拼图文件，游戏引擎将自动下载并缓存它们。
from boxoban_mcp import GameLoader
# The engine will attempt to load this from a local cache or download it.
# Example: puzzles/medium/train/000.txt
# And puzzle 0 in that file is "####\\n#@.#\\n####"
game = GameLoader.load_game_from_file("medium/train/000.txt", puzzle_index=0)如果一个文件只包含一个没有前导索引号的谜题字符串，请使用 puzzle_index=0. 使用时 load_game_from_file所提供的路径应该相对于缓存的谜题结构的根（例如。， difficulty/split/filename.txt).
- 从参数：
这是加载标准谜题的推荐方法。它自动处理下载和缓存。 如果在本地缓存（通常位于系统的临时目录中）中找不到文件，游戏将构建必要的路径并从在线存储库中获取文件。
from boxoban_mcp import GameLoader
# Loads puzzle 12 from the 'medium' difficulty, 'train' split, set '001'.
# Files will be downloaded and cached if not present locally.
game = GameLoader.load_game_from_params( # Corrected: GameLoader
difficulty="medium",
split="train",
puzzle_set_num="001", # or e.g. 1
puzzle_num=12
)与游戏互动
加载游戏后：
- 获取游戏状态：
使用上述符号（包括 + 和 *).
state_string = game.get_game_state()
print(state_string)
# Example output:
# #####
# # @*# (Player is next to a Box on a Target)
# #####- 获取有效移动：
返回玩家当前可以采取的有效操作列表。动作是字符串： 'up', 'down', 'left', 'right'.
valid_moves = game.get_valid_moves()
# e.g., ['up', 'right']- 采取行动：
将动作应用于游戏状态。退货 True 如果该行为是合法且已执行的， False 否则。
if 'right' in game.get_valid_moves():
was_legal = game.take_action('right')
if was_legal:
print("Moved right!")
print(game.get_game_state())这 take_action 该方法将更新玩家的位置和任何被按下的框。如果玩家将一个盒子推入墙壁或另一个盒子，则该行为是非法的。
- 检查是否已解决：
退货 True 如果所有框都在目标方格上， False 否则。
if game.is_solved():
print("Puzzle solved!")开发和测试
此项目使用 uv 用于包管理和 pytest 用于测试。
- 设置（使用uv）：
如果您计划贡献或运行测试，请设置虚拟环境并安装开发依赖项：
uv venv
source .venv/bin/activate
uv pip install -e .[dev] # Installs the package in editable mode along with dev dependencies like pytest- 运行测试：
导航到存储库的根目录并运行：
pytest原始数据集信息（引文）
如果您在工作中使用底层Boxoban级别数据集（游戏会根据此数据集的结构自动下载级别），请引用原始作者：
当地注释 puzzles/ 目录： 这 puzzles/ 此存储库中包含的目录仅供参考和历史使用。当发生以下情况时，游戏引擎现在会自动从在线源下载所需的谜题文件并将其缓存到系统上的临时目录中 load_game_from_params （或 load_game_from_file 如果文件不在缓存中）被调用。因此，当地 puzzles/ 目录不再被游戏逻辑用于加载级别，如果需要，可以从存储库的本地克隆中手动删除。
@misc{boxobanlevels,
author = {Arthur Guez and Mehdi Mirza and Karol Gregor and Rishabh Kabra and Sebastien Racaniere and Theophane Weber and David Raposo and Adam Santoro and Laurent Orseau and Tom Eccles and Greg Wayne and David Silver and Timothy Lillicrap and Victor Valdes},
title = {An investigation of Model-free planning: boxoban levels},
howpublished= {https://github.com/deepmind/boxoban-levels/},
year = "2018"
}关于数据集的问题可以直接联系Theophane Weber(theophane@google.com).
这不是Google的官方产品。
Boxoban MCP服务器
用于与Boxoban游戏交互的模型上下文协议（MCP）服务器可在 src/boxoban_mcp/server.py.
该服务器允许加载Boxoban谜题，并使用标准MCP工具与之交互。
运行服务器
要在本地运行MCP服务器：
python src/boxoban_mcp/server.py这将启动服务器，通常在 127.0.0.1:65432。然后，您可以使用MCP客户端或开发工具（如 mcp dev.
可用工具（部分列表）
load_game(difficulty: str, split: str, puzzle_set_num: int, puzzle_num: int)：加载特定游戏。get_game_state()：返回当前板状态。get_valid_moves()：列出有效的移动。take_action(action: str)：执行操作。take_action_list(actions: list[str])：执行一系列操作。return_full_game_state()：提供全面的游戏状态。
（注意：服务器实现中的工具名称可能略有不同。， get_full_game_state 为了 return_full_game_state。有关确切名称，请参阅服务器代码。）