frontengine 1.0.26__tar.gz → 1.0.28__tar.gz

{frontengine-1.0.26 → frontengine-1.0.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frontengine
-Version: 1.0.26
+Version: 1.0.28
 Summary: FrontEngine is use-define frontview or only use like screen saver
 Author-email: JE-Chen <jechenmailman@gmail.com>
 Project-URL: Homepage, https://github.com/Intergration-Automation-Testing/FrontEngine
@@ -53,6 +53,38 @@ It provides an intuitive interface and supports multiple media formats for inter
 
 ---
 
+## Desktop pet
+
+Spawn an animated sprite that lives on your desktop, from the **Pet** tab.
+
+- **Sprites** — pick a single GIF/WebP/PNG, or a *pet pack* folder whose file
+  names map to states: `walk`, `idle`, `sleep`, `climb`, `fall`, `drag`
+  (missing states fall back to `walk`).
+- **Behaviour** — walk on the floor with gravity (throw it and it bounces),
+  wander freely, or chase the cursor. Floor pets can climb screen edges and
+  stand on the top edge of other windows.
+- **Life** — mood, fullness and an affection level that persist between runs;
+  the pet grows as it levels up, chats in speech bubbles, naps while you are
+  away, and warns you about a low battery.
+- **Interaction** — drag it around, right-click to clone/feed/set a reminder,
+  and **drop a file onto it**: an image or pet pack becomes its new look,
+  anything else is eaten. What it eats matters — an archive is a feast, music
+  cheers it up more than it fills, a document is a modest meal, and a binary is
+  too hard to chew.
+- **Tag** — with two or more pets on screen, tick *Play tag with each other* and
+  one becomes "it": it walks toward its nearest neighbour while the others run
+  the other way, and catching someone passes the tag on.
+- **React to audio** — the pet pulses to your speakers' output level. It reads
+  only the Windows output *meter* (WASAPI `IAudioMeterInformation`); no audio
+  is captured or recorded. Peaks are smoothed with an RMS window and a
+  fast-attack/slow-decay envelope so the pulse breathes instead of flickering.
+  On multi-monitor setups each pet follows the audio endpoint that matches its
+  own screen, falling back to the default output device.
+
+Audio features are Windows-only and degrade to "no pulse" elsewhere.
+
+---
+
 ## Install
 
 - **System Requirements**

{frontengine-1.0.26 → frontengine-1.0.28}/README.md

@@ -29,6 +29,38 @@ It provides an intuitive interface and supports multiple media formats for inter
 
 ---
 
+## Desktop pet
+
+Spawn an animated sprite that lives on your desktop, from the **Pet** tab.
+
+- **Sprites** — pick a single GIF/WebP/PNG, or a *pet pack* folder whose file
+  names map to states: `walk`, `idle`, `sleep`, `climb`, `fall`, `drag`
+  (missing states fall back to `walk`).
+- **Behaviour** — walk on the floor with gravity (throw it and it bounces),
+  wander freely, or chase the cursor. Floor pets can climb screen edges and
+  stand on the top edge of other windows.
+- **Life** — mood, fullness and an affection level that persist between runs;
+  the pet grows as it levels up, chats in speech bubbles, naps while you are
+  away, and warns you about a low battery.
+- **Interaction** — drag it around, right-click to clone/feed/set a reminder,
+  and **drop a file onto it**: an image or pet pack becomes its new look,
+  anything else is eaten. What it eats matters — an archive is a feast, music
+  cheers it up more than it fills, a document is a modest meal, and a binary is
+  too hard to chew.
+- **Tag** — with two or more pets on screen, tick *Play tag with each other* and
+  one becomes "it": it walks toward its nearest neighbour while the others run
+  the other way, and catching someone passes the tag on.
+- **React to audio** — the pet pulses to your speakers' output level. It reads
+  only the Windows output *meter* (WASAPI `IAudioMeterInformation`); no audio
+  is captured or recorded. Peaks are smoothed with an RMS window and a
+  fast-attack/slow-decay envelope so the pulse breathes instead of flickering.
+  On multi-monitor setups each pet follows the audio endpoint that matches its
+  own screen, falling back to the default output device.
+
+Audio features are Windows-only and degrade to "no pulse" elsewhere.
+
+---
+
 ## Install
 
 - **System Requirements**

{frontengine-1.0.26 → frontengine-1.0.28}/frontengine/show/pet/desktop_pet.py

@@ -12,6 +12,7 @@ from PySide6.QtWidgets import QMenu, QMessageBox, QWidget
 from frontengine.show.base_widget import BaseWidget
 from frontengine.show.window_helpers import apply_overlay_window_flags
 from frontengine.user_setting.user_setting_file import user_setting_dict
+from frontengine.utils.audio_meter.audio_envelope import AudioEnvelope
 from frontengine.utils.logging.loggin_instance import front_engine_logger
 from frontengine.utils.multi_language.language_wrapper import language_wrapper
 
@@ -82,6 +83,65 @@ def scan_pet_pack(folder: str) -> dict:
     return result
 
 
+# 拖進寵物的檔案分類 / What a file dropped onto the pet means
+DROP_SPRITE = "sprite"  # 圖片或動作包 -> 換一套外觀
+DROP_FOOD = "food"      # 其他檔案 -> 當成食物餵給寵物
+
+
+def classify_drop(path) -> Optional[str]:
+    """
+    判斷拖到寵物身上的檔案要換裝還是當食物；路徑無效或空資料夾回傳 None。
+    Classify a file dropped onto the pet: a sprite/pack to wear, food to eat,
+    or None when the path is unusable.
+    """
+    try:
+        target = Path(path)
+        if not target.exists():
+            return None
+    except (OSError, TypeError, ValueError):
+        return None
+    if target.is_dir():
+        return DROP_SPRITE if scan_pet_pack(str(target)) else None
+    return DROP_SPRITE if target.suffix.lower() in _PACK_EXTS else DROP_FOOD
+
+
+# 食物種類（依副檔名猜）與各自的效果 / Food kinds guessed from the suffix
+FOOD_SNACK = "snack"    # 一般點心 / an ordinary snack
+FOOD_FEAST = "feast"    # 壓縮檔＝大餐 / an archive is a hearty meal
+FOOD_MUSIC = "music"    # 音樂檔＝聽了很開心 / music cheers it up more than it fills
+FOOD_BOOK = "book"      # 文件檔＝細嚼慢嚥 / a document is chewed slowly
+FOOD_HARD = "hard"      # 可執行檔＝咬不動 / a binary is too hard to chew
+
+_FOOD_SUFFIXES = {
+    FOOD_FEAST: (".zip", ".7z", ".rar", ".tar", ".gz", ".iso"),
+    FOOD_MUSIC: (".mp3", ".wav", ".ogg", ".flac", ".m4a", ".aac"),
+    FOOD_BOOK: (".txt", ".md", ".pdf", ".doc", ".docx", ".rtf", ".epub"),
+    FOOD_HARD: (".exe", ".dll", ".msi", ".sys", ".bat"),
+}
+
+# 每種食物的飽足／心情／親密度變化（心情為負代表不喜歡）
+# Fullness / mood / affection change per food kind (negative mood = dislikes it).
+FOOD_EFFECTS = {
+    FOOD_SNACK: {"fullness": 30, "mood": 12, "affection": 5},
+    FOOD_FEAST: {"fullness": 45, "mood": 8, "affection": 6},
+    FOOD_MUSIC: {"fullness": 15, "mood": 20, "affection": 5},
+    FOOD_BOOK: {"fullness": 20, "mood": 6, "affection": 4},
+    FOOD_HARD: {"fullness": 2, "mood": -6, "affection": 1},
+}
+
+
+def classify_food(path) -> str:
+    """依副檔名判斷食物種類；認不出來就當一般點心 / Guess the food kind from the suffix."""
+    try:
+        suffix = Path(path).suffix.lower()
+    except (OSError, TypeError, ValueError):
+        return FOOD_SNACK
+    for kind, suffixes in _FOOD_SUFFIXES.items():
+        if suffix in suffixes:
+            return kind
+    return FOOD_SNACK
+
+
 def derive_visual_state(dragging: bool, airborne: bool, surface: str, motion_state: str) -> str:
     """依目前情形推導應顯示的視覺狀態 / Derive which sprite state to show."""
     if dragging:
@@ -268,6 +328,92 @@ def nearest_peer(center, peers):
     return best, best_distance
 
 
+# 鬼抓人角色 / Roles in the tag game
+TAG_CHASE = "chase"
+TAG_FLEE = "flee"
+
+
+class PetTagGame:
+    """
+    多隻寵物的鬼抓人：一隻當鬼追最近的同伴，其他往反方向逃；抓到就換人當鬼，
+    並有短暫冷卻避免立刻抓回去。純邏輯、不依賴 Qt，由外部每一拍餵入座標。
+
+    Tag between pets: one is "it" and chases its nearest peer while the others
+    run the other way; catching someone passes "it" on, with a short cooldown so
+    the tag cannot bounce straight back. Pure logic — positions are fed in each
+    tick from outside.
+    """
+
+    CATCH_DISTANCE = 60.0
+    FLEE_DISTANCE = 220.0
+    COOLDOWN_TICKS = 20
+
+    def __init__(self, catch_distance: float = CATCH_DISTANCE, flee_distance: float = FLEE_DISTANCE,
+                 cooldown_ticks: int = COOLDOWN_TICKS) -> None:
+        self.catch_distance = float(catch_distance)
+        self.flee_distance = float(flee_distance)
+        self.cooldown_ticks = max(0, int(cooldown_ticks))
+        self.it = None
+        self.just_tagged = None
+        self._cooldown = 0
+
+    def reset(self) -> None:
+        """重置遊戲（參與者換人或停玩時呼叫）。"""
+        self.it = None
+        self.just_tagged = None
+        self._cooldown = 0
+
+    @staticmethod
+    def _nearest(positions: dict, source):
+        """回傳離 source 最近的其他參與者 (id, 距離)；只有一人時回傳 (None, inf)。"""
+        source_x, source_y = positions[source]
+        best, best_distance = None, float("inf")
+        for participant, (x, y) in positions.items():
+            if participant == source:
+                continue
+            distance = ((x - source_x) ** 2 + (y - source_y) ** 2) ** 0.5
+            if distance < best_distance:
+                best, best_distance = participant, distance
+        return best, best_distance
+
+    def update(self, positions: dict) -> dict:
+        """
+        餵入 {參與者: (x, y)}，回傳 {參與者: (角色, 目標 x)}。少於兩人時不開局。
+        Feed in {participant: (x, y)} and get {participant: (role, target_x)}.
+        """
+        self.just_tagged = None
+        if not positions or len(positions) < 2:
+            self.reset()
+            return {}
+        if self.it not in positions:
+            self.it = sorted(positions)[0]
+            self._cooldown = self.cooldown_ticks
+        # 冷卻期間只是跑給對方追，不換鬼；先判斷再遞減，冷卻 N 拍就真的保護 N 拍。
+        # While cooling down nobody can be tagged; check before decrementing so a
+        # cooldown of N protects exactly N updates.
+        can_tag = self._cooldown <= 0
+        if self._cooldown > 0:
+            self._cooldown -= 1
+        prey, distance = self._nearest(positions, self.it)
+        if prey is not None and can_tag and distance <= self.catch_distance:
+            self.it = prey
+            self.just_tagged = prey
+            self._cooldown = self.cooldown_ticks
+            prey, _distance = self._nearest(positions, self.it)
+        return self._roles(positions, prey)
+
+    def _roles(self, positions: dict, prey) -> dict:
+        """依目前的鬼與獵物組出每個人的角色與要走向的 x。"""
+        it_x, _it_y = positions[self.it]
+        roles = {self.it: (TAG_CHASE, positions[prey][0] if prey is not None else it_x)}
+        for participant, (x, _y) in positions.items():
+            if participant == self.it:
+                continue
+            away = self.flee_distance if x >= it_x else -self.flee_distance
+            roles[participant] = (TAG_FLEE, x + away)
+        return roles
+
+
 def message_bucket(hour: int) -> str:
     """依小時回傳時段 / Time-of-day bucket for the given hour."""
     hour = int(hour) % 24
@@ -876,6 +1022,7 @@ class DesktopPetWidget(BaseWidget):
             message_box.show()
 
         self.resize(self.pet_size, self.pet_size)
+        self.setAcceptDrops(True)  # drop an image to dress it up, anything else to feed it
         self.motion = PetMotion(
             0, 0, self.pet_size, self.pet_size, (0, 0, 1920, 1080), speed, behaviour, climb=climb
         )
@@ -901,10 +1048,15 @@ class DesktopPetWidget(BaseWidget):
         self._audio_react = bool(audio_react)
         self._audio_level_provider = None  # callable -> level 0..1 or None
         self._audio_scale = 1.0
+        # 峰值抖動大，先過 RMS + 快起慢降包絡再驅動脈動
+        # Raw peaks jitter, so smooth them through an RMS + attack/decay envelope.
+        self._audio_envelope = AudioEnvelope()
         # 多寵物互動 / Multi-pet interaction
         self._peers_provider = None
         self._peer_greeted = False
         self._peer_tick = 0
+        # 鬼抓人角色（由外部的 PetTagGame 指派）/ Tag role assigned by a PetTagGame
+        self._tag_role = None
         # 電量提醒 / Low-battery reaction
         self._battery_provider = read_battery
         self._battery_warned = False
@@ -957,8 +1109,31 @@ class DesktopPetWidget(BaseWidget):
         """設定回傳其他寵物中心座標清單的函式 / Provider of other pets' centres."""
         self._peers_provider = provider
 
+    def apply_tag_role(self, role) -> None:
+        """
+        套用鬼抓人角色 (角色, 目標 x)；None 代表沒在玩，恢復平常的同伴互動。
+        Apply a tag role; None means the game is off and normal peer play resumes.
+        """
+        if role is None:
+            if self._tag_role is not None:
+                self._tag_role = None
+                self.motion.clear_follow()
+            return
+        self._tag_role, target_x = role
+        self.motion.wake()
+        self.motion.set_follow(target_x)
+
+    def on_tagged(self) -> None:
+        """換自己當鬼時喊一句 / Shout when the tag lands on this pet."""
+        self._gain_affection(1)
+        pool = self._messages.get("tag") or []
+        if pool:
+            self.say(pool[self._chatter_rng.randrange(len(pool))])
+
     def _check_peers(self) -> None:
         """靠近其他寵物時走過去玩耍、抵達後轉向打招呼（帶遲滯，避免重複）。"""
+        if self._tag_role is not None:
+            return  # the tag game owns where this pet is heading
         if self._peers_provider is None:
             return
         try:
@@ -992,19 +1167,50 @@ class DesktopPetWidget(BaseWidget):
             self._peer_greeted = False
 
     def _load_sprite(self, path: str):
+        """載入一張精靈；檔案損毀或格式不支援時回傳 None。"""
         if Path(path).suffix.lower() in (".gif", ".webp"):
             movie = QMovie(str(path))
+            if not movie.isValid():
+                return None
             movie.frameChanged.connect(self.update)
             return ("movie", movie)
-        return ("pixmap", QPixmap(str(path)))
+        pixmap = QPixmap(str(path))
+        return None if pixmap.isNull() else ("pixmap", pixmap)
 
     def _load_sprites(self, image_path: Path) -> None:
-        """單一檔 -> 所有狀態共用；資料夾 -> 依檔名對應各狀態。"""
+        """單一檔 -> 所有狀態共用；資料夾 -> 依檔名對應各狀態；載不起來的略過。"""
         if image_path.is_dir():
             for state, path in scan_pet_pack(str(image_path)).items():
-                self._sprites[state] = self._load_sprite(path)
+                sprite = self._load_sprite(path)
+                if sprite is not None:
+                    self._sprites[state] = sprite
         elif image_path.is_file():
-            self._sprites["default"] = self._load_sprite(str(image_path))
+            sprite = self._load_sprite(str(image_path))
+            if sprite is not None:
+                self._sprites["default"] = sprite
+
+    def change_sprite(self, path) -> None:
+        """換一套外觀（拖圖片或動作包到寵物身上時觸發）；載不到就維持原樣。"""
+        image_path = Path(path)
+        previous = self._sprites
+        self._sprites = {}
+        self._load_sprites(image_path)
+        if not self._sprites:
+            front_engine_logger.warning(f"[DesktopPetWidget] change_sprite ignored: {image_path}")
+            self._sprites = previous
+            return
+        front_engine_logger.info(f"[DesktopPetWidget] change_sprite | path={image_path}")
+        for kind, obj in previous.values():
+            if kind == "movie":
+                obj.stop()
+        self.image_path = image_path
+        self._active = None
+        self._active_state = None
+        self._set_active_sprite(self._visual_state())
+        self._gain_affection(2)
+        pool = self._messages.get("costume") or []
+        if pool:
+            self.say(pool[self._chatter_rng.randrange(len(pool))])
 
     def _sprite_for(self, state: str):
         if "default" in self._sprites:
@@ -1042,16 +1248,23 @@ class DesktopPetWidget(BaseWidget):
     def set_audio_level_provider(self, provider) -> None:
         """設定回傳目前音量 (0~1 或 None) 的函式 / Provider of the current audio level."""
         self._audio_level_provider = provider
+        self._audio_envelope.reset()
 
     def _update_audio_scale(self) -> None:
+        """取一次音量取樣，經包絡平滑後換算成脈動比例（無音源則不脈動）。"""
         if not self._audio_react or self._audio_level_provider is None:
             self._audio_scale = 1.0
+            self._audio_envelope.reset()
             return
         try:
             level = self._audio_level_provider()
         except Exception:  # pragma: no cover - defensive
             level = None
-        self._audio_scale = 1.0 if level is None else audio_pulse_scale(level)
+        if level is None:
+            self._audio_scale = 1.0
+            self._audio_envelope.reset()
+            return
+        self._audio_scale = audio_pulse_scale(self._audio_envelope.push(level))
 
     def draw_content(self, painter: QPainter) -> None:
         pixmap = self._current_pixmap()
@@ -1099,8 +1312,14 @@ class DesktopPetWidget(BaseWidget):
             "battery": lines("pet_chatter_battery", "Battery's low - plug me in?|Low power!|Find a charger?"),
             "hungry": lines("pet_chatter_hungry", "I'm hungry...|Got a snack?|Feed me?"),
             "fed": lines("pet_chatter_fed", "Yum!|Thank you!|Delicious!"),
+            "fed_feast": lines("pet_chatter_fed_feast", "What a feast!|So full!|That was huge!"),
+            "fed_music": lines("pet_chatter_fed_music", "Tasty tune!|That one sings!|Encore!"),
+            "fed_book": lines("pet_chatter_fed_book", "Food for thought.|Chewy words!|Mmm, a story."),
+            "fed_hard": lines("pet_chatter_fed_hard", "Too hard to chew!|Ouch, my teeth!|Not food!"),
             "away": lines("pet_chatter_away", "Still there?|I'll nap till you're back~|Zzz..."),
             "levelup": lines("pet_chatter_levelup", "Level up!|I'm growing!|We're getting closer!"),
+            "costume": lines("pet_chatter_costume", "New look!|How do I look?|Nice fit!"),
+            "tag": lines("pet_chatter_tag", "You're it!|Caught you!|My turn to chase!"),
             "any": lines("pet_chatter_any", "Hi there!|(^_^)|Keep going!"),
         }
 
