zombie-escape 1.1.4__tar.gz → 1.2.1__tar.gz

{zombie_escape-1.1.4 → zombie_escape-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zombie-escape
-Version: 1.1.4
+Version: 1.2.1
 Summary: Top-down zombie survival game built with pygame.
 Project-URL: Homepage, https://github.com/tos-kamiya/zombie-escape
 Author-email: Toshihiro Kamiya <kamiya@mbj.nifty.com>
@@ -65,29 +65,29 @@ Open **Settings** from the title to toggle gameplay assists:
 
 At the title screen you can pick a stage:
 
-- **Stage 1: Find the Car** — locate the car and drive out.
-- **Stage 2: Fuel Run** — find a fuel can first, pick it up, then find the car and escape.
-- **Stage 3: Rescue Buddy** — find your stranded buddy, grab fuel, pick them up with the car, then escape together.
-- **Stage 4: Evacuate Survivors** — find the car, gather nearby civilians, and escape before zombies reach them.
+- **Stage 1: Find the Car** — locate the car and drive out (you already start with fuel).
+- **Stage 2: Fuel Run** — you start with no fuel; find a fuel can first, pick it up, then find the car and escape.
+- **Stage 3: Rescue Buddy** — same fuel hunt as Stage 2 (you begin empty) plus grab your buddy, pick them up with the car, then escape together.
+- **Stage 4: Evacuate Survivors** — start fueled, find the car, gather nearby civilians, and escape before zombies reach them. Stage 4 sprinkles extra parked cars across the map; slamming into one while already driving fully repairs your current ride and adds five more safe seats.
 
 An objective reminder is shown at the top-left during play.
 
 ### Characters/Items
 
--   **Player:** A blue circle. Controlled with the WASD or arrow keys.
+-   **Player:** A blue circle. Controlled with the WASD or arrow keys. When carrying fuel a tiny yellow square appears near the sprite so you can immediately see whether you're ready to drive.
 -   **Zombie:** A red circle. Will chase the player (or car) once detected.
     -   When out of sight, the zombie's movement mode will randomly switch every certain time (moving horizontally/vertically only, side-to-side movement, random movement, etc.).
 -   **Car:** A yellow rectangle. The player can enter by making contact with it.
     -   The car has durability. Durability decreases when colliding with internal walls or hitting zombies.
-    -   If durability reaches 0, the car is destroyed, and the player is ejected.
-    -   When the car is destroyed, a **new car will respawn** at a random location within the stage.
-    -   After roughly 5 minutes of play, a small triangle near the player points toward the objective: fuel first (Stage 2 before pickup), car after fuel is collected (Stage 2), or car directly (Stage 1).
+    -   If durability reaches 0, the car is destroyed and you are dumped on foot; you must track down another parked car hidden in the level.
+    -   When you're already driving, ramming a parked car instantly restores your current car's health. On Stage 4 this also increases the safe passenger limit by five.
+    -   After roughly 5 minutes of play, a small triangle near the player points toward the objective: fuel first (Stage 2 before pickup), car after fuel is collected (Stage 2/3), or car directly (Stage 1/4).
 -   **Walls:** Outer walls are gray; inner walls are beige.
     -   **Outer Walls:** Walls surrounding the stage that are nearly indestructible. Each side has at least three openings (exits).
     -   **Inner Walls:** Beige walls randomly placed inside the building. Inner wall segments each have durability. **The player can break these walls** by repeatedly colliding with a segment to reduce its durability; when it reaches 0, the segment is destroyed and disappears. The car cannot break walls.
 -   **Flashlight:** Picking one up boosts your visible radius by 35%.
 -   **Steel Beam (optional):** A square post with crossed diagonals; same collision as inner walls but with triple durability. Spawns independently of inner walls (may overlap them). If an inner wall covers a beam, the beam appears once the wall is destroyed.
--   **Fuel Can (Stage 2):** A yellow jerrycan. Pick it up before driving the car.
+-   **Fuel Can (Stages 2 & 3):** A yellow jerrycan that only spawns on the fuel-run stages. Pick it up before driving the car; once collected the on-player indicator appears until you refuel the car.
 -   **Buddy (Stage 3):** A green circle survivor who spawns somewhere in the building and waits.
     -   Zombies only choose to pursue the buddy if they are on-screen; otherwise they ignore them.
     -   If a zombie tags the buddy off-screen, the buddy quietly respawns somewhere else instead of ending the run.
@@ -95,7 +95,7 @@ An objective reminder is shown at the top-left during play.
 -   **Survivors (Stage 4):** Light blue civilians scattered indoors.
     - They stand still until you get close, then shuffle toward you at about one-third of player speed.
     - Zombies can convert them if both are on-screen; the survivor shouts a line and turns instantly.
-    - They only board the car; up to five ride safely, each slowing the car. Going over the limit damages the car and ejects everyone back into the building.
+    - They only board the car; your safe capacity starts at five but grows by five each time you sideswipe a parked car while already driving. Speed loss is based on how full the car is relative to that capacity, so extra slots mean quicker getaways.
 
 ### Win/Lose Conditions
 

{zombie_escape-1.1.4 → zombie_escape-1.2.1}/README.md

@@ -44,29 +44,29 @@ Open **Settings** from the title to toggle gameplay assists:
 
 At the title screen you can pick a stage:
 
-- **Stage 1: Find the Car** — locate the car and drive out.
-- **Stage 2: Fuel Run** — find a fuel can first, pick it up, then find the car and escape.
-- **Stage 3: Rescue Buddy** — find your stranded buddy, grab fuel, pick them up with the car, then escape together.
-- **Stage 4: Evacuate Survivors** — find the car, gather nearby civilians, and escape before zombies reach them.
+- **Stage 1: Find the Car** — locate the car and drive out (you already start with fuel).
+- **Stage 2: Fuel Run** — you start with no fuel; find a fuel can first, pick it up, then find the car and escape.
+- **Stage 3: Rescue Buddy** — same fuel hunt as Stage 2 (you begin empty) plus grab your buddy, pick them up with the car, then escape together.
+- **Stage 4: Evacuate Survivors** — start fueled, find the car, gather nearby civilians, and escape before zombies reach them. Stage 4 sprinkles extra parked cars across the map; slamming into one while already driving fully repairs your current ride and adds five more safe seats.
 
 An objective reminder is shown at the top-left during play.
 
 ### Characters/Items
 
--   **Player:** A blue circle. Controlled with the WASD or arrow keys.
+-   **Player:** A blue circle. Controlled with the WASD or arrow keys. When carrying fuel a tiny yellow square appears near the sprite so you can immediately see whether you're ready to drive.
 -   **Zombie:** A red circle. Will chase the player (or car) once detected.
     -   When out of sight, the zombie's movement mode will randomly switch every certain time (moving horizontally/vertically only, side-to-side movement, random movement, etc.).
 -   **Car:** A yellow rectangle. The player can enter by making contact with it.
     -   The car has durability. Durability decreases when colliding with internal walls or hitting zombies.
-    -   If durability reaches 0, the car is destroyed, and the player is ejected.
-    -   When the car is destroyed, a **new car will respawn** at a random location within the stage.
-    -   After roughly 5 minutes of play, a small triangle near the player points toward the objective: fuel first (Stage 2 before pickup), car after fuel is collected (Stage 2), or car directly (Stage 1).
+    -   If durability reaches 0, the car is destroyed and you are dumped on foot; you must track down another parked car hidden in the level.
+    -   When you're already driving, ramming a parked car instantly restores your current car's health. On Stage 4 this also increases the safe passenger limit by five.
+    -   After roughly 5 minutes of play, a small triangle near the player points toward the objective: fuel first (Stage 2 before pickup), car after fuel is collected (Stage 2/3), or car directly (Stage 1/4).
 -   **Walls:** Outer walls are gray; inner walls are beige.
     -   **Outer Walls:** Walls surrounding the stage that are nearly indestructible. Each side has at least three openings (exits).
     -   **Inner Walls:** Beige walls randomly placed inside the building. Inner wall segments each have durability. **The player can break these walls** by repeatedly colliding with a segment to reduce its durability; when it reaches 0, the segment is destroyed and disappears. The car cannot break walls.
 -   **Flashlight:** Picking one up boosts your visible radius by 35%.
 -   **Steel Beam (optional):** A square post with crossed diagonals; same collision as inner walls but with triple durability. Spawns independently of inner walls (may overlap them). If an inner wall covers a beam, the beam appears once the wall is destroyed.
--   **Fuel Can (Stage 2):** A yellow jerrycan. Pick it up before driving the car.
+-   **Fuel Can (Stages 2 & 3):** A yellow jerrycan that only spawns on the fuel-run stages. Pick it up before driving the car; once collected the on-player indicator appears until you refuel the car.
 -   **Buddy (Stage 3):** A green circle survivor who spawns somewhere in the building and waits.
     -   Zombies only choose to pursue the buddy if they are on-screen; otherwise they ignore them.
     -   If a zombie tags the buddy off-screen, the buddy quietly respawns somewhere else instead of ending the run.
@@ -74,7 +74,7 @@ An objective reminder is shown at the top-left during play.
 -   **Survivors (Stage 4):** Light blue civilians scattered indoors.
     - They stand still until you get close, then shuffle toward you at about one-third of player speed.
     - Zombies can convert them if both are on-screen; the survivor shouts a line and turns instantly.
-    - They only board the car; up to five ride safely, each slowing the car. Going over the limit damages the car and ejects everyone back into the building.
+    - They only board the car; your safe capacity starts at five but grows by five each time you sideswipe a parked car while already driving. Speed loss is based on how full the car is relative to that capacity, so extra slots mean quicker getaways.
 
 ### Win/Lose Conditions
 

{zombie_escape-1.1.4 → zombie_escape-1.2.1}/src/zombie_escape/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2025-present Toshihiro Kamiya <kamiya@mbj.nifty.com>
 #
 # SPDX-License-Identifier: MIT
-__version__ = "1.1.4"
+__version__ = "1.2.1"

{zombie_escape-1.1.4 → zombie_escape-1.2.1}/src/zombie_escape/constants.py

@@ -44,7 +44,7 @@ SURVIVOR_APPROACH_RADIUS = 48
 SURVIVOR_APPROACH_SPEED = PLAYER_SPEED * 0.35
 SURVIVOR_SPAWN_RATE = 0.07
 SURVIVOR_MAX_SAFE_PASSENGERS = 5
-SURVIVOR_SPEED_PENALTY_PER_PASSENGER = 0.104
+SURVIVOR_SPEED_PENALTY_PER_PASSENGER = 0.08
 SURVIVOR_MIN_SPEED_FACTOR = 0.35
 SURVIVOR_OVERLOAD_DAMAGE_RATIO = 0.2
 SURVIVOR_MESSAGE_DURATION_MS = 2000
@@ -53,6 +53,7 @@ SURVIVOR_CONVERSION_LINE_KEYS = [
     "stages.stage4.conversion_lines.line2",
     "stages.stage4.conversion_lines.line3",
 ]
+SURVIVOR_STAGE_WAITING_CAR_COUNT = 2
 
 # --- Flashlight settings ---
 DEFAULT_FLASHLIGHT_BONUS_SCALE = float(
@@ -83,7 +84,7 @@ ZOMBIE_INTERIOR_SPAWN_RATE = 0.015
 ZOMBIE_SPAWN_PLAYER_BUFFER = 140
 ZOMBIE_MODE_CHANGE_INTERVAL_MS = 5000
 ZOMBIE_SIGHT_RANGE = FOV_RADIUS * 2.0
-FAST_ZOMBIE_BASE_SPEED = PLAYER_SPEED * 0.81
+FAST_ZOMBIE_BASE_SPEED = PLAYER_SPEED * 0.77
 FAST_ZOMBIE_SPEED_JITTER = 0.075
 ZOMBIE_SEPARATION_DISTANCE = ZOMBIE_RADIUS * 2.2
 
@@ -170,6 +171,7 @@ __all__ = [
     "SURVIVOR_OVERLOAD_DAMAGE_RATIO",
     "SURVIVOR_MESSAGE_DURATION_MS",
     "SURVIVOR_CONVERSION_LINE_KEYS",
+    "SURVIVOR_STAGE_WAITING_CAR_COUNT",
     "DEFAULT_FLASHLIGHT_BONUS_SCALE",
     "FLASHLIGHT_WIDTH",
     "FLASHLIGHT_HEIGHT",

{zombie_escape-1.1.4 → zombie_escape-1.2.1}/src/zombie_escape/gameplay/logic.py

@@ -45,6 +45,7 @@ from ..constants import (
     SURVIVOR_RADIUS,
     SURVIVOR_SPAWN_RATE,
     SURVIVOR_SPEED_PENALTY_PER_PASSENGER,
+    SURVIVOR_STAGE_WAITING_CAR_COUNT,
     ZOMBIE_INTERIOR_SPAWN_RATE,
     ZOMBIE_RADIUS,
     ZOMBIE_SEPARATION_DISTANCE,
@@ -68,6 +69,8 @@ from ..entities import (
     Zombie,
 )
 
+LOGICAL_SCREEN_RECT = pygame.Rect(0, 0, SCREEN_WIDTH, SCREEN_HEIGHT)
+
 __all__ = [
     "create_zombie",
     "rect_for_cell",
@@ -80,8 +83,14 @@ __all__ = [
     "scatter_positions_on_walkable",
     "spawn_survivors",
     "update_survivors",
+    "alive_waiting_cars",
+    "log_waiting_car_count",
+    "nearest_waiting_car",
     "calculate_car_speed_for_passengers",
     "apply_passenger_speed_penalty",
+    "waiting_car_target_count",
+    "spawn_waiting_car",
+    "maintain_waiting_car_supply",
     "add_survivor_message",
     "random_survivor_conversion_line",
     "cleanup_survivor_messages",
@@ -91,7 +100,7 @@ __all__ = [
     "get_shrunk_sprite",
     "update_footprints",
     "initialize_game_state",
-    "setup_player_and_car",
+    "setup_player_and_cars",
     "spawn_initial_zombies",
     "process_player_input",
     "update_entities",
@@ -246,6 +255,8 @@ def place_new_car(
     wall_group: pygame.sprite.Group,
     player: Player,
     walkable_cells: list[pygame.Rect],
+    *,
+    existing_cars: Sequence[Car] | None = None,
 ) -> Car | None:
     if not walkable_cells:
         return None
@@ -268,13 +279,23 @@ def place_new_car(
             temp_car, nearby_walls, collided=lambda s1, s2: s1.rect.colliderect(s2.rect)
         )
         collides_player = temp_rect.colliderect(player.rect.inflate(50, 50))
-        if not collides_wall and not collides_player:
+        car_overlap = False
+        if existing_cars:
+            car_overlap = any(
+                temp_car.rect.colliderect(other.rect)
+                for other in existing_cars
+                if other and other.alive()
+            )
+        if not collides_wall and not collides_player and not car_overlap:
             return temp_car
     return None
 
 
 def place_fuel_can(
-    walkable_cells: list[pygame.Rect], player: Player, *, car: Car | None = None
+    walkable_cells: list[pygame.Rect],
+    player: Player,
+    *,
+    cars: Sequence[Car] | None = None,
 ) -> FuelCan | None:
     """Pick a spawn spot for the fuel can away from the player (and car if given)."""
     if not walkable_cells:
@@ -290,14 +311,17 @@ def place_fuel_can(
             < min_player_dist
         ):
             continue
-        if (
-            car
-            and math.hypot(
-                cell.centerx - car.rect.centerx, cell.centery - car.rect.centery
-            )
-            < min_car_dist
-        ):
-            continue
+        if cars:
+            too_close = False
+            for parked_car in cars:
+                if math.hypot(
+                    cell.centerx - parked_car.rect.centerx,
+                    cell.centery - parked_car.rect.centery,
+                ) < min_car_dist:
+                    too_close = True
+                    break
+            if too_close:
+                continue
         return FuelCan(cell.centerx, cell.centery)
 
     # Fallback: drop near a random walkable cell
@@ -306,7 +330,10 @@ def place_fuel_can(
 
 
 def place_flashlight(
-    walkable_cells: list[pygame.Rect], player: Player, *, car: Car | None = None
+    walkable_cells: list[pygame.Rect],
+    player: Player,
+    *,
+    cars: Sequence[Car] | None = None,
 ) -> Flashlight | None:
     """Pick a spawn spot for the flashlight away from the player (and car if given)."""
     if not walkable_cells:
@@ -322,14 +349,16 @@ def place_flashlight(
             < min_player_dist
         ):
             continue
-        if (
-            car
-            and math.hypot(
-                cell.centerx - car.rect.centerx, cell.centery - car.rect.centery
-            )
-            < min_car_dist
-        ):
-            continue
+        if cars:
+            if any(
+                math.hypot(
+                    cell.centerx - parked.rect.centerx,
+                    cell.centery - parked.rect.centery,
+                )
+                < min_car_dist
+                for parked in cars
+            ):
+                continue
         return Flashlight(cell.centerx, cell.centery)
 
     cell = random.choice(walkable_cells)
@@ -340,7 +369,7 @@ def place_flashlights(
     walkable_cells: list[pygame.Rect],
     player: Player,
     *,
-    car: Car | None = None,
+    cars: Sequence[Car] | None = None,
     count: int = DEFAULT_FLASHLIGHT_SPAWN_COUNT,
 ) -> list[Flashlight]:
     """Spawn multiple flashlights using the single-place helper to spread them out."""
@@ -349,7 +378,7 @@ def place_flashlights(
     max_attempts = max(200, count * 80)
     while len(placed) < count and attempts < max_attempts:
         attempts += 1
-        fl = place_flashlight(walkable_cells, player, car=car)
+        fl = place_flashlight(walkable_cells, player, cars=cars)
         if not fl:
             break
         # Avoid clustering too tightly
@@ -367,7 +396,10 @@ def place_flashlights(
 
 
 def place_companion(
-    walkable_cells: list[pygame.Rect], player: Player, *, car: Car | None = None
+    walkable_cells: list[pygame.Rect],
+    player: Player,
+    *,
+    cars: Sequence[Car] | None = None,
 ) -> Companion | None:
     """Spawn the stranded buddy somewhere on a walkable tile away from the player and car."""
     if not walkable_cells:
@@ -383,14 +415,16 @@ def place_companion(
             < min_player_dist
         ):
             continue
-        if (
-            car
-            and math.hypot(
-                cell.centerx - car.rect.centerx, cell.centery - car.rect.centery
-            )
-            < min_car_dist
-        ):
-            continue
+        if cars:
+            if any(
+                math.hypot(
+                    cell.centerx - parked.rect.centerx,
+                    cell.centery - parked.rect.centery,
+                )
+                < min_car_dist
+                for parked in cars
+            ):
+                continue
         return Companion(cell.centerx, cell.centery)
 
     cell = random.choice(walkable_cells)
@@ -508,8 +542,12 @@ def update_survivors(game_data: GameData) -> None:
                 other.rect.center = (int(other.x), int(other.y))
 
 
-def calculate_car_speed_for_passengers(passengers: int) -> float:
-    penalty = SURVIVOR_SPEED_PENALTY_PER_PASSENGER * passengers
+def calculate_car_speed_for_passengers(
+    passengers: int, *, capacity: int = SURVIVOR_MAX_SAFE_PASSENGERS
+) -> float:
+    cap = max(1, capacity)
+    load_ratio = max(0.0, passengers / cap)
+    penalty = SURVIVOR_SPEED_PENALTY_PER_PASSENGER * load_ratio
     penalty = min(0.95, max(0.0, penalty))
     adjusted = CAR_SPEED * (1 - penalty)
     return max(CAR_SPEED * SURVIVOR_MIN_SPEED_FACTOR, adjusted)
@@ -522,7 +560,98 @@ def apply_passenger_speed_penalty(game_data: GameData) -> None:
     if not game_data.stage.survivor_stage:
         car.speed = CAR_SPEED
         return
-    car.speed = calculate_car_speed_for_passengers(game_data.state.survivors_onboard)
+    car.speed = calculate_car_speed_for_passengers(
+        game_data.state.survivors_onboard,
+        capacity=game_data.state.survivor_capacity,
+    )
+
+
+def rect_visible_on_screen(camera: Camera | None, rect: pygame.Rect) -> bool:
+    if camera is None:
+        return False
+    return camera.apply_rect(rect).colliderect(LOGICAL_SCREEN_RECT)
+
+
+def waiting_car_target_count(stage: Stage) -> int:
+    return SURVIVOR_STAGE_WAITING_CAR_COUNT if stage.survivor_stage else 1
+
+
+def spawn_waiting_car(game_data: GameData) -> Car | None:
+    """Attempt to place an additional parked car on the map."""
+    player = game_data.player
+    if not player:
+        return None
+    walkable_cells = game_data.areas.walkable_cells
+    if not walkable_cells:
+        return None
+    wall_group = game_data.groups.wall_group
+    all_sprites = game_data.groups.all_sprites
+    active_car = game_data.car if game_data.car and game_data.car.alive() else None
+    waiting = alive_waiting_cars(game_data)
+    obstacles: list[Car] = list(waiting)
+    if active_car:
+        obstacles.append(active_car)
+    camera = game_data.camera
+    offscreen_attempts = 6
+    while offscreen_attempts > 0:
+        new_car = place_new_car(
+            wall_group,
+            player,
+            walkable_cells,
+            existing_cars=obstacles,
+        )
+        if not new_car:
+            return None
+        if rect_visible_on_screen(camera, new_car.rect):
+            offscreen_attempts -= 1
+            continue
+        game_data.waiting_cars.append(new_car)
+        all_sprites.add(new_car, layer=1)
+        return new_car
+    return None
+
+
+def maintain_waiting_car_supply(
+    game_data: GameData, *, minimum: int | None = None
+) -> None:
+    """Ensure a baseline count of parked cars exists."""
+    target = 1 if minimum is None else max(0, minimum)
+    current = len(alive_waiting_cars(game_data))
+    while current < target:
+        new_car = spawn_waiting_car(game_data)
+        if not new_car:
+            break
+        current += 1
+
+
+def alive_waiting_cars(game_data: GameData) -> list[Car]:
+    """Return the list of parked cars that still exist, pruning any destroyed sprites."""
+    cars = [car for car in game_data.waiting_cars if car.alive()]
+    game_data.waiting_cars = cars
+    log_waiting_car_count(game_data)
+    return cars
+
+
+def log_waiting_car_count(game_data: GameData, *, force: bool = False) -> None:
+    """Print the number of waiting cars when it changes."""
+    current = len(game_data.waiting_cars)
+    if not force and current == game_data.last_logged_waiting_cars:
+        return
+    stage_id = getattr(game_data.stage, "id", "unknown")
+    game_data.last_logged_waiting_cars = current
+
+
+def nearest_waiting_car(
+    game_data: GameData, origin: tuple[float, float]
+) -> Car | None:
+    """Find the closest waiting car to an origin point."""
+    cars = alive_waiting_cars(game_data)
+    if not cars:
+        return None
+    return min(
+        cars,
+        key=lambda car: math.hypot(car.rect.centerx - origin[0], car.rect.centery - origin[1]),
+    )
 
 
 def add_survivor_message(game_data: GameData, text: str) -> None:
@@ -592,7 +721,6 @@ def handle_survivor_zombie_collisions(
     zombies.sort(key=lambda s: s.rect.centerx)
     zombie_xs = [z.rect.centerx for z in zombies]
     camera = game_data.camera
-    screen_rect = pygame.Rect(0, 0, SCREEN_WIDTH, SCREEN_HEIGHT)
 
     for survivor in list(survivor_group):
         if not survivor.alive():
@@ -622,7 +750,7 @@ def handle_survivor_zombie_collisions(
 
         if not collided:
             continue
-        if not camera.apply_rect(survivor.rect).colliderect(screen_rect):
+        if not rect_visible_on_screen(camera, survivor.rect):
             continue
         survivor.kill()
         line = random_survivor_conversion_line()
@@ -749,6 +877,7 @@ def initialize_game_state(config: dict[str, Any], stage: Stage) -> GameData:
         survivors_onboard=0,
         survivors_rescued=0,
         survivor_messages=[],
+        survivor_capacity=SURVIVOR_MAX_SAFE_PASSENGERS,
     )
 
     # Create sprite groups
@@ -796,10 +925,13 @@ def initialize_game_state(config: dict[str, Any], stage: Stage) -> GameData:
     )
 
 
-def setup_player_and_car(
-    game_data: GameData, layout_data: Mapping[str, list[pygame.Rect]]
-) -> tuple[Player, Car]:
-    """Create and position the player and car using blueprint candidates."""
+def setup_player_and_cars(
+    game_data: GameData,
+    layout_data: Mapping[str, list[pygame.Rect]],
+    *,
+    car_count: int = 1,
+) -> tuple[Player, list[Car]]:
+    """Create the player plus one or more parked cars using blueprint candidates."""
     all_sprites = game_data.groups.all_sprites
     walkable_cells: list[pygame.Rect] = layout_data["walkable_cells"]
 
@@ -813,31 +945,38 @@ def setup_player_and_car(
     player_pos = pick_center(layout_data["player_cells"] or walkable_cells)
     player = Player(*player_pos)
 
-    # Place car away from player
-    car_candidates = layout_data["car_cells"] or walkable_cells
-    car_pos = None
-    for attempt in range(200):
-        candidate = random.choice(car_candidates)
-        if (
-            math.hypot(
-                candidate.centerx - player_pos[0], candidate.centery - player_pos[1]
-            )
-            >= 400
-        ):
-            car_pos = candidate.center
+    car_candidates = list(layout_data["car_cells"] or walkable_cells)
+    waiting_cars: list[Car] = []
+
+    def _pick_car_position() -> tuple[int, int]:
+        """Favor distant cells for the first car, otherwise fall back to random picks."""
+        if not car_candidates:
+            return (player_pos[0] + 200, player_pos[1])
+        random.shuffle(car_candidates)
+        for candidate in car_candidates:
+            if (
+                math.hypot(
+                    candidate.centerx - player_pos[0],
+                    candidate.centery - player_pos[1],
+                )
+                >= 400
+            ):
+                car_candidates.remove(candidate)
+                return candidate.center
+        # No far-enough cells found; pick the first available
+        choice = car_candidates.pop()
+        return choice.center
+
+    for idx in range(max(1, car_count)):
+        car_pos = _pick_car_position()
+        car = Car(*car_pos)
+        waiting_cars.append(car)
+        all_sprites.add(car, layer=1)
+        if not car_candidates:
             break
-    if car_pos is None and car_candidates:
-        car_pos = random.choice(car_candidates).center
-    elif car_pos is None:
-        car_pos = (player_pos[0] + 200, player_pos[1])  # Fallback
 
-    car = Car(*car_pos)
-
-    # Add to sprite groups
     all_sprites.add(player, layer=2)
-    all_sprites.add(car, layer=1)
-
-    return player, car
+    return player, waiting_cars
 
 
 def spawn_initial_zombies(
@@ -878,7 +1017,7 @@ def spawn_initial_zombies(
 
 
 def process_player_input(
-    keys: Sequence[bool], player: Player, car: Car
+    keys: Sequence[bool], player: Player, car: Car | None
 ) -> tuple[float, float, float, float]:
     """Process keyboard input and return movement deltas."""
     dx_input, dy_input = 0, 0
@@ -893,7 +1032,7 @@ def process_player_input(
 
     player_dx, player_dy, car_dx, car_dy = 0, 0, 0, 0
 
-    if player.in_car and car.alive():
+    if player.in_car and car and car.alive():
         target_speed = getattr(car, "speed", CAR_SPEED)
         move_len = math.hypot(dx_input, dy_input)
         if move_len > 0:
@@ -925,32 +1064,35 @@ def update_entities(
     player = game_data.player
     assert player is not None
     car = game_data.car
-    assert car is not None
     companion = game_data.companion
     wall_group = game_data.groups.wall_group
     all_sprites = game_data.groups.all_sprites
     zombie_group = game_data.groups.zombie_group
     camera = game_data.camera
     stage = game_data.stage
+    active_car = car if car and car.alive() else None
 
     # Update player/car movement
-    if player.in_car and car.alive():
-        car.move(car_dx, car_dy, wall_group)
-        player.rect.center = car.rect.center
-        player.x, player.y = car.x, car.y
+    if player.in_car and active_car:
+        active_car.move(car_dx, car_dy, wall_group)
+        player.rect.center = active_car.rect.center
+        player.x, player.y = active_car.x, active_car.y
     elif not player.in_car:
         # Ensure player is in all_sprites if not in car
         if player not in all_sprites:
             all_sprites.add(player, layer=2)
         player.move(player_dx, player_dy, wall_group)
+    else:
+        # Player flagged as in-car but car is gone; drop them back to foot control
+        player.in_car = False
 
     # Update camera
-    target_for_camera = car if player.in_car and car.alive() else player
+    target_for_camera = active_car if player.in_car and active_car else player
     camera.update(target_for_camera)
 
     # Update companion (Stage 3 follow logic)
     if companion and companion.alive() and not companion.rescued:
-        follow_target = car if player.in_car and car.alive() else player
+        follow_target = active_car if player.in_car and active_car else player
         companion.update_follow(follow_target.rect.center, wall_group)
         if companion not in all_sprites:
             all_sprites.add(companion, layer=2)
@@ -971,24 +1113,23 @@ def update_entities(
 
     # Update zombies
     target_center = (
-        car.rect.center if player.in_car and car.alive() else player.rect.center
+        active_car.rect.center if player.in_car and active_car else player.rect.center
     )
     companion_on_screen = False
-    screen_rect = pygame.Rect(0, 0, SCREEN_WIDTH, SCREEN_HEIGHT)
     if (
         game_data.stage.requires_companion
         and companion
         and companion.alive()
         and not companion.rescued
     ):
-        companion_on_screen = camera.apply_rect(companion.rect).colliderect(screen_rect)
+        companion_on_screen = rect_visible_on_screen(camera, companion.rect)
 
     survivors_on_screen: list[Survivor] = []
     if stage.survivor_stage:
         survivor_group = game_data.groups.survivor_group
         for survivor in survivor_group:
             if getattr(survivor, "alive", lambda: False)():
-                if camera.apply_rect(survivor.rect).colliderect(screen_rect):
+                if rect_visible_on_screen(camera, survivor.rect):
                     survivors_on_screen.append(survivor)
 
     zombies_sorted: list[Zombie] = sorted(list(zombie_group), key=lambda z: z.x)
@@ -1024,7 +1165,7 @@ def update_entities(
                 target = companion.rect.center
 
         if stage.survivor_stage:
-            zombie_on_screen = camera.apply_rect(zombie.rect).colliderect(screen_rect)
+            zombie_on_screen = rect_visible_on_screen(camera, zombie.rect)
             if zombie_on_screen:
                 candidate_positions: list[tuple[int, int]] = []
                 for survivor in survivors_on_screen:
@@ -1050,10 +1191,8 @@ def check_interactions(
     player = game_data.player
     assert player is not None
     car = game_data.car
-    assert car is not None
     companion = game_data.companion
     zombie_group = game_data.groups.zombie_group
-    wall_group = game_data.groups.wall_group
     all_sprites = game_data.groups.all_sprites
     survivor_group = game_data.groups.survivor_group
     state = game_data.state
@@ -1063,6 +1202,9 @@ def check_interactions(
     flashlights = game_data.flashlights or []
     camera = game_data.camera
     stage = game_data.stage
+    maintain_waiting_car_supply(game_data)
+    active_car = car if car and car.alive() else None
+    waiting_cars = game_data.waiting_cars
 
     # Fuel pickup
     if fuel and fuel.alive() and not state.has_fuel and not player.in_car:
@@ -1104,8 +1246,7 @@ def check_interactions(
     )
     if companion_active:
         assert companion is not None
-        screen_rect = pygame.Rect(0, 0, SCREEN_WIDTH, SCREEN_HEIGHT)
-        companion_on_screen = camera.apply_rect(companion.rect).colliderect(screen_rect)
+        companion_on_screen = rect_visible_on_screen(camera, companion.rect)
 
     # Companion interactions (Stage 3)
     if companion_active and stage.requires_companion:
@@ -1113,10 +1254,10 @@ def check_interactions(
         if not player.in_car:
             if pygame.sprite.collide_circle(companion, player):
                 companion.set_following()
-        elif player.in_car and car.alive():
+        elif player.in_car and active_car:
             g = pygame.sprite.Group()
             g.add(companion)
-            if pygame.sprite.spritecollide(get_shrunk_sprite(car, 0.8), g, False):
+            if pygame.sprite.spritecollide(get_shrunk_sprite(active_car, 0.8), g, False):
                 state.companion_rescued = True
                 companion.mark_rescued()
                 companion.kill()
@@ -1140,13 +1281,18 @@ def check_interactions(
                     companion.teleport((LEVEL_WIDTH // 2, LEVEL_HEIGHT // 2))
                 companion.following = False
 
-    shrunk_car = get_shrunk_sprite(car, 0.8) if car else None
+    player_group = pygame.sprite.Group()
+    player_group.add(player)
 
-    # Player entering car
-    if not player.in_car and car.alive() and car.health > 0:
-        g = pygame.sprite.Group()
-        g.add(player)
-        if pygame.sprite.spritecollide(shrunk_car, g, False):
+    # Player entering an active car already under control
+    if (
+        not player.in_car
+        and active_car
+        and active_car.alive()
+        and active_car.health > 0
+    ):
+        shrunk_active = get_shrunk_sprite(active_car, 0.8)
+        if pygame.sprite.spritecollide(shrunk_active, player_group, False):
             if state.has_fuel:
                 player.in_car = True
                 all_sprites.remove(player)
@@ -1156,19 +1302,72 @@ def check_interactions(
             else:
                 now_ms = state.elapsed_play_ms
                 state.fuel_message_until = now_ms + FUEL_HINT_DURATION_MS
-                # Keep hint timing unchanged so the car visit doesn't immediately reveal fuel
                 state.hint_target_type = "fuel"
 
+    # Claim a waiting/parked car when the player finally reaches it
+    if not player.in_car and not active_car and waiting_cars:
+        claimed_car: Car | None = None
+        for parked_car in waiting_cars:
+            shrunk_waiting = get_shrunk_sprite(parked_car, 0.8)
+            if pygame.sprite.spritecollide(shrunk_waiting, player_group, False):
+                claimed_car = parked_car
+                break
+        if claimed_car:
+            if state.has_fuel:
+                try:
+                    game_data.waiting_cars.remove(claimed_car)
+                except ValueError:
+                    pass
+                game_data.car = claimed_car
+                active_car = claimed_car
+                player.in_car = True
+                all_sprites.remove(player)
+                state.hint_expires_at = 0
+                state.hint_target_type = None
+                apply_passenger_speed_penalty(game_data)
+                maintain_waiting_car_supply(game_data)
+                print("Player claimed a waiting car!")
+            else:
+                now_ms = state.elapsed_play_ms
+                state.fuel_message_until = now_ms + FUEL_HINT_DURATION_MS
+                state.hint_target_type = "fuel"
+
+    shrunk_car = get_shrunk_sprite(active_car, 0.8) if active_car else None
+
+    # Bonus: collide a parked car while driving to repair/extend capabilities
+    if player.in_car and active_car and shrunk_car and waiting_cars:
+        waiting_group = pygame.sprite.Group(waiting_cars)
+        collided_waiters = pygame.sprite.spritecollide(
+            shrunk_car, waiting_group, False, pygame.sprite.collide_rect
+        )
+        if collided_waiters:
+            removed_any = False
+            for parked in collided_waiters:
+                if not parked.alive():
+                    continue
+                parked.kill()
+                try:
+                    game_data.waiting_cars.remove(parked)
+                except ValueError:
+                    pass
+                active_car.health = active_car.max_health
+                active_car.update_color()
+                removed_any = True
+                if stage.survivor_stage:
+                    state.survivor_capacity += SURVIVOR_MAX_SAFE_PASSENGERS
+            if removed_any:
+                maintain_waiting_car_supply(game_data)
+
     # Car hitting zombies
-    if player.in_car and car.alive() and car.health > 0:
+    if player.in_car and active_car and active_car.health > 0 and shrunk_car:
         zombies_hit = pygame.sprite.spritecollide(shrunk_car, zombie_group, True)
         if zombies_hit:
-            car.take_damage(CAR_ZOMBIE_DAMAGE * len(zombies_hit))
+            active_car.take_damage(CAR_ZOMBIE_DAMAGE * len(zombies_hit))
 
     if (
         stage.survivor_stage
         and player.in_car
-        and car.alive()
+        and active_car
         and shrunk_car
         and survivor_group
     ):
@@ -1178,18 +1377,20 @@ def check_interactions(
         if boarded:
             state.survivors_onboard += len(boarded)
             apply_passenger_speed_penalty(game_data)
-            if state.survivors_onboard > SURVIVOR_MAX_SAFE_PASSENGERS:
+            capacity_limit = state.survivor_capacity
+            if state.survivors_onboard > capacity_limit:
                 overload_damage = max(
-                    1, int(game_data.car.max_health * SURVIVOR_OVERLOAD_DAMAGE_RATIO)
+                    1,
+                    int(active_car.max_health * SURVIVOR_OVERLOAD_DAMAGE_RATIO),
                 )
                 add_survivor_message(game_data, _("survivors.too_many_aboard"))
-                game_data.car.take_damage(overload_damage)
+                active_car.take_damage(overload_damage)
 
     if stage.survivor_stage:
         handle_survivor_zombie_collisions(game_data, config)
 
     # Handle car destruction
-    if car.alive() and car.health <= 0:
+    if car and car.alive() and car.health <= 0:
         car_destroyed_pos = car.rect.center
         car.kill()
         if stage.survivor_stage:
@@ -1202,21 +1403,14 @@ def check_interactions(
                 all_sprites.add(player, layer=2)
             print("Car destroyed! Player ejected.")
 
+        # Clear active car and let the player hunt for another waiting car.
+        game_data.car = None
+        state.survivor_capacity = SURVIVOR_MAX_SAFE_PASSENGERS
+        apply_passenger_speed_penalty(game_data)
+
         # Bring back the rescued companion near the player after losing the car
         respawn_rescued_companion_near_player(game_data)
-
-        # Respawn car
-        new_car = place_new_car(wall_group, player, walkable_cells)
-        if new_car is None:
-            # Fallback: Try original car position or other strategies
-            new_car = Car(car.rect.centerx, car.rect.centery)
-
-        if new_car is not None:
-            game_data.car = new_car  # Update car reference
-            all_sprites.add(new_car, layer=1)
-            apply_passenger_speed_penalty(game_data)
-        else:
-            print("Error: Failed to respawn car anywhere!")
+        maintain_waiting_car_supply(game_data)
 
     # Player getting caught by zombies
     if not player.in_car and player in all_sprites:
@@ -1230,7 +1424,7 @@ def check_interactions(
                 state.game_over_message = _("game_over.scream")
 
     # Player escaping the level
-    if player.in_car and car.alive() and state.has_fuel:
+    if player.in_car and car and car.alive() and state.has_fuel:
         companion_ready = not stage.requires_companion or state.companion_rescued
         if companion_ready and any(
             outside.collidepoint(car.rect.center) for outside in outside_rects
@@ -1244,5 +1438,5 @@ def check_interactions(
 
     # Return fog of view target
     if not state.game_over and not state.game_won:
-        return car if player.in_car and car.alive() else player
+        return car if player.in_car and car and car.alive() else player
     return None

{zombie_escape-1.1.4 → zombie_escape-1.2.1}/src/zombie_escape/models.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import TYPE_CHECKING
 
 import pygame
@@ -48,6 +48,7 @@ class ProgressState:
     survivors_onboard: int
     survivors_rescued: int
     survivor_messages: list
+    survivor_capacity: int
 
 
 @dataclass
@@ -74,7 +75,9 @@ class GameData:
     flashlights: list[Flashlight] | None = None
     player: Player | None = None
     car: Car | None = None
+    waiting_cars: list[Car] = field(default_factory=list)
     companion: Companion | None = None
+    last_logged_waiting_cars: int | None = None
 
 
 @dataclass(frozen=True)

{zombie_escape-1.1.4 → zombie_escape-1.2.1}/src/zombie_escape/render.py

@@ -445,10 +445,28 @@ def draw(
                 pygame.draw.circle(screen, color, sr.center, assets.footprint_radius)
 
     screen_rect_inflated = screen.get_rect().inflate(100, 100)
+    player_screen_rect: pygame.Rect | None = None
     for entity in all_sprites:
         sprite_screen_rect = camera.apply_rect(entity.rect)
         if sprite_screen_rect.colliderect(screen_rect_inflated):
             screen.blit(entity.image, sprite_screen_rect)
+        if entity is player:
+            player_screen_rect = sprite_screen_rect
+
+    if player_screen_rect is None:
+        player_screen_rect = camera.apply_rect(player.rect)
+
+    if has_fuel and player_screen_rect and not player.in_car:
+        indicator_size = max(6, (assets.player_radius // 2) * 2)
+        padding = max(2, indicator_size // 4)
+        indicator_rect = pygame.Rect(
+            player_screen_rect.right - indicator_size + padding,
+            player_screen_rect.bottom - indicator_size + padding,
+            indicator_size,
+            indicator_size,
+        )
+        pygame.draw.rect(screen, YELLOW, indicator_rect)
+        pygame.draw.rect(screen, BLACK, indicator_rect, width=1)
 
     if hint_target and player:
         current_fov_scale = get_fog_scale(
@@ -532,7 +550,7 @@ def draw(
         and getattr(stage, "survivor_stage", False)
         and (survivors_onboard is not None)
     ):
-        limit = SURVIVOR_MAX_SAFE_PASSENGERS
+        limit = getattr(state, "survivor_capacity", SURVIVOR_MAX_SAFE_PASSENGERS)
         objective_lines.append(
             _("objectives.survivors_onboard", count=survivors_onboard, limit=limit)
         )

{zombie_escape-1.1.4 → zombie_escape-1.2.1}/src/zombie_escape/screens/gameplay.py

@@ -9,6 +9,7 @@ from ..colors import LIGHT_GRAY, RED, WHITE, YELLOW
 from ..constants import (
     CAR_HINT_DELAY_MS_DEFAULT,
     DEFAULT_FLASHLIGHT_SPAWN_COUNT,
+    SURVIVOR_STAGE_WAITING_CAR_COUNT,
 )
 from ..gameplay import logic
 from ..localization import translate as _
@@ -41,9 +42,19 @@ def gameplay_screen(
     last_fov_target = None
 
     layout_data = logic.generate_level_from_blueprint(game_data, config)
-    player, car = logic.setup_player_and_car(game_data, layout_data)
+    initial_waiting = (
+        SURVIVOR_STAGE_WAITING_CAR_COUNT if stage.survivor_stage else 1
+    )
+    player, waiting_cars = logic.setup_player_and_cars(
+        game_data, layout_data, car_count=initial_waiting
+    )
     game_data.player = player
-    game_data.car = car
+    game_data.waiting_cars = waiting_cars
+    game_data.car = None
+    # Only top up if initial placement spawned fewer than the intended baseline (shouldn't happen)
+    logic.maintain_waiting_car_supply(
+        game_data, minimum=logic.waiting_car_target_count(stage)
+    )
     logic.apply_passenger_speed_penalty(game_data)
 
     if stage.survivor_stage:
@@ -59,7 +70,7 @@ def gameplay_screen(
 
     if stage.requires_fuel:
         fuel_can = logic.place_fuel_can(
-            layout_data["walkable_cells"], player, car=car
+            layout_data["walkable_cells"], player, cars=game_data.waiting_cars
         )
         if fuel_can:
             game_data.fuel = fuel_can
@@ -68,7 +79,7 @@ def gameplay_screen(
         flashlights = logic.place_flashlights(
             layout_data["walkable_cells"],
             player,
-            car=car,
+            cars=game_data.waiting_cars,
             count=max(1, flashlight_count),
         )
         game_data.flashlights = flashlights
@@ -76,7 +87,7 @@ def gameplay_screen(
 
     if stage.requires_companion:
         companion = logic.place_companion(
-            layout_data["walkable_cells"], player, car=car
+            layout_data["walkable_cells"], player, cars=game_data.waiting_cars
         )
         if companion:
             game_data.companion = companion
@@ -222,10 +233,13 @@ def gameplay_screen(
         hint_expires_at = game_data.state.hint_expires_at
         hint_target_type = game_data.state.hint_target_type
 
+        active_car = game_data.car if game_data.car and game_data.car.alive() else None
         if hint_enabled:
             if not has_fuel and game_data.fuel and game_data.fuel.alive():
                 target_type = "fuel"
-            elif not player.in_car and game_data.car.alive():
+            elif not player.in_car and (
+                active_car or logic.alive_waiting_cars(game_data)
+            ):
                 target_type = "car"
             else:
                 target_type = None
@@ -246,8 +260,15 @@ def gameplay_screen(
             ):
                 if target_type == "fuel" and game_data.fuel and game_data.fuel.alive():
                     hint_target = game_data.fuel.rect.center
-                elif target_type == "car" and game_data.car.alive():
-                    hint_target = game_data.car.rect.center
+                elif target_type == "car":
+                    if active_car:
+                        hint_target = active_car.rect.center
+                    else:
+                        waiting_target = logic.nearest_waiting_car(
+                            game_data, (player.x, player.y)
+                        )
+                        if waiting_target:
+                            hint_target = waiting_target.rect.center
 
         draw(
             render_assets,

{zombie_escape-1.1.4 → zombie_escape-1.2.1}/src/zombie_escape/zombie_escape.py

@@ -29,6 +29,15 @@ from .screens.settings import settings_screen
 from .screens.title import title_screen
 from .gameplay.logic import calculate_car_speed_for_passengers
 
+# Re-export the gameplay helpers constants for external callers/tests.
+__all__ = [
+    "main",
+    "CAR_SPEED",
+    "SURVIVOR_MAX_SAFE_PASSENGERS",
+    "SURVIVOR_MIN_SPEED_FACTOR",
+    "calculate_car_speed_for_passengers",
+]
+
 
 # --- Main Entry Point ---
 def main() -> None: