Examples: maze

Procedural maze level generator example.

This module demonstrates building a parameterized maze-based level using the GridState editing API and factory helpers, then converting to an immutable State suitable for simulation or Gym-style environments.

Design Goals

• Showcase composition of factories (agent, walls, doors, portals, hazards, power-ups, enemies) with reference wiring (e.g., portal pairing, enemy pathfinding target reference to the agent) that are resolved during to_state conversion.
• Provide tunable difficulty levers: wall density, counts of required objectives, rewards, hazards, enemies, doors, portals and power-ups.
• Illustrate how movement styles (static, directional patrol, straight-line pathfinding, full pathfinding) can be expressed via component choices.

Usage Example

from grid_universe.examples import maze
state = maze.generate(width=20, height=20, seed=123)

# Render / step the state using the engine's systems or gym wrapper.

Key Concepts Illustrated

Required Items: Use cores flagged as required=True which the default objective logic expects to be collected before reaching the exit. Power-Ups: Effects created with optional time or usage limits (speed, immunity, phasing) acting as pickups. Enemies: Configurable movement style and lethality; pathfinding enemies reference the agent to resolve target entity IDs later. Essential Path: Minimal union of shortest paths that touch required items and exit. Other entities (hazards, enemies, boxes) prefer non-essential cells.

generate(width, height, num_required_items=1, num_rewardable_items=1, num_portals=1, num_doors=1, health=5, movement_cost=1, required_item_reward=10, rewardable_item_reward=10, boxes=DEFAULT_BOXES, powerups=DEFAULT_POWERUPS, hazards=DEFAULT_HAZARDS, enemies=DEFAULT_ENEMIES, wall_percentage=0.8, movement=CardinalMovement(), objective=CollectAndExitObjective(), seed=None, turn_limit=None)

Generate a randomized maze game state.

This function orchestrates maze carving, tile classification, entity placement and reference wiring before producing the immutable simulation State.

Parameters:

Name	Type	Description	Default
width	int	Width of the maze grid.	required
height	int	Height of the maze grid.	required
num_required_items	int	Number of required cores that must be collected before exit.	1
num_rewardable_items	int	Number of optional reward coins.	1
num_portals	int	Number of portal pairs to place (each pair consumes two open cells).	1
num_doors	int	Number of door/key pairs; each door is locked by its matching key.	1
health	int	Initial agent health points.	5
movement_cost	int	Per-tile movement cost encoded in floor components.	1
required_item_reward	int	Reward granted for collecting each required item.	10
rewardable_item_reward	int	Reward granted for each optional reward item (coin).	10
boxes	List[BoxSpec]	List defining (pushable?, speed) for box entities; speed > 0 creates moving boxes.	DEFAULT_BOXES
powerups	List[PowerupSpec]	Effect specifications converted into pickup entities.	DEFAULT_POWERUPS
hazards	List[HazardSpec]	Hazard specifications (appearance, damage, lethal).	DEFAULT_HAZARDS
enemies	List[EnemySpec]	Enemy specifications (damage, lethal, movement type, speed).	DEFAULT_ENEMIES
wall_percentage	float	Fraction of original maze walls to retain (0.0 => open field, 1.0 => perfect maze).	0.8
movement	BaseMovement	Movement system configuration for the level.	CardinalMovement()
objective	BaseObjective	Win condition configuration for the level.	CollectAndExitObjective()
seed	int | None	RNG seed for deterministic generation.	None

Returns:

Name	Type	Description
State	State	Fully wired immutable state ready for simulation.