@@ -1267,14 +1486,19 @@ class DesktopPetWidget(BaseWidget):
     def _persist_hunger(self) -> None:
         user_setting_dict["pet_hunger"] = self._hunger.value
 
-    def feed(self) -> None:
-        """餵食：補足飽足並讓心情變好，說一句道謝。"""
-        self._hunger.feed()
-        self._mood.pet()
+    def feed(self, kind: str = FOOD_SNACK) -> None:
+        """餵食：依食物種類調整飽足與心情，並說一句對應的話。"""
+        effect = FOOD_EFFECTS.get(kind, FOOD_EFFECTS[FOOD_SNACK])
+        self._hunger.feed(effect["fullness"])
+        mood_change = effect["mood"]
+        if mood_change >= 0:
+            self._mood.pet(mood_change)
+        else:
+            self._mood.decay(-mood_change)
         self._persist_hunger()
         self._persist_mood()
-        self._gain_affection(5)
-        pool = self._messages.get("fed") or []
+        self._gain_affection(effect["affection"])
+        pool = self._messages.get(f"fed_{kind}") or self._messages.get("fed") or []
         if pool:
             self.say(pool[self._chatter_rng.randrange(len(pool))])
 
@@ -1389,6 +1613,38 @@ class DesktopPetWidget(BaseWidget):
                 self.say()  # a click (no drag) makes the pet talk
         super().mouseReleaseEvent(event)
 
