Farama-Foundation/PettingZoo

Problem env.state() represents the global state of an environment, but PettingZoo's state validation and guidance assume that the returned value is a NumPy array. A custom environment may instead have a structured global state, such as a dictionary represented by gymnasium.spaces.Dict. This is the implementation follow-up to #1326. Work Make the documented contract for state() and state_space accept a value described by any appropriate gymnasium.spaces.Space, including Dict, rather than requiring an ndarray. Update pettingzoo/test/state_test.py so it validates state_space.contains(state) throughout a rollout for both AEC and Parallel environments. Apply array-specific checks only when the state is an ndarray; do not stop testing when it is another type. Review the relevant API type annotations and utilities for assumptions that state() always returns an ndarray, and update those assumptions where they are part of PettingZoo's public API. Document a small custom-environment example wit

Porting observation and action wrappers alone will not let PettingZoo retire SuperSuit. Its maintained training tutorials use SuperSuit’s vectorization and Stable-Baselines3 adapters, including the workflow built around pettingzoo_env_to_vec_env_v1, concat_vec_envs_v1, and stable_baselines3_vec_env_v0. Inventory each SuperSuit vector constructor or adapter used in PettingZoo’s maintained examples. For each workflow, select an actively maintained replacement API, or implement the missing bridge in an appropriate maintained package. These functions do not become AEC or Parallel environment wrappers merely by moving them into pettingzoo.wrappers; document where the replacement lives and why. Migrate the affected SB3 and other training examples to the replacement. Preserve their ability to train with the expected observation/action spaces and agent counts, including the KAZ example that also requires black-death behavior. Document an old-to-new mapping for each SuperSuit vector functio

After the replacement wrappers and vector workflow are available, update PettingZoo’s maintained documentation and tutorials so they no longer instruct users to install or import SuperSuit. This is part of completing #1365. Inventory supersuit/SuperSuit references in documentation, tutorials, tutorial requirements, and documentation build configuration. Replace executable preprocessing examples with the corresponding PettingZoo wrapper classes. Update the SuperSuit wrapper reference page and navigation to describe the native API and old-to-new name mappings. Update the Atari preprocessing examples and the CleanRL, AgileRL, Ray, and SB3 tutorials where they currently import SuperSuit. Preserve explanations and working examples. Remove a tutorial’s SuperSuit requirement only after its code has a working replacement. If an example needs the vectorization work tracked separately under #1365, complete that replacement before changing the example. Completion: Maintained PettingZoo exampl

Issue #1365 calls for SuperSuit’s environment-wrapper functionality to live under pettingzoo.wrappers, similar to gymnasium.wrappers. The migrated classes currently appear in pettingzoo.utils.wrappers. Provide the requested public pettingzoo.wrappers import path. Re-export the native environment wrappers from this namespace, including those already merged and those added through #1365. Keep existing pettingzoo.utils.wrappers imports working. Define an explicit __all__ and document which classes apply to AEC environments and which apply to Parallel environments. This issue concerns the public namespace and exports; it does not require moving every implementation file. Completion: Users can import the migrated classes from pettingzoo.wrappers; existing imports still work; import tests and the wrapper reference documentation cover the public path. Coordinate the export list with the wrapper PRs as they merge.

PettingZoo already has an AEC ClipOutOfBoundsWrapper. Add its native Parallel counterpart under pettingzoo.utils.wrappers as part of #1365. Do not create a second AEC action-clipping class. For each active agent with a Box action space, clip the supplied action elementwise to that agent’s own low and high bounds before forwarding the action dictionary. Leave in-range actions unchanged. Validate action shapes and reject NaNs, matching the existing AEC wrapper’s safety behavior. Warn when an out-of-range action is clipped, as the existing AEC class does. Preserve the action spaces. This deliberately follows PettingZoo’s existing AEC clipping behavior. SuperSuit’s clip_actions_v0 calls np.clip without the same warnings and NaN check; document the difference so users migrating from SuperSuit know what to expect. Completion: Export and document the Parallel class beside ClipOutOfBoundsWrapper. Test agents with different Box bounds, in-range and out-of-range actions, warning behavior