Skip to content

pikdum/thistle_tea / .agents/skills/drive-client-playtest

drive-client-playtest

Verified

Launch and drive an isolated World of Warcraft 1.12.1 client against a local Thistle Tea server, including keyboard input, left/right clicks, camera drags, screenshots, real instance entry, log observation, and Tidewave runtime probes. Use for real-client gameplay acceptance, client-sensitive protocol or movement verification, reproducing live bugs, checking visibility and instance isolation, or validating a scripted content chain beyond automated tests.

FileKindSize
SKILL.mdskill md4.9 KB
agents/openai.yamlconfig233 B
references/thistle-tea.mdmarkdown8.0 KB
scripts/test-cleanupexecutablescript4.3 KB
scripts/wow-clientexecutablescript16.4 KB

scripts/wow-client

View on GitHub
#!/usr/bin/env bash
set -euo pipefail

ensure_tools() {
  local required=()
  local packages=()
  local command_name

  case "${1:-}" in
    _run|_game) return ;;
    launch)
      required=(systemd-run systemctl xdotool glxinfo)
      case "${THISTLE_PLAYTEST_RENDERER:-gpu}" in
        gpu) required+=(gamescope gamescopectl) ;;
        software) required+=(Xvfb import) ;;
        *) fail "THISTLE_PLAYTEST_RENDERER must be gpu or software" ;;
      esac
      ;;
    stop) required=(systemctl) ;;
    capture)
      required=(xdotool systemctl)
      case "$(session_value "$(require_session "${2:-}")" renderer)" in
        gpu) required+=(gamescopectl) ;;
        software) required+=(import) ;;
        *) fail "unknown session renderer" ;;
      esac
      ;;
    *) required=(xdotool systemctl) ;;
  esac

  for command_name in "${required[@]}"; do
    if ! command -v "$command_name" >/dev/null 2>&1; then
      case "$command_name" in
        Xvfb) packages+=(nixpkgs#xorg-server) ;;
        glxinfo) packages+=(nixpkgs#mesa-demos) ;;
        import) packages+=(nixpkgs#imagemagick) ;;
        gamescopectl) packages+=(nixpkgs#gamescope) ;;
        systemd-run|systemctl) fail "a systemd user manager is required" ;;
        *) packages+=("nixpkgs#$command_name") ;;
      esac
    fi
  done

  if [[ "${#packages[@]}" -gt 0 && "${THISTLE_PLAYTEST_NIX_READY:-0}" != 1 ]]; then
    export THISTLE_PLAYTEST_NIX_READY=1
    exec nix shell "${packages[@]}" --command bash "$0" "$@"
  fi

  [[ "${#packages[@]}" == 0 ]] || fail "required playtest tools are unavailable"
}

fail() {
  echo "error: $*" >&2
  exit 1
}

usage() {
  echo "usage: wow-client launch|status|window|focus|login-debug|chat|type|key|click|drag|capture|stop ..." >&2
  exit 2
}

require_session() {
  local session_dir="${1:-}"

  [[ -n "$session_dir" ]] || usage
  [[ -d "$session_dir" ]] || fail "session directory does not exist: $session_dir"
  [[ -f "$session_dir/session.kind" ]] || fail "not a playtest session: $session_dir"
  [[ "$(<"$session_dir/session.kind")" == drive-client-playtest ]] || fail "not a playtest session: $session_dir"
  realpath -e "$session_dir"
}

session_value() {
  local session_dir="$1"
  local name="$2"
  local path="$session_dir/$name"

  [[ -f "$path" ]] || fail "session is missing $name: $session_dir"
  <"$path" tr -d '\n'
}

process_alive() {
  local pid="$1"

  [[ "$pid" =~ ^[1-9][0-9]*$ ]] || return 1
  kill -0 "$pid" 2>/dev/null
}

session_unit() {
  local session_dir="$1"
  local unit

  [[ -f "$session_dir/unit" && -f "$session_dir/unit.invocation" ]] ||
    fail "session has no systemd ownership record; legacy sessions require individual process inspection"
  unit="$(session_value "$session_dir" unit)"
  [[ "$unit" == "$(basename "$session_dir").service" && "$unit" == thistle-wow-playtest.*.service ]] ||
    fail "session unit does not match its directory"
  printf '%s\n' "$unit"
}