+    # --- drop a file onto the pet: wear it (image / pack) or eat it ---
+    @staticmethod
+    def dropped_path(mime_data) -> Optional[str]:
+        """從拖曳資料取出第一個可用的本機路徑；沒有可用者回傳 None。"""
+        if mime_data is None or not mime_data.hasUrls():
+            return None
+        for url in mime_data.urls():
+            local_path = url.toLocalFile()
+            if local_path and classify_drop(local_path) is not None:
+                return local_path
+        return None
+
+    def dragEnterEvent(self, event) -> None:
+        if self.dropped_path(event.mimeData()) is not None:
+            event.acceptProposedAction()
+
+    def dragMoveEvent(self, event) -> None:
+        if self.dropped_path(event.mimeData()) is not None:
+            event.acceptProposedAction()
+
+    def dropEvent(self, event) -> None:
+        path = self.dropped_path(event.mimeData())
+        if path is None:
+            return
+        front_engine_logger.info(f"[DesktopPetWidget] dropEvent | path={path}")
+        self.motion.wake()
+        if classify_drop(path) == DROP_SPRITE:
+            self.change_sprite(path)
+        else:
+            self.feed(classify_food(path))
+        event.acceptProposedAction()
+
     def contextMenuEvent(self, event) -> None:
         self.menu.popup(event.globalPos())
 

