pikdum/thistle_tea / .agents/skills/drive-client-playtest
drive-client-playtest
VerifiedLaunch 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.9 KB |
| agents/openai.yaml | config | 233 B |
| references/thistle-tea.md | markdown | 8.0 KB |
| scripts/test-cleanupexecutable | script | 4.3 KB |
| scripts/wow-clientexecutable | script | 16.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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |