RealArDor's picture
download
raw
16.6 kB
"""Headless ViZDoom adapter with bounded, visible-only text observations.
Install requirements-vizdoom.txt separately; importing this module needs only
the Python standard library. ``max_steps`` counts decisions, ``frame_skip``
counts Doom tics per decision, and optional ``max_ticks`` is an additional
task deadline measured from reset. Native scenario timeouts remain enabled.
All these deadlines are task terminations, never collector truncations.
Only visible label bounding boxes and player health/ammo/pose enter ``state``.
Kill/damage counters are evaluation information, not policy observations.
The bundled basic and predict_position scenarios each have one target.
Success means a positive KILLCOUNT delta, independently of native reward.
Primary API references:
https://vizdoom.farama.org/api/python/doom_game/
https://vizdoom.farama.org/api/python/game_state/
"""
from __future__ import annotations
import hashlib
import importlib
import json
import math
from collections import deque
from pathlib import Path
import tempfile
from typing import Any, Mapping
def _load_vizdoom():
try:
return importlib.import_module("vizdoom")
except ImportError as exc:
raise ImportError(
"ViZDoom is optional. Install it in your environment with "
"python -m pip install -r requirements-vizdoom.txt"
) from exc
def _positive_int(value: Any, name: str) -> int:
if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
raise ValueError(f"{name} must be a positive integer")
return value
def _finite(value: Any, name: str) -> float:
value = float(value)
if not math.isfinite(value):
raise RuntimeError(f"ViZDoom returned a nonfinite {name}")
return value
class UnifiedDoomEnv:
"""Synchronous PLAYER environment implementing reset/step/close.
Specs: task='shooting', scenario='basic'|'predict_position',
max_steps=75, frame_skip=4, optional max_ticks, history_length=2 (1..4).
Actions are the stable IDs left/right/shoot/noop, with no combinations.
reset(seed) re-seeds immediately before new_episode, including the first
reset; the episode implicitly created by init is never used as a rollout.
"""
_VARIABLES = (
"HEALTH", "SELECTED_WEAPON_AMMO", "POSITION_X", "POSITION_Y",
"POSITION_Z", "ANGLE", "KILLCOUNT", "DAMAGECOUNT", "DAMAGE_TAKEN",
)
_ACTIONS = {
"left": (True, False, False),
"right": (False, True, False),
"shoot": (False, False, True),
"noop": (False, False, False),
}
def __init__(self, spec: Mapping[str, Any]):
self.spec = dict(spec)
if self.spec.get("task", "shooting") != "shooting":
raise ValueError("UnifiedDoomEnv only supports task='shooting'")
self.scenario = self.spec.get("scenario", "basic")
if self.scenario not in ("basic", "predict_position"):
raise ValueError("scenario must be 'basic' or 'predict_position'")
self.max_steps = _positive_int(self.spec.get("max_steps", 75), "max_steps")
self.frame_skip = _positive_int(self.spec.get("frame_skip", 4), "frame_skip")
self.max_ticks = _positive_int(
self.spec.get("max_ticks", self.max_steps * self.frame_skip), "max_ticks"
)
self.history_length = _positive_int(
self.spec.get("history_length", 2), "history_length"
)
if self.history_length > 4:
raise ValueError("history_length must be at most 4")
self._game = None
self._vzd = None
self._temporary = None
self._active = False
self._done = True
self._history = deque(maxlen=self.history_length)
self._metadata: dict[str, Any] = {}
def _initialize(self):
self._vzd = vzd = _load_vizdoom()
game = vzd.DoomGame()
self._game = game
scenarios = Path(getattr(vzd, "scenarios_path", Path(vzd.__file__).parent / "scenarios"))
config = scenarios / f"{self.scenario}.cfg"
wad = scenarios / f"{self.scenario}.wad"
if not config.is_file() or not wad.is_file():
self.close()
raise RuntimeError(f"Bundled ViZDoom scenario files are missing: {config}")
self._temporary = tempfile.TemporaryDirectory(prefix="nanojev_doom_")
try:
game.load_config(str(config))
game.set_doom_scenario_path(str(wad))
game.set_doom_config_path(str(Path(self._temporary.name) / "vizdoom.ini"))
game.set_mode(vzd.Mode.PLAYER)
game.set_window_visible(False)
game.set_sound_enabled(False)
game.set_console_enabled(False)
game.set_screen_resolution(vzd.ScreenResolution.RES_320X240)
game.set_screen_format(vzd.ScreenFormat.RGB24)
game.set_labels_buffer_enabled(True)
game.set_objects_info_enabled(False)
game.set_sectors_info_enabled(False)
game.set_automap_buffer_enabled(False)
game.set_depth_buffer_enabled(False)
names = ("MOVE_LEFT", "MOVE_RIGHT", "ATTACK") if self.scenario == "basic" else (
"TURN_LEFT", "TURN_RIGHT", "ATTACK"
)
game.set_available_buttons([getattr(vzd.Button, name) for name in names])
missing = [name for name in self._VARIABLES if not hasattr(vzd.GameVariable, name)]
if missing:
raise RuntimeError(f"ViZDoom GameVariable API is missing: {missing}")
game.set_available_game_variables([
getattr(vzd.GameVariable, name) for name in self._VARIABLES
])
self._metadata = {
"backend": "vizdoom", "vizdoom_version": str(getattr(vzd, "__version__", "unknown")),
"scenario": self.scenario, "mode": "PLAYER", "buttons": list(names),
"scenario_config_sha256": hashlib.sha256(config.read_bytes()).hexdigest(),
"scenario_wad_sha256": hashlib.sha256(wad.read_bytes()).hexdigest(),
"observation_source": "visible_label_boxes_and_player_health_ammo_pose",
"objects_info_enabled": False, "sectors_info_enabled": False,
"timeout_detection": "native_flag_and_episode_clock" if hasattr(
game, "is_episode_timeout_reached"
) else "episode_clock",
"counter_source": "get_game_variable_after_each_single_tick",
"physical_tick_source": "synchronous_single_tick_calls",
"action_repeat": "same_buttons_until_duration_or_first_goal_terminal_tick",
"frame_skip": self.frame_skip, "max_steps": self.max_steps,
"max_ticks": self.max_ticks, "history_length": self.history_length,
}
game.init()
except Exception:
self.close()
raise
def _variables(self) -> dict[str, float]:
# Explicit enum checks above prevent an absent enum being mistaken for 0.
# No fallback from unreadable terminal counters to reward is permitted.
return {
name: _finite(self._game.get_game_variable(getattr(self._vzd.GameVariable, name)), name)
for name in self._VARIABLES
}
def _remaining_ticks(self) -> int:
budget = max(0, self.max_ticks - self._physical_ticks)
if self._native_timeout > 0:
budget = min(budget, max(0, self._native_timeout - self._episode_tick))
return budget
def _visible_snapshot(self, state, variables) -> dict[str, Any]:
labels = []
if state is not None:
buffer = state.labels_buffer
if buffer is None:
raise RuntimeError("ViZDoom labels buffer is missing despite being enabled")
for label in state.labels:
# A bounding box alone is insufficient: require rendered pixels.
# This never accesses state.objects, sectors, hidden entities or RNG.
value = int(label.value)
if value == 0 or not bool((buffer == value).any()):
continue
box = [int(label.x), int(label.y), int(label.width), int(label.height)]
if box[2] <= 0 or box[3] <= 0:
continue
labels.append({"id": int(label.object_id), "name": str(label.object_name), "bbox": box})
labels.sort(key=lambda row: (row["id"], row["name"], row["bbox"]))
return {
"episode_tick": self._episode_tick,
"health": variables["HEALTH"], "ammo": variables["SELECTED_WEAPON_AMMO"],
"position": [round(variables[f"POSITION_{axis}"], 3) for axis in "XYZ"],
"angle_degrees": round(variables["ANGLE"], 3),
"visible_labels": labels, "visual_state_available": state is not None,
}
def _observation(self) -> dict[str, Any]:
ticks = 0 if self._done else self._remaining_ticks()
remaining = 0 if self._done else min(
self.max_steps - self._step, (ticks + self.frame_skip - 1) // self.frame_skip
)
duration = min(self.frame_skip, ticks)
movement = "Strafe" if self.scenario == "basic" else "Turn"
candidates = {} if self._done else {
"left": f"{movement} left for {duration} Doom ticks.",
"right": f"{movement} right for {duration} Doom ticks.",
"shoot": f"Hold attack for {duration} Doom ticks.",
"noop": f"Wait without pressing buttons for {duration} Doom ticks.",
}
payload = {
"scenario": self.scenario, "goal": "Eliminate the monster before the task deadline.",
"screen_size": [320, 240], "bbox_format": "x,y,width,height; origin top left",
"remaining_decisions": remaining, "remaining_ticks": ticks,
"observed_history": list(self._history), "terminal": self._done,
}
return {
"task": "shooting", "state": json.dumps(payload, separators=(",", ":"), allow_nan=False),
"candidates": candidates, "remaining_steps": remaining, "step": self._step,
}
def _info(self, native_reward=0.0, action_id=None, requested_ticks=0, actual_ticks=0):
current = self._current
metrics = {
"success": self._success, "outcome": self._outcome,
"decisions": self._step, "physical_ticks": self._physical_ticks,
"native_reward": self._native_reward,
"killcount": current["KILLCOUNT"],
"kills": current["KILLCOUNT"] - self._initial["KILLCOUNT"],
"damage_dealt": current["DAMAGECOUNT"] - self._initial["DAMAGECOUNT"],
"damage_taken": current["DAMAGE_TAKEN"] - self._initial["DAMAGE_TAKEN"],
"health": current["HEALTH"], "ammo": current["SELECTED_WEAPON_AMMO"],
"ammo_consumed": self._ammo_consumed,
}
return {
**self._metadata, "seed": self._seed, "success": self._success,
"episode_metrics": metrics, "native_reward": native_reward,
"native_total_reward": _finite(self._game.get_total_reward(), "total_reward"),
"action_id": action_id, "requested_ticks": requested_ticks, "actual_ticks": actual_ticks,
"episode_tick": self._episode_tick, "episode_start_tick": self._start_tick,
"native_episode_tick": self._native_episode_tick,
"native_clock_resets": self._native_clock_resets,
"native_timeout_tick": self._native_timeout,
"terminated": self._done, "truncated": False,
"terminal_reason": self._outcome if self._done else None,
"bootstrap_allowed": not self._done,
}
def reset(self, seed: int = 0):
if isinstance(seed, bool) or not isinstance(seed, int) or not 0 <= seed < 2**32:
raise ValueError("seed must be an integer in [0, 2**32)")
if self._game is None:
self._initialize()
self._game.set_seed(seed)
self._game.new_episode()
if self._game.is_episode_finished():
raise RuntimeError("ViZDoom scenario is already terminal at reset")
self._seed = seed
self._step = self._physical_ticks = 0
self._native_reward = self._ammo_consumed = 0.0
self._episode_tick = self._start_tick = int(self._game.get_episode_time())
self._native_episode_tick = self._episode_tick
self._native_clock_resets = 0
self._native_timeout = int(self._game.get_episode_timeout())
self._initial = self._current = self._variables()
self._success = self._done = False
self._outcome = "running"
self._active = True
self._history.clear()
state = self._game.get_state()
if state is None or self._remaining_ticks() <= 0:
raise RuntimeError("ViZDoom reset has no usable state or remaining task ticks")
self._history.append(self._visible_snapshot(state, self._current))
return self._observation(), self._info()
def step(self, action_id: str):
if not self._active or self._done:
raise RuntimeError("Call reset before step and after every terminal transition")
if not isinstance(action_id, str) or action_id not in self._ACTIONS:
raise ValueError(f"Unknown action ID: {action_id!r}")
requested = min(self.frame_skip, self._remaining_ticks())
if requested <= 0:
raise RuntimeError("Live episode unexpectedly has no remaining physical ticks")
reward, actual = 0.0, 0
finished = dead = native_timeout = False
# A multi-tic call can cross a scripted map exit and reset episode time
# and counters. Advance one synchronous tic at a time, holding the same
# chosen buttons, so the first observed kill is retained before that exit.
for _ in range(requested):
previous, before_tick = self._current, self._native_episode_tick
reward += _finite(self._game.make_action(list(self._ACTIONS[action_id]), 1), "reward")
self._native_episode_tick = int(self._game.get_episode_time())
finished = bool(self._game.is_episode_finished())
native_delta = self._native_episode_tick - before_tick
if native_delta != 1:
if finished and native_delta <= 0:
self._native_clock_resets += 1
else:
raise RuntimeError(f"Unexpected clock change after one synchronous tick: {native_delta}")
actual += 1
self._physical_ticks += 1
self._episode_tick = self._start_tick + self._physical_ticks
self._current = self._variables()
self._ammo_consumed += max(
0.0, previous["SELECTED_WEAPON_AMMO"] - self._current["SELECTED_WEAPON_AMMO"]
)
self._success = self._current["KILLCOUNT"] > self._initial["KILLCOUNT"]
dead = bool(self._game.is_player_dead())
native_timeout = self._native_timeout > 0 and self._episode_tick >= self._native_timeout
if hasattr(self._game, "is_episode_timeout_reached"):
native_timeout = native_timeout or bool(self._game.is_episode_timeout_reached())
if self._success or dead or finished or native_timeout:
break
self._step += 1
self._native_reward += reward
deadline = self._step >= self.max_steps or self._physical_ticks >= self.max_ticks
self._done = bool(self._success or dead or native_timeout or deadline or finished)
self._outcome = (
"target_killed" if self._success else "player_dead" if dead else
"native_timeout" if native_timeout else "task_deadline" if deadline else
"native_terminal_without_kill" if finished else "running"
)
self._history.append(self._visible_snapshot(self._game.get_state(), self._current))
return self._observation(), reward, self._done, False, self._info(reward, action_id, requested, actual)
def close(self):
if self._game is not None:
try:
self._game.close()
finally:
self._game = None
if self._temporary is not None:
self._temporary.cleanup()
self._temporary = None
self._active = False
self._done = True
def __enter__(self):
return self
def __exit__(self, *_):
self.close()

Xet Storage Details

Size:
16.6 kB
·
Xet hash:
c99ece57ceee891db4f0f4d148ab24cea5b9f68979a9a67ec96cee24f557944c

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.