{frontengine-1.0.26 → frontengine-1.0.28}/frontengine/ui/page/pet/pet_setting_ui.py

@@ -1,12 +1,13 @@
 from typing import Optional
 
+from PySide6.QtCore import QTimer
 from PySide6.QtGui import QGuiApplication
 from PySide6.QtWidgets import (
     QWidget, QGridLayout, QLabel, QPushButton, QMessageBox, QComboBox, QCheckBox, QFileDialog,
 )
 
 from frontengine.show.pet.desktop_pet import (
-    DesktopPetWidget, BEHAVIOUR_FLOOR, BEHAVIOUR_WANDER, BEHAVIOUR_CHASE, scan_pet_pack,
+    DesktopPetWidget, BEHAVIOUR_FLOOR, BEHAVIOUR_WANDER, BEHAVIOUR_CHASE, PetTagGame, scan_pet_pack,
 )
 from frontengine.ui.dialog.choose_file_dialog import choose_pet, choose_wav_sound
 from frontengine.ui.page.utils import (
@@ -17,7 +18,7 @@ from frontengine.ui.page.utils import (
     resolve_preferred_monitor,
 )
 from frontengine.user_setting.user_setting_file import add_recent_file
-from frontengine.utils.audio_meter.system_audio_meter import system_audio_level
+from frontengine.utils.audio_meter.screen_audio import audio_level_provider_for_screen
 from frontengine.utils.logging.loggin_instance import front_engine_logger
 from frontengine.utils.multi_language.language_wrapper import language_wrapper
 
@@ -36,6 +37,11 @@ class PetSettingUI(QWidget):
         self.ready_to_play = False
         self.pet_image_path: Optional[str] = None
         self.pet_sound_path: Optional[str] = None
+        # 鬼抓人：由本頁統一驅動，寵物只負責套用被指派的角色
+        # Tag game: driven from this page, pets only apply the role they are given.
+        self.tag_game = PetTagGame()
+        self.tag_timer = QTimer(self)
+        self.tag_timer.timeout.connect(self._tick_tag_game)
 
         # Choose file
         self.choose_file_button = QPushButton(
@@ -81,6 +87,9 @@ class PetSettingUI(QWidget):
         self.talk_checkbox.setChecked(True)
         self.sit_checkbox = QCheckBox(language_wrapper.language_word_dict.get("pet_sit_label", "Sit on windows"))
         self.sit_checkbox.setChecked(True)
+        self.tag_checkbox = QCheckBox(
+            language_wrapper.language_word_dict.get("pet_tag_label", "Play tag with each other"))
+        self.tag_checkbox.toggled.connect(self._on_tag_toggled)
 
         # Target monitor + sound volume
         self.target_monitor_label = QLabel(
@@ -93,6 +102,12 @@ class PetSettingUI(QWidget):
         self.volume_combobox.setCurrentText("100%")
         self.audio_react_checkbox = QCheckBox(
             language_wrapper.language_word_dict.get("pet_audio_label", "React to audio"))
+        self.drop_hint_label = QLabel(
+            language_wrapper.language_word_dict.get(
+                "pet_drop_hint",
+                "Tip: drop an image or pet pack onto the pet to change its look, "
+                "or any other file to feed it."))
+        self.drop_hint_label.setWordWrap(True)
 
         # Start
         self.start_button = QPushButton(language_wrapper.language_word_dict.get("pet_start", "Spawn pet"))
@@ -128,6 +143,8 @@ class PetSettingUI(QWidget):
         self.grid_layout.addWidget(self.volume_label, 6, 2)
         self.grid_layout.addWidget(self.volume_combobox, 7, 2)
         self.grid_layout.addWidget(self.audio_react_checkbox, 7, 0)
+        self.grid_layout.addWidget(self.tag_checkbox, 7, 1)
+        self.grid_layout.addWidget(self.drop_hint_label, 8, 0, 1, 3)
 
     def _spawn_pet(self) -> None:
         """建立、顯示並開始移動一隻寵物（供 Start 與右鍵複製共用）。"""
@@ -147,12 +164,16 @@ class PetSettingUI(QWidget):
         )
         pet.clone_requested.connect(self._spawn_pet)
         pet.set_peers_provider(lambda me=pet: self._peer_centers(me))
+        geometry = self._target_geometry()
         if self.audio_react_checkbox.isChecked():
-            pet.set_audio_level_provider(system_audio_level)  # real system output peak meter
+            # 跟隨寵物所在螢幕的音源（比對不到就用系統預設輸出裝置）
+            # Follow the audio of the screen the pet lives on; default endpoint otherwise.
+            pet.set_audio_level_provider(
+                audio_level_provider_for_screen(geometry[1] if geometry is not None else None))
         pet.set_pet_window_flag()
         self.pet_list.append(pet)
         pet.show()
-        geometry = self._target_geometry()
+        self._start_tag_game()
         if geometry is not None:
             pet.setScreen(geometry[1])
             bounds = geometry[0]
@@ -170,17 +191,59 @@ class PetSettingUI(QWidget):
             return None
         return (screen.availableGeometry(), screen)
 
-    def _peer_centers(self, me) -> list:
-        """回傳其他仍存活寵物的中心座標（略過已被銷毀者）。"""
-        centers = []
-        for other in list(self.pet_list):
-            if other is me:
-                continue
+    def _alive_pets(self) -> list:
+        """回傳仍存活的寵物，並把已被銷毀者從清單移除。"""
+        alive = []
+        for pet in list(self.pet_list):
             try:
-                centers.append(other.center())
+                pet.center()
             except RuntimeError:
-                pass  # underlying C++ object already deleted
-        return centers
+                self.pet_list.remove(pet)  # underlying C++ object already deleted
+                continue
+            alive.append(pet)
+        return alive
+
+    def _peer_centers(self, me) -> list:
+        """回傳其他仍存活寵物的中心座標（略過已被銷毀者）。"""
+        return [pet.center() for pet in self._alive_pets() if pet is not me]
+
+    TAG_INTERVAL_MS = 100
+
+    def _on_tag_toggled(self, checked: bool) -> None:
+        """切換鬼抓人：關掉時停錶並把所有寵物放回平常的行為。"""
+        front_engine_logger.info(f"[PetSettingUI] tag game | enabled={checked}")
+        if checked:
+            self._start_tag_game()
+            return
+        self.tag_timer.stop()
+        self.tag_game.reset()
+        for pet in self._alive_pets():
+            pet.apply_tag_role(None)
+
+    def _start_tag_game(self) -> None:
+        """有兩隻以上寵物且已勾選時才需要開錶 / Only run the game with 2+ pets."""
+        if self.tag_checkbox.isChecked() and len(self._alive_pets()) >= 2:
+            if not self.tag_timer.isActive():
+                self.tag_timer.start(self.TAG_INTERVAL_MS)
+
+    def _tick_tag_game(self) -> None:
+        """每一拍把座標餵給遊戲，再把角色發回各隻寵物。"""
+        pets = self._alive_pets()
+        if len(pets) < 2:
+            self.tag_timer.stop()
+            self.tag_game.reset()
+            for pet in pets:
+                pet.apply_tag_role(None)
+            return
+        # 用每隻寵物的物件識別碼當鍵，避免有寵物關閉後索引位移導致「鬼」換人
+        # Key by object identity so closing a pet cannot shift who is "it".
+        by_key = {id(pet): pet for pet in pets}
+        roles = self.tag_game.update({key: pet.center() for key, pet in by_key.items()})
+        tagged = self.tag_game.just_tagged
+        for key, pet in by_key.items():
+            pet.apply_tag_role(roles.get(key))
+            if key == tagged:
+                pet.on_tagged()
 
     def start_play_pet(self) -> None:
         front_engine_logger.info("[PetSettingUI] start_play_pet")
@@ -261,6 +324,7 @@ class PetSettingUI(QWidget):
             "target_monitor": self.target_monitor_combobox.currentText(),
             "volume": self.volume_combobox.currentText(),
             "audio_react": self.audio_react_checkbox.isChecked(),
+            "tag": self.tag_checkbox.isChecked(),
         }
 
     def set_state(self, state: dict) -> None:
@@ -298,3 +362,5 @@ class PetSettingUI(QWidget):
                 self.volume_combobox.setCurrentIndex(index)
         if "audio_react" in state:
             self.audio_react_checkbox.setChecked(bool(state["audio_react"]))
+        if "tag" in state:
+            self.tag_checkbox.setChecked(bool(state["tag"]))