Add spoken spatial clock announcements with top-of-hour mode

server/app/items/types/clock/actions.py

@@ -11,8 +11,8 @@ from ....models import WorldItem
 def use_item(item: WorldItem, nickname: str, clock_formatter: Callable[[dict], str]) -> ItemUseResult:
     """Read current clock time based on item configuration."""
 
-    display_time = clock_formatter(item.params)
+    _display_time = clock_formatter(item.params)
     return ItemUseResult(
-        self_message=f"{item.title} says {display_time}.",
-        others_message=f"{nickname} checks {item.title}. {item.title} says {display_time}.",
+        self_message="",
+        others_message="",
     )

server/app/items/types/clock/definition.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 LABEL = "clock"
 TOOLTIP = "It tells the time. What did you think it did?"
-EDITABLE_PROPERTIES: tuple[str, ...] = ("title", "timeZone", "use24Hour")
+EDITABLE_PROPERTIES: tuple[str, ...] = ("title", "timeZone", "use24Hour", "topOfHourAnnounce")
 CAPABILITIES: tuple[str, ...] = ("editable", "carryable", "deletable", "usable")
 USE_SOUND: str | None = None
 EMIT_SOUND = "sounds/clock.ogg"
@@ -55,11 +55,12 @@ TIME_ZONE_OPTIONS: tuple[str, ...] = (
     "Pacific/Pago_Pago",
     "UTC",
 )
-DEFAULT_PARAMS: dict = {"timeZone": DEFAULT_TIME_ZONE, "use24Hour": False}
-PARAM_KEYS: tuple[str, ...] = ("timeZone", "use24Hour")
+DEFAULT_PARAMS: dict = {"timeZone": DEFAULT_TIME_ZONE, "use24Hour": False, "topOfHourAnnounce": True}
+PARAM_KEYS: tuple[str, ...] = ("timeZone", "use24Hour", "topOfHourAnnounce")
 
 PROPERTY_METADATA: dict[str, dict[str, object]] = {
     "title": {"valueType": "text", "tooltip": "Display name spoken and shown for this item.", "maxLength": 80},
     "timeZone": {"valueType": "list", "tooltip": "Timezone used when the clock speaks time.", "options": list(TIME_ZONE_OPTIONS)},
     "use24Hour": {"valueType": "boolean", "tooltip": "Use 24 hour format instead of AM/PM."},
+    "topOfHourAnnounce": {"valueType": "boolean", "tooltip": "Automatically announce time at the top of each hour."},
 }

server/app/items/types/clock/validator.py

@@ -16,6 +16,10 @@ def validate_update(_item: WorldItem, next_params: dict) -> dict:
     use_24_hour = parse_bool_like_or_none(next_params.get("use24Hour"))
     if use_24_hour is None:
         raise ValueError("use24Hour must be on/off.")
+    top_of_hour_announce = parse_bool_like_or_none(next_params.get("topOfHourAnnounce"))
+    if top_of_hour_announce is None:
+        raise ValueError("topOfHourAnnounce must be on/off.")
     next_params["timeZone"] = time_zone
     next_params["use24Hour"] = use_24_hour
+    next_params["topOfHourAnnounce"] = top_of_hour_announce
     return keep_only_known_params(next_params, PARAM_KEYS)