session_alive() {
  local session_dir="$1"
  local unit
  local expected
  local current

  unit="$(session_unit "$session_dir")" || return 1
  expected="$(session_value "$session_dir" unit.invocation)"
  current="$(systemctl --user show "$unit" -p InvocationID --value 2>/dev/null)" || return 1
  [[ -n "$expected" && "$current" == "$expected" ]] && systemctl --user is-active --quiet "$unit"
}

find_window() {
  local session_dir="$1"
  local display
  local ids

  session_alive "$session_dir" || return 1
  [[ -f "$session_dir/display" ]] || return 1
  display="$(session_value "$session_dir" display)"
  mapfile -t ids < <(DISPLAY="$display" xdotool search --onlyvisible --name '^World of Warcraft$' 2>/dev/null || true)

  [[ "${#ids[@]}" -gt 0 ]] || return 1
  printf '%s\n' "${ids[0]}"
}

wait_for_window() {
  local session_dir="$1"
  local window_id

  for _attempt in $(seq 1 180); do
    if window_id="$(find_window "$session_dir")"; then
      printf '%s\n' "$window_id"
      return 0
    fi

    session_alive "$session_dir" || return 1
    sleep 0.5
  done

  return 1
}

focus_window() {
  local session_dir="$1"
  local display
  local window_id

  display="$(session_value "$session_dir" display)"
  window_id="$(find_window "$session_dir")" || fail "WoW window is not available"
  DISPLAY="$display" xdotool windowfocus --sync "$window_id"
  printf '%s\n' "$window_id"
}

button_number() {
  case "$1" in
    left) printf '1\n' ;;
    middle) printf '2\n' ;;
    right) printf '3\n' ;;
    *) fail "mouse button must be left, middle, or right" ;;
  esac
}

choose_display() {
  local requested="${THISTLE_PLAYTEST_DISPLAY_NUMBER:-}"

  if [[ -n "$requested" ]]; then
    [[ "$requested" =~ ^[0-9]+$ ]] || fail "THISTLE_PLAYTEST_DISPLAY_NUMBER must be numeric"
    [[ ! -S "/tmp/.X11-unix/X$requested" && ! -e "/tmp/.X${requested}-lock" ]] || fail "X display :$requested is busy"
    printf '%s\n' "$requested"
    return
  fi

  for candidate in $(seq 98 109); do
    if [[ ! -S "/tmp/.X11-unix/X$candidate" && ! -e "/tmp/.X${candidate}-lock" ]]; then
      printf '%s\n' "$candidate"
      return
    fi
  done

  fail "no free X display between :98 and :109"
}

stop_session_unit() {
  local session_dir="$1"
  local unit
  local expected
  local current

  unit="$(session_unit "$session_dir")" || return 1
  expected="$(session_value "$session_dir" unit.invocation)" || return 1
  current="$(systemctl --user show "$unit" -p InvocationID --value 2>/dev/null || true)"
  [[ -n "$current" ]] || return 0
  [[ -n "$expected" && "$current" == "$expected" ]] || fail "unit ownership changed; refusing to stop $unit"
  systemctl --user stop "$unit"
}

cleanup_failed_launch() {
  local session_dir="$1"

  if [[ -f "$session_dir/unit.invocation" ]]; then
    stop_session_unit "$session_dir"
  fi
}

