Modernize MAgent2 for Python 3.10-3.12 (v0.4.0)

- Fix c_lib.py: replace hardcoded venv path with automatic library discovery
- Fix CMakeLists.txt: separate MSVC/GCC flags, use CMAKE_CXX_STANDARD
- Fix setup.py: remove deprecated self.debug, unify cross-platform cmake build
- Fix Range.h: sizeof(bool) -> sizeof(int) in copy constructor (data corruption bug)
- Fix C++ headers: tgmath.h -> cmath, stdlib.h -> cstdlib, assert.h -> cassert
- Fix magent_env.py: update deprecated seeding.np_random() API
- Update pyproject.toml: Python >=3.10, remove numpy <2.0 upper bound
- Update CI: Python 3.10-3.12 matrix, upgrade actions to v4/v5
- Update pre-commit: pyupgrade --py310-plus
- Update README and docs with modern usage examples
- Add battle_demo.py and battle_video.py examples
- Bump version to 0.4.0

Tested with Python 3.11, numpy 2.3, gymnasium 1.2.3, pettingzoo 1.25, pygame 2.6.1

Fixes Farama-Foundation#63, Farama-Foundation#59, Farama-Foundation#57, Farama-Foundation#54, Farama-Foundation#53

Author: hxypqr

.github/workflows/build-publish.yml

@@ -20,60 +20,62 @@ jobs:
     strategy:
       matrix:
         include:
-        - os: ubuntu-22.04
-          python: 38
-          platform: manylinux_x86_64
-        - os: ubuntu-22.04
-          python: 39
-          platform: manylinux_x86_64
         - os: ubuntu-22.04
           python: 310
           platform: manylinux_x86_64
         - os: ubuntu-22.04
           python: 311
           platform: manylinux_x86_64
+        - os: ubuntu-22.04
+          python: 312
+          platform: manylinux_x86_64
 
     steps:
     - uses: actions/checkout@v4
     - name: Build wheels
