"""Piano item schema metadata and behavior.""" from __future__ import annotations from typing import Callable from ..item_types import ItemUseResult from ..models import WorldItem from .helpers import keep_only_known_params LABEL = "piano" TOOLTIP = "Playable keyboard instrument with multiple synth voices." EDITABLE_PROPERTIES: tuple[str, ...] = ( "title", "instrument", "voiceMode", "octave", "attack", "decay", "release", "brightness", "emitRange", ) CAPABILITIES: tuple[str, ...] = ("editable", "carryable", "deletable", "usable") USE_SOUND: str | None = None EMIT_SOUND: str | None = None USE_COOLDOWN_MS = 1000 EMIT_RANGE = 15 DIRECTIONAL = False DEFAULT_TITLE = "piano" DEFAULT_PARAMS: dict = { "instrument": "piano", "voiceMode": "poly", "octave": 0, "attack": 15, "decay": 45, "release": 35, "brightness": 55, "emitRange": 15, "songId": "unterlandersheimweh", } PARAM_KEYS: tuple[str, ...] = ("instrument", "voiceMode", "octave", "attack", "decay", "release", "brightness", "emitRange", "songId") INSTRUMENT_OPTIONS: tuple[str, ...] = ( "piano", "electric_piano", "guitar", "organ", "bass", "violin", "synth_lead", "brass", "nintendo", "drum_kit", ) VOICE_MODE_OPTIONS: tuple[str, ...] = ("poly", "mono") DEFAULT_ENVELOPE_BY_INSTRUMENT: dict[str, tuple[int, int, int, int, str, int]] = { "piano": (15, 45, 35, 55, "poly", 0), "electric_piano": (12, 40, 30, 62, "poly", 0), "guitar": (8, 35, 25, 50, "poly", 0), "organ": (25, 70, 45, 48, "poly", 0), "bass": (2, 24, 18, 34, "mono", -1), "violin": (22, 75, 55, 58, "mono", 0), "synth_lead": (6, 30, 22, 72, "poly", 0), "brass": (10, 45, 30, 60, "mono", 0), "nintendo": (1, 24, 15, 85, "poly", 0), "drum_kit": (1, 22, 12, 68, "poly", 0), } PROPERTY_METADATA: dict[str, dict[str, object]] = { "title": {"valueType": "text", "tooltip": "Display name spoken and shown for this item.", "maxLength": 80}, "instrument": {"valueType": "list", "tooltip": "Instrument voice used when playing this piano."}, "voiceMode": {"valueType": "list", "tooltip": "Mono plays one note at a time; poly allows chords."}, "octave": { "valueType": "number", "tooltip": "Shifts played notes in octaves. -1 is one octave down.", "range": {"min": -2, "max": 2, "step": 1}, }, "attack": { "valueType": "number", "tooltip": "How quickly notes ramp in. Lower is sharper; higher is softer.", "range": {"min": 0, "max": 100, "step": 1}, }, "decay": { "valueType": "number", "tooltip": "How long notes ring out after the initial hit.", "range": {"min": 0, "max": 100, "step": 1}, }, "release": { "valueType": "number", "tooltip": "How long notes continue after key release.", "range": {"min": 0, "max": 100, "step": 1}, }, "brightness": { "valueType": "number", "tooltip": "Tone brightness; higher values sound brighter.", "range": {"min": 0, "max": 100, "step": 1}, }, "emitRange": { "valueType": "number", "tooltip": "Maximum distance in squares where this piano can be heard.", "range": {"min": 5, "max": 20, "step": 1}, }, } def validate_update(_item: WorldItem, next_params: dict) -> dict: """Validate and normalize piano params.""" # Song references are server-managed and not directly editable from client updates. preserved_song_id = _item.params.get("songId") next_params.pop("songId", None) instrument = str(next_params.get("instrument", "piano")).strip().lower() if instrument not in INSTRUMENT_OPTIONS: raise ValueError(f"instrument must be one of: {', '.join(INSTRUMENT_OPTIONS)}.") previous_instrument = str(_item.params.get("instrument", "piano")).strip().lower() next_params["instrument"] = instrument voice_mode = str(next_params.get("voiceMode", _item.params.get("voiceMode", "poly"))).strip().lower() if voice_mode not in VOICE_MODE_OPTIONS: raise ValueError("voiceMode must be one of: poly, mono.") next_params["voiceMode"] = voice_mode try: octave = int(next_params.get("octave", _item.params.get("octave", 0))) except (TypeError, ValueError) as exc: raise ValueError("octave must be an integer between -2 and 2.") from exc if not (-2 <= octave <= 2): raise ValueError("octave must be between -2 and 2.") next_params["octave"] = octave try: attack = int(next_params.get("attack", 15)) except (TypeError, ValueError) as exc: raise ValueError("attack must be an integer between 0 and 100.") from exc if not (0 <= attack <= 100): raise ValueError("attack must be between 0 and 100.") try: decay = int(next_params.get("decay", 45)) except (TypeError, ValueError) as exc: raise ValueError("decay must be an integer between 0 and 100.") from exc if not (0 <= decay <= 100): raise ValueError("decay must be between 0 and 100.") try: release = int(next_params.get("release", 35)) except (TypeError, ValueError) as exc: raise ValueError("release must be an integer between 0 and 100.") from exc if not (0 <= release <= 100): raise ValueError("release must be between 0 and 100.") try: brightness = int(next_params.get("brightness", 55)) except (TypeError, ValueError) as exc: raise ValueError("brightness must be an integer between 0 and 100.") from exc if not (0 <= brightness <= 100): raise ValueError("brightness must be between 0 and 100.") # When instrument changes, reset envelope to instrument-appropriate defaults. if instrument != previous_instrument: attack, decay, release, brightness, voice_mode, octave = DEFAULT_ENVELOPE_BY_INSTRUMENT.get( instrument, (15, 45, 35, 55, "poly", 0) ) next_params["voiceMode"] = voice_mode next_params["octave"] = octave next_params["attack"] = attack next_params["decay"] = decay next_params["release"] = release next_params["brightness"] = brightness try: emit_range = int(next_params.get("emitRange", 15)) except (TypeError, ValueError) as exc: raise ValueError("emitRange must be an integer between 5 and 20.") from exc if not (5 <= emit_range <= 20): raise ValueError("emitRange must be between 5 and 20.") next_params["emitRange"] = emit_range if isinstance(preserved_song_id, str) and preserved_song_id.strip(): next_params["songId"] = preserved_song_id.strip() return keep_only_known_params(next_params, PARAM_KEYS) def use_item(item: WorldItem, nickname: str, _clock_formatter: Callable[[dict], str]) -> ItemUseResult: """Enter piano play mode for the user who used the item.""" return ItemUseResult( self_message=f"You begin playing {item.title}.", others_message=f"{nickname} begins playing {item.title}.", )