launch_client() {
  local wow_dir="${THISTLE_PLAYTEST_WOW_DIR:-/storage/games/World of Warcraft - Vanilla (Automation)}"
  local proton_path="${THISTLE_PLAYTEST_PROTON_PATH:-/home/pikdum/.local/share/Steam/steamapps/common/Proton - Experimental}"
  local cache_dir="${THISTLE_PLAYTEST_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}}"
  local renderer="${THISTLE_PLAYTEST_RENDERER:-gpu}"
  local session_dir
  local unit
  local window_id
  local script_path

  [[ -f "$wow_dir/WoW.exe" ]] || fail "WoW.exe not found in $wow_dir"
  [[ -f "$wow_dir/realmlist.wtf" ]] || fail "realmlist.wtf not found in $wow_dir"
  grep -Eiq 'set[[:space:]]+realmlist[[:space:]]+(localhost|127\.0\.0\.1)' "$wow_dir/realmlist.wtf" || fail "realmlist.wtf does not point to localhost"
  [[ -d "$proton_path" ]] || fail "Proton path does not exist: $proton_path"
  command -v umu-run >/dev/null 2>&1 || fail "umu-run is not available"
  systemctl --user show-environment >/dev/null || fail "the systemd user manager is unavailable"
  if [[ "$renderer" == gpu && -n "${THISTLE_PLAYTEST_DISPLAY_NUMBER:-}" ]]; then
    fail "GPU sessions allocate a private Xwayland display; DISPLAY_NUMBER applies only to software sessions"
  fi

  mkdir -p "$cache_dir"
  session_dir="$(mktemp -d "$cache_dir/thistle-wow-playtest.XXXXXX")"
  session_dir="$(realpath -e "$session_dir")"
  mkdir -p "$session_dir/prefix" "$session_dir/screenshots"
  if [[ -d "$wow_dir/WDB" && -z "${THISTLE_PLAYTEST_KEEP_WDB:-}" ]]; then
    mv "$wow_dir/WDB" "$session_dir/wdb-previous"
  fi
  printf 'drive-client-playtest\n' >"$session_dir/session.kind"
  printf '%s\n' "$renderer" >"$session_dir/renderer"
  unit="$(basename "$session_dir").service"
  printf '%s\n' "$unit" >"$session_dir/unit"

  if [[ "$renderer" == software ]]; then
    printf ':%s\n' "$(choose_display)" >"$session_dir/display.requested"
  fi

  script_path="$(realpath -e "$0")"
  trap 'cleanup_failed_launch "$session_dir"' EXIT
  trap 'exit 130' INT TERM
  systemd-run --user --quiet --collect --unit="$unit" --service-type=exec \
    --property=KillMode=control-group --property=TimeoutStopSec=5s \
    --property="StandardOutput=append:$session_dir/wow.log" \
    --property="StandardError=append:$session_dir/wow.log" \
    --setenv="PATH=$PATH" \
    "$BASH" "$script_path" _run "$session_dir" "$(realpath -e "$wow_dir")" "$(realpath -e "$proton_path")"
  systemctl --user show "$unit" -p InvocationID --value >"$session_dir/unit.invocation"

  window_id="$(wait_for_window "$session_dir")" || fail "WoW window did not appear; see $session_dir/wow.log"
  trap - EXIT INT TERM

  printf 'session=%s\n' "$session_dir"
  printf 'renderer=%s\n' "$renderer"
  printf 'unit=%s\n' "$unit"
  printf 'display=%s\n' "$(session_value "$session_dir" display)"
  printf 'window=%s\n' "$window_id"
  printf 'screenshots=%s\n' "$session_dir/screenshots"
  printf 'wow_log=%s\n' "$session_dir/wow.log"
}

run_session() {
  local session_dir="$1"
  local wow_dir="$2"
  local proton_path="$3"
  local renderer
  local xvfb_pid

  renderer="$(session_value "$session_dir" renderer)"
  unset DISPLAY WAYLAND_DISPLAY GAMESCOPE_WAYLAND_DISPLAY LIBGL_ALWAYS_SOFTWARE GALLIUM_DRIVER MESA_LOADER_DRIVER_OVERRIDE

  if [[ "$renderer" == gpu ]]; then
    exec gamescope --backend headless -W 1280 -H 720 -w 1280 -h 720 -r 60 -- \
      "$BASH" "$0" _game "$session_dir" "$wow_dir" "$proton_path"
  fi

  DISPLAY="$(session_value "$session_dir" display.requested)"
  export DISPLAY
  export LIBGL_ALWAYS_SOFTWARE=1
  Xvfb "$DISPLAY" -displayfd 3 -screen 0 1280x720x24 -ac -nolisten tcp \
    3>"$session_dir/display.ready" >"$session_dir/xvfb.log" 2>&1 &
  xvfb_pid=$!

  for _attempt in $(seq 1 50); do
    [[ -s "$session_dir/display.ready" ]] && break
    process_alive "$xvfb_pid" || fail "Xvfb exited; see $session_dir/xvfb.log"
    sleep 0.1
  done

  [[ -s "$session_dir/display.ready" ]] || fail "Xvfb did not become ready"
  run_game "$session_dir" "$wow_dir" "$proton_path"
}

