PettingZoo自定义环境教程：动作掩码的实现与应用

环境概述

在PettingZoo多智能体强化学习框架中，动作掩码(Action Masking)是一种重要的机制，它允许我们动态地限制智能体在每个时间步可执行的动作范围。本文将通过一个逃脱游戏的案例，详细讲解如何在自定义环境中实现动作掩码功能。

环境设计

我们设计了一个8x8网格世界，包含三个关键角色：

1. 玩家(Player)：初始位置在(0,0)，目标是到达目标点
2. 追捕者(Chaser)：初始位置在(7,7)，目标是抓捕玩家
3. 目标点(Goal)：随机生成在(2,2)-(5,5)范围内

动作掩码实现原理

动作掩码本质上是一个二进制数组，其中每个元素对应一个动作，1表示允许执行该动作，0表示禁止。在我们的环境中：

• 玩家和追捕者都有4个动作：上、下、左、右
• 当智能体位于边界时，对应的移动动作会被禁止
• 追捕者不能直接移动到目标点所在的位置

掩码生成逻辑

# 玩家动作掩码示例
player_action_mask = np.ones(4, dtype=np.int8)
if self.player_x == 0:
    player_action_mask[0] = 0  # 禁止向左移动
elif self.player_x == 6:
    player_action_mask[1] = 0  # 禁止向右移动
if self.player_y == 0:
    player_action_mask[2] = 0  # 禁止向下移动
elif self.player_y == 6:
    player_action_mask[3] = 0  # 禁止向上移动

关键方法解析

1. 环境初始化

__init__方法定义了环境的基本属性，包括各角色的位置坐标和时间步计数器。注意这里我们遵循PettingZoo的最佳实践，不在初始化时直接定义动作和观察空间。

def __init__(self):
    self.goal_y = None
    self.goal_x = None
    self.chaser_y = None
    self.chaser_x = None
    self.player_y = None
    self.player_x = None
    self.timestep = None
    self.possible_agents = ["player", "chaser"]

2. 重置环境

reset方法不仅初始化环境状态，还返回包含初始观察和动作掩码的字典：

observations = {
    "player": {"observation": observation, "action_mask": [0, 1, 1, 0]},
    "chaser": {"observation": observation, "action_mask": [1, 0, 0, 1]},
}

3. 步进函数

step方法是环境的核心，它处理以下逻辑：

• 执行动作并更新位置
• 生成新的动作掩码
• 检查终止条件
• 计算奖励
• 返回新的观察和掩码

观察与动作空间

我们使用lru_cache装饰器缓存空间定义，提高性能：

@functools.lru_cache(maxsize=None)
def observation_space(self, agent):
    return MultiDiscrete([7 * 7 - 1] * 3)

@functools.lru_cache(maxsize=None)
def action_space(self, agent):
    return Discrete(4)

终止条件

环境定义了两种终止情况：

1. 玩家被追捕者捕获：玩家-1分，追捕者+1分
2. 玩家到达目标点：玩家+1分，追捕者-1分
3. 超过100步未分胜负：双方0分

实际应用价值

动作掩码在强化学习中具有重要作用：

1. 防止无效动作：避免智能体执行不可能的动作
2. 提高学习效率：减少探索空间，加速收敛
3. 实现复杂规则：可以编码各种游戏规则和限制条件

扩展思考

读者可以基于这个示例进行以下扩展：

1. 设计更复杂的掩码规则
2. 实现动态变化的掩码
3. 结合部分可观察性设计
4. 添加更多智能体和交互规则

通过本教程，我们展示了如何在PettingZoo中实现动作掩码功能，这为开发更复杂、更贴近实际的多智能体环境提供了基础。