-      uses: pypa/cibuildwheel@v2.19.2
+      uses: pypa/cibuildwheel@v2.22.0
       env:
         CIBW_BUILD: cp${{ matrix.python }}-${{ matrix.platform }}
         CIBW_ARCHS: auto
         CIBW_BUILD_VERBOSITY: 1
 
     - name: Store wheels
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
+        name: wheels-linux-${{ matrix.python }}
         path: ./wheelhouse/*.whl
 
   build-src:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
     - name: Build src
       run: |
-        python -m pip install --upgrade pip
-        pip install wheel
-        python setup.py sdist
+        python -m pip install --upgrade pip build
+        python -m build --sdist
     - name: Store src
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
+        name: sdist
         path: dist/*.tar.gz
 
   build-wheels-ms:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: [ '3.8', '3.9', '3.10', '3.11' ]
+        python-version: [ '3.10', '3.11', '3.12' ]
         include:
         - os: windows-latest
 
     steps:
     - uses: actions/checkout@v4
 
     - name: Set up Python
-      uses: actions/setup-python@v3
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
         architecture: x64
@@ -87,8 +89,9 @@ jobs:
         pip install wheel cmake-build-extension
         pip wheel .  --no-deps -w wheelhouse/
 
-    - uses: actions/upload-artifact@v3
+    - uses: actions/upload-artifact@v4
       with:
+        name: wheels-windows-${{ matrix.python-version }}
         path: ./wheelhouse/*.whl
 
   publish:
@@ -100,10 +103,10 @@ jobs:
     if: github.event_name == 'release' && github.event.action == 'published'
     steps:
     - name: Download dists
-      uses: actions/download-artifact@v3
+      uses: actions/download-artifact@v4
       with:
-        name: artifact
         path: dist
+        merge-multiple: true
     - name: Publish
       uses: pypa/gh-action-pypi-publish@release/v1
       with:

.gitignore

@@ -22,4 +22,13 @@ docs/environments/*.md
 Parallel_Demo.py
 
 # Environments
-.venv
+.venv
+
+# Build artifacts
+*.pyd
+*.egg-info/
+_frames/
+.pytest_cache/
+
+# Demo outputs
+battle_video.mp4

.pre-commit-config.yaml

@@ -38,7 +38,7 @@ repos:
     rev: v3.3.2
     hooks:
       - id: pyupgrade
-        args: ["--py37-plus"]
+        args: ["--py310-plus"]
   - repo: https://github.com/PyCQA/isort
     rev: 5.12.0
     hooks:

CMakeLists.txt

@@ -4,17 +4,21 @@ project(magent)
 
 set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake ${CMAKE_MODULE_PATH})
 
+# Use CMake's standard mechanism instead of -std=c++11
+set(CMAKE_CXX_STANDARD 11)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
 file(GLOB autopilot_sources src/*.cc src/gridworld/*.cc src/utility/*.cc)
 set(LIB_SRC_FILES ${autopilot_sources})
 
-
-set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -g -Wall -std=c++11 -O3")
-IF (WIN32)
-  set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /W0 /wd4711 /wd4710")
-ELSE()
-  set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-unused-variable -Wno-reorder -Wno-sign-compare -Wno-missing-braces")
-ENDIF()
-set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DDEBUG")
+if(MSVC)
+  add_compile_options(/W0 /wd4711 /wd4710)
+  add_compile_definitions(DEBUG)
+else()
+  add_compile_options(-g -Wall -O3
+    -Wno-unused-variable -Wno-reorder -Wno-sign-compare -Wno-missing-braces)
+  add_compile_definitions(DEBUG)
+endif()
 
 # runtime library
 add_library(magent SHARED ${LIB_SRC_FILES})

README.md

@@ -11,11 +11,98 @@ MAgent2 is a library for the creation of environments where large numbers of pix
 MAgent2 is a maintained fork of the original [MAgent](https://github.com/geek-ai/MAgent) codebase. It contains some [reference environments](https://github.com/Farama-Foundation/MAgent2/tree/main/magent2/environments) implemented using the [PettingZoo](https://github.com/Farama-Foundation/PettingZoo) API. These environments used to be included in PettingZoo itself, but have been moved here to exist independently. They are being regularly maintained and will receive bug fixes, support new versions of Python, etc. Development used to take place at [github.com/Farama-Foundation/MAgent](https://github.com/Farama-Foundation/MAgent) but was moved to [github.com/Farama-Foundation/MAgent2](https://github.com/Farama-Foundation/MAgent2) so that the distinction from the original MAgent library is clear to users.
 
 ## Installation
-Install using pip: `pip install magent2`. See [docs](https://magent2.farama.org/) for usage information.
 
+Install using pip:
+```bash
+pip install magent2
+```
+
+See [docs](https://magent2.farama.org/) for usage information.
+
+### Build from source
+
+MAgent2 includes a C++ native extension that requires CMake to build:
+
+```bash
+# Prerequisites: Python 3.10+, CMake, C++ compiler (GCC/Clang on Linux, MSVC on Windows)
+git clone https://github.com/Farama-Foundation/MAgent2.git
+cd MAgent2
+pip install -e .
+```
 
 ## Requirements
-MAgent2 supports Linux and macOS and Python 3.8+.
+
+- Python 3.10+
+- Linux or Windows
+- Dependencies (installed automatically):
+  - `numpy >= 1.21.0`
+  - `pygame >= 2.1.0`
+  - `pettingzoo >= 1.23.1` (which pulls in `gymnasium`)
+
+### Tested with
+
+| Package | Version |
+|---------|---------|
+| Python | 3.11 |
+| numpy | 2.3.x |
+| gymnasium | 1.2.3 |
+| pettingzoo | 1.25.0 |
+| pygame | 2.6.1 |
+
+## Quick Start
+
+### AEC API (agents take turns)
+
+```python
+from magent2.environments import battle_v4
+
+env = battle_v4.env(map_size=45, max_cycles=300)
+env.reset()
+
+for agent in env.agent_iter():
+    observation, reward, termination, truncation, info = env.last()
+    if termination or truncation:
+        action = None
+    else:
+        action = env.action_space(agent).sample()  # random policy
+    env.step(action)
+
+env.close()
+```
+
+### Parallel API (all agents act simultaneously, faster)
+
+```python
+from magent2.environments.battle.battle import parallel_env
+
+env = parallel_env(map_size=45, max_cycles=300)
+observations, infos = env.reset()
+
+while env.agents:
+    actions = {agent: env.action_space(agent).sample() for agent in env.agents}
+    observations, rewards, terminations, truncations, infos = env.step(actions)
+
+env.close()
+```
+
+### Generate a battle video (requires ffmpeg)
+
+```python
+python battle_video.py
+```
+
+This renders each frame as a grid image (red = red team, blue = blue team) and encodes them into an MP4 video using ffmpeg. See `battle_video.py` for the full implementation.
+
+## Available Environments
+
+| Environment | Agents | Description |
+|-------------|--------|-------------|
+| `battle_v4` | 162 | Two teams battle on a 45x45 grid |
+| `adversarial_pursuit_v4` | 75 | Predators chase prey agents |
+| `battlefield_v5` | 162 | Large battlefield with obstacles |
+| `combined_arms_v6` | 162 | Two unit types per team (melee + ranged) |
+| `gather_v5` | 495 | Agents gather food while avoiding predators |
+| `tiger_deer_v4` | 121 | Tigers hunt deer |
 
 ## References
 ```

battle_demo.py

@@ -0,0 +1,66 @@
+"""MAgent2 Battle 环境演示脚本
+
+两队智能体（红队 red vs 蓝队 blue）在 45x45 网格上进行团战。
+使用随机策略运行，输出每步的存活数量和最终结果。
+"""
+
+from magent2.environments import battle_v4
+
+
+def run_battle_demo():
+    # 创建环境 (AEC 模式，即逐个智能体轮流行动)
+    env = battle_v4.env(map_size=45, max_cycles=300)
+    env.reset()
+
+    red_alive = 0
+    blue_alive = 0
+    step_count = 0
+
+    # 统计初始数量
+    for agent in env.agents:
+        if agent.startswith("red"):
+            red_alive += 1
+        else:
+            blue_alive += 1
+    print(f"=== MAgent2 Battle Demo ===")
+    print(f"Initial: red={red_alive}, blue={blue_alive}, total={red_alive + blue_alive}")
+    print()
+
+    # 主循环：逐个智能体行动
+    for agent in env.agent_iter():
+        observation, reward, termination, truncation, info = env.last()
+
+        if termination or truncation:
+            action = None  # 已死亡或截断的智能体不行动
+        else:
+            # 随机选择一个合法动作
+            action = env.action_space(agent).sample()
+
+        env.step(action)
+        step_count += 1
+
+        # 每 1000 步打印一次状态
+        if step_count % 1000 == 0:
+            red = sum(1 for a in env.agents if a.startswith("red"))
+            blue = sum(1 for a in env.agents if a.startswith("blue"))
+            print(f"  step {step_count:>6d}: red={red:>3d}, blue={blue:>3d}")
+
+    # 最终结果
+    red_final = sum(1 for a in env.agents if a.startswith("red"))
+    blue_final = sum(1 for a in env.agents if a.startswith("blue"))
+    print()
+    print(f"=== Battle Finished ===")
+    print(f"Total steps: {step_count}")
+    print(f"Survivors: red={red_final}, blue={blue_final}")
+    if red_final > blue_final:
+        print("Result: Red team wins!")
+    elif blue_final > red_final:
+        print("Result: Blue team wins!")
+    else:
+        print("Result: Draw!")
+
+    env.close()
+
+
+if __name__ == "__main__":
+    run_battle_demo()