run_game() {
  local session_dir="$1"
  local wow_dir="$2"
  local proton_path="$3"

  printf '%s\n' "$DISPLAY" >"$session_dir/display"
  if [[ "$(session_value "$session_dir" renderer)" == gpu ]]; then
    printf '%s\n' "${GAMESCOPE_WAYLAND_DISPLAY:?gamescope did not publish its display}" >"$session_dir/wayland.display"
  fi
  glxinfo -B >"$session_dir/renderer.log"
  if [[ "$(session_value "$session_dir" renderer)" == gpu ]] &&
    grep -Eiq 'llvmpipe|softpipe|Accelerated: no' "$session_dir/renderer.log"; then
    fail "GPU session obtained a software renderer; see $session_dir/renderer.log"
  fi

  cd "$wow_dir"
  exec env WINEPREFIX="$session_dir/prefix" PROTONPATH="$proton_path" WINEDEBUG=-all \
    SDL_AUDIODRIVER=dummy STEAM_COMPAT_MOUNTS=/storage umu-run WoW.exe -windowed -opengl
}

show_status() {
  local session_dir="$1"
  local window_id="none"

  window_id="$(find_window "$session_dir" || printf 'none')"

  printf 'session=%s\n' "$session_dir"
  printf 'display=%s\n' "$(session_value "$session_dir" display)"
  printf 'renderer=%s\n' "$(session_value "$session_dir" renderer)"
  printf 'unit=%s\n' "$(session_unit "$session_dir")"
  printf 'session_alive=%s\n' "$(session_alive "$session_dir" && printf true || printf false)"
  printf 'window=%s\n' "$window_id"
  printf 'screenshots=%s\n' "$session_dir/screenshots"
  printf 'wow_log=%s\n' "$session_dir/wow.log"
}

login_debug() {
  local session_dir="$1"
  local display
  local window_id

  display="$(session_value "$session_dir" display)"
  window_id="$(focus_window "$session_dir")"
  DISPLAY="$display" xdotool mousemove --window "$window_id" 650 378 sleep 0.1 click 1 key Home shift+End BackSpace type --clearmodifiers --delay 50 debug
  DISPLAY="$display" xdotool mousemove --window "$window_id" 650 448 sleep 0.1 click 1 key Home shift+End BackSpace type --clearmodifiers --delay 50 debug
  DISPLAY="$display" xdotool key Return
  sleep 6
  DISPLAY="$display" xdotool key Return
  sleep 8
}

send_chat() {
  local session_dir="$1"
  shift
  local text="$*"
  local display

  [[ -n "$text" ]] || usage
  display="$(session_value "$session_dir" display)"
  focus_window "$session_dir" >/dev/null
  DISPLAY="$display" xdotool key Return
  sleep 0.8
  DISPLAY="$display" xdotool type --clearmodifiers --delay 20 -- "$text"
  DISPLAY="$display" xdotool key Return
}

type_text() {
  local session_dir="$1"
  shift
  local text="$*"
  local display

  [[ -n "$text" ]] || usage
  display="$(session_value "$session_dir" display)"
  focus_window "$session_dir" >/dev/null
  DISPLAY="$display" xdotool type --clearmodifiers --delay 20 -- "$text"
}

send_key() {
  local session_dir="$1"
  shift
  local display

  [[ "$#" -gt 0 ]] || usage
  display="$(session_value "$session_dir" display)"
  focus_window "$session_dir" >/dev/null
  DISPLAY="$display" xdotool key --clearmodifiers "$@"
}

click_at() {
  local session_dir="$1"
  local button
  local x="$3"
  local y="$4"
  local display
  local window_id

  button="$(button_number "$2")"
  display="$(session_value "$session_dir" display)"
  window_id="$(focus_window "$session_dir")"
  DISPLAY="$display" xdotool mousemove --window "$window_id" "$x" "$y" sleep 0.1 click "$button"
}

drag_to() {
  local session_dir="$1"
  local button
  local x1="$3"
  local y1="$4"
  local x2="$5"
  local y2="$6"
  local display
  local window_id

  button="$(button_number "$2")"
  display="$(session_value "$session_dir" display)"
  window_id="$(focus_window "$session_dir")"
  DISPLAY="$display" xdotool mousemove --window "$window_id" "$x1" "$y1" mousedown "$button"
  sleep 0.15
  DISPLAY="$display" xdotool mousemove --sync --window "$window_id" "$x2" "$y2"
  sleep 0.15
  DISPLAY="$display" xdotool mouseup "$button"
}

capture_screen() {
  local session_dir="$1"
  local name="${2:-$(date +%Y%m%d-%H%M%S)}"
  local display
  local path
  local window_id

  [[ "$name" =~ ^[A-Za-z0-9._-]+$ ]] || fail "capture name may contain only letters, digits, dot, underscore, and hyphen"
  display="$(session_value "$session_dir" display)"
  window_id="$(find_window "$session_dir")" || fail "WoW window is not available"
  path="$session_dir/screenshots/$name.png"
  if [[ "$(session_value "$session_dir" renderer)" == gpu ]]; then
    capture_gpu_frame "$session_dir" "$path"
  else
    DISPLAY="$display" import -window "$window_id" "$path"
  fi
  printf '%s\n' "$path"
}

capture_gpu_frame() {
  local session_dir="$1"
  local path="$2"
  local pending
  local wayland_display

  wayland_display="$(session_value "$session_dir" wayland.display)"
  [[ -n "$wayland_display" ]] || fail "session is missing its Gamescope display"
  pending="$(mktemp "$session_dir/screenshots/.capture.XXXXXX.png")"
  GAMESCOPE_WAYLAND_DISPLAY="$wayland_display" timeout 10s gamescopectl screenshot "$pending"

  for _attempt in $(seq 1 100); do
    if grep -Fq "Screenshot saved to $pending" "$session_dir/wow.log" && [[ -s "$pending" ]]; then
      mv -- "$pending" "$path"
      return
    fi
    session_alive "$session_dir" || fail "session stopped during capture"
    sleep 0.1
  done

  fail "Gamescope did not finish the screenshot; see $session_dir/wow.log"
}

stop_client() {
  local session_dir="$1"

  stop_session_unit "$session_dir"
  printf 'stopped=%s\n' "$session_dir"
  printf 'artifacts_retained=%s\n' "$session_dir"
}

main() {
  ensure_tools "$@"
  local command_name="${1:-}"
  shift || true

  case "$command_name" in
    _run)
      [[ "$#" == 3 ]] || usage
      run_session "$@"
      ;;
    _game)
      [[ "$#" == 3 ]] || usage
      run_game "$@"
      ;;
    launch)
      [[ "$#" == 0 ]] || usage
      launch_client
      ;;
    status)
      [[ "$#" == 1 ]] || usage
      show_status "$(require_session "$1")"
      ;;
    window)
      [[ "$#" == 1 ]] || usage
      find_window "$(require_session "$1")" || fail "WoW window is not available"
      ;;
    focus)
      [[ "$#" == 1 ]] || usage
      focus_window "$(require_session "$1")"
      ;;
    login-debug)
      [[ "$#" == 1 ]] || usage
      login_debug "$(require_session "$1")"
      ;;
    chat)
      [[ "$#" -ge 2 ]] || usage
      local chat_session
      chat_session="$(require_session "$1")"
      shift
      send_chat "$chat_session" "$@"
      ;;
    type)
      [[ "$#" -ge 2 ]] || usage
      local type_session
      type_session="$(require_session "$1")"
      shift
      type_text "$type_session" "$@"
      ;;
    key)
      [[ "$#" -ge 2 ]] || usage
      local key_session
      key_session="$(require_session "$1")"
      shift
      send_key "$key_session" "$@"
      ;;
    click)
      [[ "$#" == 4 ]] || usage
      click_at "$(require_session "$1")" "$2" "$3" "$4"
      ;;
    drag)
      [[ "$#" == 6 ]] || usage
      drag_to "$(require_session "$1")" "$2" "$3" "$4" "$5" "$6"
      ;;
    capture)
      [[ "$#" -ge 1 && "$#" -le 2 ]] || usage
      capture_screen "$(require_session "$1")" "${2:-}"
      ;;
    stop)
      [[ "$#" == 1 ]] || usage
      stop_client "$(require_session "$1")"
      ;;
    *) usage ;;
  esac
}

if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
  main "$@"
fi
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall