golem-bridge 1.0.2 → 2.0.0

package/golem.py

@@ -0,0 +1,1093 @@
+#!/usr/bin/env python3
+"""Golem helper - control a live Roblox Studio session from anywhere.
+
+The Studio plugin polls the command channel below and posts results to the
+result channel. This helper sends a command, waits for the matching result,
+and prints it as JSON. Python 3.8+, no dependencies.
+
+Usage:
+    python3 golem.py ping
+    python3 golem.py debug                           # full connection + marketplace diagnostics
+    python3 golem.py exec '{"op":"list","args":{"path":"game"}}'
+    python3 golem.py lua 'return 1+1'
+    python3 golem.py lua - < code.lua
+    python3 golem.py list ServerScriptService
+    python3 golem.py list game --recursive --max 1000
+    python3 golem.py tree game --depth 3
+    python3 golem.py read ServerScriptService/Main
+    python3 golem.py find Coin --class Part --scope Workspace
+    python3 golem.py grep applyDamage --scope ServerScriptService
+    python3 golem.py script ReplicatedStorage Config --class ModuleScript < source.lua
+    python3 golem.py delete Workspace/OldPart
+    python3 golem.py move Workspace/Part ServerStorage
+    python3 golem.py selection --set Workspace/Part
+    python3 golem.py waypoint "before refactor"
+    python3 golem.py turn begin
+    python3 golem.py turn end --note "short reply the user reads in the chat"
+    python3 golem.py place <path> <x,y,z> [--orientation x,y,z]   # absolute position
+    python3 golem.py paint <path> [--color #RRGGBB] [--material Grass] [--transparency 0.2]
+    python3 golem.py rename <path> <newName>
+    python3 golem.py look <path> [--distance 40]     # aim the editor camera
+    python3 golem.py count [scope] [--class Part]    # quick instance count
+    python3 golem.py undo                            # one Studio undo step
+    python3 golem.py anchor <path> [--off]           # anchor parts (models: all parts)
+    python3 golem.py collide <path> [--off]          # toggle collision
+    python3 golem.py light <path> [--type point|spot|surface] [--color #RRGGBB] [--range 30] [--brightness 1]
+    python3 golem.py sound <parent> <audioId> [--volume 0.5] [--loop] [--play] [--name N]
+    python3 golem.py scatter <path> --count 20 --radius 60 [--y-jitter 2] [--parent P]
+    python3 golem.py weld <path>                        # weld a model's parts together
+    python3 golem.py hitbox <path> [--padding 1] [--name N] [--collide]
+    python3 golem.py prompt <path> "Chop" [--object Tree] [--hold 0.5] [--distance 8]
+    python3 golem.py particles <path> leaves|sparks|smoke|magic|fire|snow|rain|bubbles|dust|confetti|fireflies [--rate N] [--color #RRGGBB]
+    python3 golem.py sign "Camp rules: no griefing" [--position x,y,z] [--parent P] [--size 6,4,0.5]
+    python3 golem.py attr <path> [--set k=v ...] [--clear k ...]     # Studio attributes
+    python3 golem.py beam <FROM> <TO> [--color #RRGGBB] [--width 0.4] [--curve 0]   # glowing beam between parts
+    python3 golem.py trail <path> [--color #RRGGBB] [--lifetime 0.6]  # motion trail on a moving part
+    python3 golem.py explosion [--position x,y,z] [--radius 8]        # one-shot boom (visual only)
+    python3 golem.py ui_screen <name> [--parent P] [--order N]        # ScreenGui under StarterGui
+    python3 golem.py ui_frame <parent> <name> [--position 0,0,0,0] [--size 1,0,1,0] [--anchor 0,0]
+                       [--color #RRGGBB] [--radius 8] [--transparency 0] [--clip]
+    python3 golem.py ui_label <parent> <name> --text "..." [--align left|center|right] [--wrap]
+                       [--color #RRGGBB] [--font medium] [--text-size 16]
+    python3 golem.py ui_button <parent> <name> --text "..." [--color #RRGGBB] [--text-color #RRGGBB]
+    python3 golem.py ui_input <parent> <name> [--placeholder "..."] [--background #RRGGBB]
+    python3 golem.py ui_image <parent> <name> --asset <assetId> [--scale fit|stretch|tile]
+    python3 golem.py ui_list <parent> [--direction vertical|horizontal] [--padding 8]
+                       [--halign left|center|right] [--valign top|middle|bottom]
+    python3 golem.py play [--mode play|run]               # start play-testing the game
+    python3 golem.py stop                                 # stop the play test
+    python3 golem.py logs [--all] [--limit N] [--since TS]  # output log (errors+warnings by default)
+    python3 golem.py tag <path> --add Choppable [--remove Old]       # + find --tag Choppable
+    python3 golem.py match <from> <to...>              # copy color/material onto targets
+    python3 golem.py search <query> [--category C] [--limit N]   # marketplace (runs directly, no Studio)
+    python3 golem.py info <assetId>                   # asset details (runs directly, no Studio)
+    python3 golem.py insert <assetId> [parent]        # place a FREE marketplace asset into the place
+
+Add --timeout N (seconds, default 120) to any command.
+Exit codes: 0 = ok, 1 = Studio reported an error, 2 = transport/usage error.
+"""
+import argparse
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+FIREBASE_DB = os.environ.get("AIB_FIREBASE_DB", "__DB_URL__")
+CHANNEL = os.environ.get("AIB_CHANNEL", "__CHANNEL_ID__")
+CMD_URL = "%s/channels/%s/cmd" % (FIREBASE_DB, CHANNEL)
+RES_URL = "%s/channels/%s/res" % (FIREBASE_DB, CHANNEL)
+POLL_INTERVAL = float(os.environ.get("AIB_POLL_INTERVAL", "2"))
+
+
+def vec3(s):
+    parts = [float(v) for v in str(s).replace(",", " ").split()]
+    if not parts:
+        raise ValueError("empty vector")
+    if len(parts) == 1:
+        return {"x": parts[0], "y": 0.0, "z": 0.0}
+    if len(parts) != 3:
+        raise ValueError("expected x,y,z")
+    return {"x": parts[0], "y": parts[1], "z": parts[2]}
+
+
+def _post(url, body, timeout=30):
+    req = urllib.request.Request(url, data=body.encode("utf-8"),
+                                 headers={"Content-Type": "application/json"}, method="POST")
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        return json.loads(resp.read().decode("utf-8", "replace"))
+
+
+def _get(url, timeout=60):
+    with urllib.request.urlopen(url, timeout=timeout) as resp:
+        return resp.read().decode("utf-8", "replace")
+
+
+MARKETPLACE_CATEGORIES = {
+    "model": "Model", "models": "Model", "mesh": "MeshPart", "meshes": "MeshPart",
+    "meshpart": "MeshPart", "decal": "Decal", "decals": "Decal", "image": "Decal",
+    "images": "Decal", "picture": "Decal", "texture": "Decal", "audio": "Audio",
+    "sound": "Audio", "sounds": "Audio", "music": "Audio", "video": "Video",
+    "videos": "Video", "plugin": "Plugin", "plugins": "Plugin",
+}
+ASSET_TYPE_NAMES = {1: "Image", 3: "Audio", 4: "Mesh", 9: "Decal", 10: "Model",
+                    18: "Video", 19: "Font", 40: "MeshPart"}
+
+
+def marketplace_get(url, timeout=20):
+    req = urllib.request.Request(url, headers={
+        "Accept": "application/json", "User-Agent": "Golem-aib/1.0"})
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        return json.loads(resp.read().decode("utf-8", "replace"))
+
+
+def marketplace_search(query, category="model", limit=10, cursor=None):
+    asset_type = MARKETPLACE_CATEGORIES.get(str(category or "model").lower())
+    if asset_type is None:
+        raise ValueError("unknown category '%s' (valid: model, mesh, image, audio, video, plugin)" % category)
+    try:
+        limit = max(1, min(int(limit or 10), 50))
+    except (TypeError, ValueError):
+        limit = 10
+    url = ("https://apis.roblox.com/toolbox-service/v1/marketplace/%s?keyword=%s&limit=%d"
+           % (asset_type, urllib.parse.quote(str(query)), limit))
+    if cursor:
+        url += "&cursor=" + urllib.parse.quote(str(cursor))
+    data = marketplace_get(url)
+    ids = [it["id"] for it in (data.get("data") or [])
+           if isinstance(it, dict) and it.get("id") is not None]
+    details, thumbs = {}, {}
+    for i, aid in enumerate(ids[:12]):
+        try:
+            details[aid] = marketplace_get("https://economy.roblox.com/v2/assets/%s/details" % aid)
+        except Exception:
+            pass
+        if i < 11:
+            time.sleep(0.4)  # the economy API rate limits hard
+    if ids:
+        try:
+            tdata = marketplace_get(
+                "https://thumbnails.roblox.com/v1/assets?assetIds=%s&size=420x420&format=Png"
+                % ",".join(str(x) for x in ids[:12]))
+            for th in (tdata.get("data") or []):
+                if isinstance(th, dict) and th.get("targetId") is not None:
+                    thumbs[th["targetId"]] = th
+        except Exception:
+            pass
+    results = []
+    for aid in ids:
+        d, th = details.get(aid), thumbs.get(aid)
+        entry = {"id": aid, "category": asset_type}
+        if isinstance(d, dict):
+            entry["name"] = d.get("Name")
+            entry["assetTypeId"] = d.get("AssetTypeId")
+            entry["assetType"] = ASSET_TYPE_NAMES.get(d.get("AssetTypeId"))
+            creator = d.get("Creator")
+            if isinstance(creator, dict):
+                entry["creator"] = creator.get("Name")
+            if d.get("PriceInRobux") is not None:
+                entry["priceInRobux"] = d["PriceInRobux"]
+            if d.get("IsForSale") is not None:
+                entry["forSale"] = d["IsForSale"]
+            desc = d.get("Description")
+            if isinstance(desc, str) and desc:
+                entry["description"] = desc[:280]
+        else:
+            entry["detailsUnavailable"] = True
+        if isinstance(th, dict):
+            entry["thumbnail"] = th.get("imageUrl")
+            entry["thumbnailState"] = th.get("state")
+        results.append(entry)
+    out = {"totalResults": data.get("totalResults"), "results": results}
+    if data.get("nextPageCursor"):
+        out["nextPageCursor"] = data["nextPageCursor"]
+    return out
+
+
+def marketplace_info(asset_id):
+    d = marketplace_get("https://economy.roblox.com/v2/assets/%s/details" % int(asset_id))
+    out = {"id": int(asset_id)}
+    if isinstance(d, dict):
+        out["name"] = d.get("Name")
+        out["assetTypeId"] = d.get("AssetTypeId")
+        out["assetType"] = ASSET_TYPE_NAMES.get(d.get("AssetTypeId"))
+        creator = d.get("Creator")
+        if isinstance(creator, dict):
+            out["creator"] = creator.get("Name")
+        if d.get("PriceInRobux") is not None:
+            out["priceInRobux"] = d["PriceInRobux"]
+        if d.get("IsForSale") is not None:
+            out["forSale"] = d["IsForSale"]
+        desc = d.get("Description")
+        if isinstance(desc, str):
+            out["description"] = desc[:1000]
+    try:
+        tdata = marketplace_get(
+            "https://thumbnails.roblox.com/v1/assets?assetIds=%d&size=420x420&format=Png" % int(asset_id))
+        if isinstance(tdata.get("data"), list) and tdata["data"]:
+            out["thumbnail"] = tdata["data"][0].get("imageUrl")
+            out["thumbnailState"] = tdata["data"][0].get("state")
+    except Exception:
+        pass
+    return out
+
+
+def _marketplace_via_plugin():
+    return os.environ.get("AIB_MARKETPLACE", "").lower() == "plugin"
+
+
+def call(op, args=None, timeout=120):
+    if str(FIREBASE_DB).startswith("__") or str(CHANNEL).startswith("__"):
+        return {"ok": False, "error": "helper not configured (channel never stamped) - re-run: npx golem-bridge connect <channelId>"}
+    cid = "c%d" % time.time_ns()
+    payload = json.dumps({"id": cid, "op": op, "args": args or {}, "ts": int(time.time())})
+    try:
+        pub = None
+        for attempt in range(4):
+            try:
+                pub = _post(CMD_URL + ".json", payload)
+                break
+            except urllib.error.HTTPError as exc:
+                if exc.code == 429 and attempt < 3:
+                    time.sleep(float(exc.headers.get("Retry-After") or (5 * (attempt + 1))))
+                else:
+                    raise
+    except urllib.error.HTTPError as exc:
+        return {"ok": False, "error": "relay rejected the command: HTTP %d: %s" % (exc.code, exc.read()[:200])}
+    except Exception as exc:
+        return {"ok": False, "error": "cannot reach the relay (%s) - check internet/DNS" % exc}
+
+    since_key = str((pub or {}).get("name") or "") or None
+    deadline = time.time() + timeout
+    attempt = 0
+    while time.time() < deadline:
+        try:
+            body = _get(RES_URL + ".json?shallow=true")  # keys only - tiny
+            attempt = 0
+            keys = json.loads(body) if body != "null" else {}
+            if isinstance(keys, dict):
+                for key in sorted(k for k in keys if since_key is None or k > since_key):
+                    since_key = key
+                    raw = _get(RES_URL + "/" + key + ".json")
+                    try:
+                        entry = json.loads(raw)
+                    except ValueError:
+                        continue
+                    if isinstance(entry, dict) and entry.get("id") == cid:
+                        if entry.get("resultEncoded") and isinstance(entry.get("result"), str):
+                            try:
+                                entry["result"] = json.loads(entry["result"])
+                            except ValueError:
+                                pass
+                            entry.pop("resultEncoded", None)
+                        return entry
+        except urllib.error.HTTPError as exc:
+            if exc.code == 429:
+                time.sleep(float(exc.headers.get("Retry-After") or 6))
+            else:
+                time.sleep(2)
+            continue
+        except Exception:
+            attempt += 1
+            time.sleep(min(15.0, 0.5 * (2 ** min(attempt, 5))))
+            continue
+        time.sleep(POLL_INTERVAL)
+    return {
+        "ok": False,
+        "error": "timed out after %ds waiting for Studio to answer '%s'. Is Roblox Studio open with the Golem "
+                 "plugin connected to the relay?" % (timeout, op),
+    }
+
+
+def status():
+    """Read the relay channel's recent history and decode the plugin's liveness
+    beacons. No Studio round-trip needed."""
+    if str(CMD_URL).startswith("__") or str(RES_URL).startswith("__"):  # no literal placeholders - see call()
+        return {"ok": False, "error": "helper not configured (channel never stamped) - re-run: npx golem-bridge connect <channelId>"}
+    try:
+        beacon_body = _get(
+            "%s/channels/%s/beacons.json?orderBy=%s&limitToLast=5"
+            % (FIREBASE_DB, CHANNEL, urllib.parse.quote('"$key"')), timeout=30)
+        beacon_data = json.loads(beacon_body) if beacon_body != "null" else {}
+        if not isinstance(beacon_data, dict):
+            beacon_data = {}
+        res_body = _get(RES_URL + ".json?shallow=true", timeout=30)
+        res_keys = json.loads(res_body) if res_body != "null" else {}
+        if not isinstance(res_keys, dict):
+            res_keys = {}
+        results = sum(1 for v in res_keys.values() if v is True)
+    except Exception as exc:
+        return {"ok": False, "error": "cannot read the relay channel: %s" % exc}
+    now = time.time()
+    beacons = []
+    for entry in beacon_data.values():
+        if isinstance(entry, dict) and entry.get("op") in ("hello", "paused", "revoked"):
+            beacons.append((float(entry.get("ts") or 0), entry))
+    if not beacons:
+        if results:
+            verdict = ("no beacons, but %d cached result(s) - Studio is not running or runs an "
+                       "older plugin; ask the user to fully restart Studio with the current plugin" % results)
+        else:
+            verdict = ("result channel is empty - the plugin has never posted here: Studio is closed "
+                       "or was not restarted after a plugin update")
+        return {"ok": True, "beacon": None, "ageSeconds": None, "recentResults": results, "verdict": verdict}
+    ts, beacon = max(beacons, key=lambda b: b[0])
+    age = max(0, int(now - ts))
+    op = beacon.get("op")
+    ver = beacon.get("v", "?")
+    if age <= 900:
+        verdict = "plugin is LIVE (v%s, hello beacon %ds ago) - it should answer commands" % (ver, age)
+    else:
+        verdict = ("last hello was %d min ago (v%s) - Studio may be closed or hung since then; ask the "
+                   "user to check the Golem window" % (age // 60, ver))
+    return {"ok": True, "beacon": beacon, "ageSeconds": age, "recentResults": results, "verdict": verdict}
+
+
+def _turn_reminder(entry):
+    if isinstance(entry, dict) and entry.get("turnOpen"):
+        helper = (sys.argv and sys.argv[0]) or "golem.py"
+        n = entry.get("turnTools")
+        head = (">> TURN STILL OPEN (%d tools) - do NOT reply yet." % n
+                if isinstance(n, int) else ">> TURN STILL OPEN - do NOT reply yet.")
+        print(head + " When this task is done, close it with:\n"
+              '>>    python3 "%s" turn end --note "your reply"' % helper,
+              file=sys.stderr)
+
+
+def _out(data, as_json=False, raw_field=None):
+    if data.get("ok"):
+        if raw_field and not as_json:
+            result = data.get("result") or {}
+            if isinstance(result.get(raw_field), str):
+                sys.stdout.write(result[raw_field])
+                if not result[raw_field].endswith("\n"):
+                    sys.stdout.write("\n")
+                _turn_reminder(data)
+                return 0
+        print(json.dumps(data, indent=2))
+        _turn_reminder(data)
+        return 0
+    print(json.dumps(data, indent=2), file=sys.stderr)
+    _turn_reminder(data)
+    return 1 if "error" in data else 2
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Golem helper for Roblox Studio", prog="golem.py")
+    ap.add_argument("--timeout", type=float, default=120.0, help="seconds to wait for Studio (default 120)")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("ping", help="health check - is Studio connected?")
+
+    sub.add_parser("debug", help="diagnostics: relay round-trip, marketplace reachability, HTTP state")
+
+    sub.add_parser("status", help="is the plugin alive, paused, or the link revoked? (no Studio needed)")
+
+    p = sub.add_parser("exec", help="send a raw op JSON: {\"op\":..., \"args\":...}")
+    p.add_argument("json")
+
+    p = sub.add_parser("lua", help="run Lua inside Studio (code arg, or - for stdin)")
+    p.add_argument("code", nargs="?")
+    p.add_argument("-", dest="from_stdin", action="store_true")
+
+    p = sub.add_parser("list", help="children of a path")
+    p.add_argument("path", nargs="?", default="game")
+    p.add_argument("--recursive", action="store_true")
+    p.add_argument("--max", type=int)
+
+    p = sub.add_parser("tree", help="recursive tree of a path")
+    p.add_argument("path", nargs="?", default="game")
+    p.add_argument("--depth", type=int)
+
+    p = sub.add_parser("read", help="read an instance (script source by default, --json for full record)")
+    p.add_argument("path")
+    p.add_argument("--json", action="store_true", dest="as_json")
+    p.add_argument("--props", help="comma-separated extra properties")
+
+    p = sub.add_parser("find", help="find instances by name or --tag")
+    p.add_argument("query", nargs="?", default="")
+    p.add_argument("--class", dest="cls")
+    p.add_argument("--scope", default="game")
+    p.add_argument("--max", type=int)
+    p.add_argument("--exact", action="store_true")
+    p.add_argument("--tag", help="find by CollectionService tag instead of name")
+
+    p = sub.add_parser("grep", help="search script sources")
+    p.add_argument("pattern")
+    p.add_argument("--scope", default="game")
+    p.add_argument("--max", type=int)
+    p.add_argument("-i", action="store_true", dest="icase", help="case-insensitive")
+
+    p = sub.add_parser("script", help="create/update a script (source from stdin or --source)")
+    p.add_argument("parent")
+    p.add_argument("name")
+    p.add_argument("--class", dest="cls", default="Script",
+                   choices=["Script", "LocalScript", "ModuleScript"])
+    p.add_argument("--mode", choices=["create", "update", "replace"], default="create")
+    p.add_argument("--source")
+
+    p = sub.add_parser("delete", help="delete instances")
+    p.add_argument("paths", nargs="+")
+
+    p = sub.add_parser("move", help="reparent an instance")
+    p.add_argument("path")
+    p.add_argument("parent")
+
+    p = sub.add_parser("selection", help="read or set the Studio selection")
+    p.add_argument("--set", help="comma-separated paths")
+    p.add_argument("--clear", action="store_true")
+
+    p = sub.add_parser("waypoint", help="set an undo checkpoint")
+    p.add_argument("label", nargs="?", default="bridge")
+
+    p = sub.add_parser("say", help="post a message to the user's Studio chat (closes the turn)")
+    p.add_argument("text")
+
+    p = sub.add_parser("turn", help="mark work turns: begin ... tools ... end --note (required protocol)")
+    p.add_argument("action", choices=["begin", "end"])
+    p.add_argument("--note", help="the user-facing reply, posted when the turn ends")
+
+    p = sub.add_parser("rotate", help="rotate: --axis y --degrees 90 (relative) or --set 0,90,0 (absolute)")
+    p.add_argument("path")
+    p.add_argument("--axis", help="x|y|z|up|right|forward (or x,y,z vector)")
+    p.add_argument("--degrees", type=float)
+    p.add_argument("--set", dest="absolute", help="absolute orientation x,y,z in degrees")
+    p.add_argument("--space", choices=["world", "local"], default="world")
+
+    p = sub.add_parser("face", help="aim an instance's axis at a world point (keeps position)")
+    p.add_argument("path")
+    p.add_argument("target", help="x,y,z world position to face")
+    p.add_argument("--axis", default="forward", help="forward (default) | up | right")
+
+    p = sub.add_parser("shift", help="move by an offset in studs (world or local)")
+    p.add_argument("path")
+    p.add_argument("offset", help="x,y,z studs")
+    p.add_argument("--space", choices=["world", "local"], default="world")
+
+    p = sub.add_parser("scale", help="scale a part/model by a relative factor")
+    p.add_argument("path")
+    p.add_argument("factor", type=float)
+
+    p = sub.add_parser("duplicate", help="clone an instance (optionally N times with spacing)")
+    p.add_argument("path")
+    p.add_argument("--count", type=int, default=1)
+    p.add_argument("--offset", help="x,y,z applied per copy (copy i gets offset*i)")
+    p.add_argument("--parent")
+    p.add_argument("--name")
+
+    p = sub.add_parser("group", help="wrap instances into a Model")
+    p.add_argument("paths", nargs="+")
+    p.add_argument("--name", default="Group")
+    p.add_argument("--parent")
+
+    p = sub.add_parser("pivot", help="set a model/part pivot (what it rotates around)")
+    p.add_argument("path")
+    p.add_argument("--position", help="x,y,z world position")
+    p.add_argument("--orientation", help="x,y,z degrees")
+
+    p = sub.add_parser("place", help="absolute position via pivot (parts and models)")
+    p.add_argument("path")
+    p.add_argument("position", help="x,y,z world position")
+    p.add_argument("--orientation", help="x,y,z degrees")
+
+    p = sub.add_parser("paint", help="set color/material/transparency/reflectance on parts")
+    p.add_argument("paths", nargs="+")
+    p.add_argument("--color", help="#RRGGBB")
+    p.add_argument("--material", help="Grass, Neon, WoodPlanks, ...")
+    p.add_argument("--transparency", type=float)
+    p.add_argument("--reflectance", type=float)
+
+    p = sub.add_parser("rename", help="rename an instance")
+    p.add_argument("path")
+    p.add_argument("name")
+
+    p = sub.add_parser("look", help="aim the Studio editor camera at a path")
+    p.add_argument("path")
+    p.add_argument("--distance", type=float, default=30)
+
+    p = sub.add_parser("count", help="count instances (cheap, no payloads)")
+    p.add_argument("scope", nargs="?", default="game")
+    p.add_argument("--class", dest="cls")
+
+    sub.add_parser("undo", help="one Studio undo step (Ctrl+Z)")
+
+    p = sub.add_parser("anchor", help="anchor parts in place (models: all their parts)")
+    p.add_argument("paths", nargs="+")
+    p.add_argument("--off", action="store_true", help="unanchor instead of anchor")
+
+    p = sub.add_parser("collide", help="enable part collision (models: all their parts)")
+    p.add_argument("paths", nargs="+")
+    p.add_argument("--off", action="store_true", help="disable collision instead of enabling")
+
+    p = sub.add_parser("light", help="add or update a light inside a part")
+    p.add_argument("path")
+    p.add_argument("--type", dest="light_type", default="point", choices=["point", "spot", "surface"])
+    p.add_argument("--color")
+    p.add_argument("--range", type=float)
+    p.add_argument("--brightness", type=float)
+    p.add_argument("--shadows", action="store_true")
+
+    p = sub.add_parser("sound", help="add a Sound to a parent, optionally play it")
+    p.add_argument("parent")
+    p.add_argument("id")
+    p.add_argument("--volume", type=float)
+    p.add_argument("--loop", action="store_true")
+    p.add_argument("--play", action="store_true")
+    p.add_argument("--name")
+
+    p = sub.add_parser("weld", help="weld a model's parts together with WeldConstraints")
+    p.add_argument("paths", nargs="+")
+
+    p = sub.add_parser("hitbox", help="invisible hitbox part sized to a target")
+    p.add_argument("path")
+    p.add_argument("--padding", type=float, default=0.5)
+    p.add_argument("--name")
+    p.add_argument("--collide", action="store_true", help="make the hitbox collidable")
+
+    p = sub.add_parser("prompt", help="add a ProximityPrompt to a part (Press E to ...)")
+    p.add_argument("path")
+    p.add_argument("action")
+    p.add_argument("--object", help="title above the prompt (e.g. the object's name)")
+    p.add_argument("--hold", type=float, default=0)
+    p.add_argument("--distance", type=float, default=8)
+
+    p = sub.add_parser("particles", help="attach a particle preset to a part")
+    p.add_argument("path")
+    p.add_argument("preset", choices=["leaves", "sparks", "smoke", "magic", "fire",
+                                    "snow", "rain", "bubbles", "dust", "confetti", "fireflies"])
+    p.add_argument("--rate", type=float)
+    p.add_argument("--color")
+
+    p = sub.add_parser("sign", help="place a readable wooden sign")
+    p.add_argument("text")
+    p.add_argument("--position")
+    p.add_argument("--parent")
+    p.add_argument("--size")
+    p.add_argument("--name")
+
+    p = sub.add_parser("beam", help="glowing beam between two parts")
+    p.add_argument("from")  # keyword name; read with getattr(ns, "from")
+    p.add_argument("to")
+    p.add_argument("--color")
+    p.add_argument("--width", type=float)
+    p.add_argument("--curve", type=float)
+    p.add_argument("--name")
+
+    p = sub.add_parser("trail", help="motion trail on a moving part")
+    p.add_argument("path")
+    p.add_argument("--color")
+    p.add_argument("--lifetime", type=float)
+    p.add_argument("--name")
+
+    p = sub.add_parser("explosion", help="one-shot explosion (visual only)")
+    p.add_argument("--position")
+    p.add_argument("--radius", type=float)
+
+    p = sub.add_parser("ui_screen", help="create a ScreenGui under StarterGui")
+    p.add_argument("name")
+    p.add_argument("--parent")
+    p.add_argument("--order", type=int)
+
+    p = sub.add_parser("ui_frame", help="rounded panel/frame")
+    p.add_argument("parent")
+    p.add_argument("name")
+    p.add_argument("--position")
+    p.add_argument("--size")
+    p.add_argument("--anchor")
+    p.add_argument("--color")
+    p.add_argument("--transparency", type=float)
+    p.add_argument("--radius", type=int)
+    p.add_argument("--clip", action="store_true")
+
+    p = sub.add_parser("ui_label", help="text label")
+    p.add_argument("parent")
+    p.add_argument("name")
+    p.add_argument("--text")
+    p.add_argument("--position")
+    p.add_argument("--size")
+    p.add_argument("--anchor")
+    p.add_argument("--color")
+    p.add_argument("--align")
+    p.add_argument("--font")
+    p.add_argument("--text-size", type=int)
+    p.add_argument("--wrap", action="store_true")
+
+    p = sub.add_parser("ui_button", help="text button")
+    p.add_argument("parent")
+    p.add_argument("name")
+    p.add_argument("--text")
+    p.add_argument("--position")
+    p.add_argument("--size")
+    p.add_argument("--anchor")
+    p.add_argument("--color")
+    p.add_argument("--text-color")
+    p.add_argument("--radius", type=int)
+    p.add_argument("--font")
+    p.add_argument("--text-size", type=int)
+
+    p = sub.add_parser("ui_input", help="TextBox the player can type into")
+    p.add_argument("parent")
+    p.add_argument("name")
+    p.add_argument("--placeholder")
+    p.add_argument("--text")
+    p.add_argument("--position")
+    p.add_argument("--size")
+    p.add_argument("--color")
+    p.add_argument("--background")
+    p.add_argument("--radius", type=int)
+    p.add_argument("--text-size", type=int)
+
+    p = sub.add_parser("ui_image", help="ImageLabel from a Roblox asset id")
+    p.add_argument("parent")
+    p.add_argument("name")
+    p.add_argument("--asset")
+    p.add_argument("--position")
+    p.add_argument("--size")
+    p.add_argument("--scale")
+
+    p = sub.add_parser("ui_list", help="UIListLayout that auto-arranges a container's children")
+    p.add_argument("parent")
+    p.add_argument("--direction")
+    p.add_argument("--padding", type=int)
+    p.add_argument("--halign")
+    p.add_argument("--valign")
+
+    p = sub.add_parser("play", help="start play-testing the game (client when possible, Run mode fallback)")
+    p.add_argument("--mode", choices=["play", "run"])
+
+    p = sub.add_parser("stop", help="stop the running play test")
+
+    p = sub.add_parser("logs", help="read Studio output - errors and warnings from the play test")
+    p.add_argument("--all", action="store_true", help="include info/print messages too")
+    p.add_argument("--limit", type=int)
+    p.add_argument("--since", type=float, help="unix timestamp floor (default: when the test started)")
+
+    p = sub.add_parser("attr", help="read/set/clear Studio attributes on an instance")
+    p.add_argument("path")
+    p.add_argument("--set", action="append", metavar="K=V")
+    p.add_argument("--clear", action="append", metavar="K")
+
+    p = sub.add_parser("tag", help="add/remove CollectionService tags")
+    p.add_argument("paths", nargs="+")
+    p.add_argument("--add", action="append", metavar="TAG")
+    p.add_argument("--remove", action="append", metavar="TAG")
+
+    p = sub.add_parser("match", help="copy color/material/transparency from one part onto targets")
+    p.add_argument("from_path")
+    p.add_argument("to", nargs="+")
+
+    p = sub.add_parser("scatter", help="scatter N copies of a template in a disc around it")
+    p.add_argument("path")
+    p.add_argument("--count", type=int, default=10)
+    p.add_argument("--radius", type=float, default=20)
+    p.add_argument("--y-jitter", dest="y_jitter", type=float, default=0)
+    p.add_argument("--parent")
+    p.add_argument("--name")
+
+    p = sub.add_parser("terrain", help="fill or clear terrain (block or ball)")
+    p.add_argument("--action", choices=["fill", "clear"], default="fill")
+    p.add_argument("--shape", choices=["block", "ball"], default="block")
+    p.add_argument("--position", required=True, help="x,y,z center")
+    p.add_argument("--size", help="x,y,z (block)")
+    p.add_argument("--radius", type=float, help="ball radius")
+    p.add_argument("--material", default="Grass")
+
+    p = sub.add_parser("search", help="search the Roblox Creator Store (models, meshes, images, audio)")
+    p.add_argument("query")
+    p.add_argument("--category", default="model", help="model|mesh|image|audio|video|plugin")
+    p.add_argument("--limit", type=int)
+    p.add_argument("--cursor", help="nextPageCursor from a previous search")
+
+    p = sub.add_parser("info", help="details + thumbnail for one marketplace asset")
+
+    p.add_argument("id")
+
+    p = sub.add_parser("insert", help="insert a marketplace asset into the place")
+    p.add_argument("id")
+    p.add_argument("parent", nargs="?", default="Workspace")
+    p.add_argument("--name")
+
+    p = sub.add_parser("apply", help="apply an asset id to a property (Image, Texture, SoundId, MeshId...)")
+    p.add_argument("id")
+    p.add_argument("path")
+    p.add_argument("prop")
+
+    ns = ap.parse_args()
+    cmd = ns.cmd
+    timeout = ns.timeout
+
+    if cmd == "ping":
+        sys.exit(_out(call("ping", {}, timeout=max(timeout, 60))))
+    if cmd == "debug":
+        sys.exit(_out(call("debug", {}, timeout=max(timeout, 90))))
+    if cmd == "status":
+        sys.exit(_out(status()))
+    if cmd == "exec":
+        try:
+            payload = json.loads(ns.json)
+        except ValueError as exc:
+            print("invalid JSON: %s" % exc, file=sys.stderr)
+            sys.exit(2)
+        if not isinstance(payload, dict) or "op" not in payload:
+            print('JSON must be an object with an "op" key', file=sys.stderr)
+            sys.exit(2)
+        sys.exit(_out(call(payload["op"], payload.get("args") or {}, timeout)))
+    if cmd == "lua":
+        code = ns.code
+        if ns.from_stdin or (code is None and not sys.stdin.isatty()):
+            code = sys.stdin.read()
+        if not code:
+            print("no Lua code given (pass it as an argument or pipe it in)", file=sys.stderr)
+            sys.exit(2)
+        sys.exit(_out(call("run", {"code": code}, timeout=timeout)))
+    if cmd == "list":
+        args = {"path": ns.path}
+        if ns.recursive:
+            args["recursive"] = True
+        if ns.max:
+            args["max"] = ns.max
+        sys.exit(_out(call("list", args, timeout)))
+    if cmd == "tree":
+        args = {"path": ns.path, "depth": ns.depth or 2}
+        sys.exit(_out(call("tree", args, timeout)))
+    if cmd == "read":
+        args = {"path": ns.path}
+        if ns.props:
+            args["props"] = [p.strip() for p in ns.props.split(",") if p.strip()]
+        sys.exit(_out(call("read", args, timeout), as_json=ns.as_json, raw_field="source"))
+    if cmd == "find":
+        args = {"scope": ns.scope}
+        if ns.tag:
+            args["tag"] = ns.tag
+        else:
+            args["query"] = ns.query
+        if ns.cls:
+            args["class"] = ns.cls
+        if ns.max:
+            args["max"] = ns.max
+        if ns.exact:
+            args["exact"] = True
+        sys.exit(_out(call("find", args, timeout)))
+    if cmd == "grep":
+        args = {"pattern": ns.pattern, "scope": ns.scope}
+        if ns.max:
+            args["max"] = ns.max
+        if ns.icase:
+            args["caseSensitive"] = False
+        sys.exit(_out(call("grep", args, timeout)))
+    if cmd == "script":
+        source = ns.source
+        if source is None and not sys.stdin.isatty():
+            source = sys.stdin.read()
+        if source is None:
+            print("pass the script source via stdin (heredoc/pipe) or --source", file=sys.stderr)
+            sys.exit(2)
+        sys.exit(_out(call("script", {
+            "parent": ns.parent, "name": ns.name, "class": ns.cls, "mode": ns.mode, "source": source,
+        }, timeout)))
+    if cmd == "delete":
+        sys.exit(_out(call("delete", {"paths": ns.paths}, timeout)))
+    if cmd == "move":
+        sys.exit(_out(call("move", {"path": ns.path, "parent": ns.parent}, timeout)))
+    if cmd == "selection":
+        args = {}
+        if ns.clear:
+            args["clear"] = True
+        elif ns.set:
+            args["set"] = [p.strip() for p in ns.set.split(",") if p.strip()]
+        sys.exit(_out(call("selection", args, timeout)))
+    if cmd == "search":
+        if not _marketplace_via_plugin():
+            err = None
+            try:
+                result = marketplace_search(ns.query, ns.category, ns.limit, ns.cursor)
+            except Exception as exc:
+                result, err = None, "marketplace search failed: %s" % exc
+            if err is None:
+                sys.exit(_out({"ok": True, "op": "search", "result": result}))
+            sys.exit(_out({"ok": False, "op": "search", "error": err}))
+        args = {"query": ns.query, "category": ns.category}
+        if ns.limit:
+            args["limit"] = ns.limit
+        if ns.cursor:
+            args["cursor"] = ns.cursor
+        sys.exit(_out(call("search_assets", args, timeout=max(timeout, 180))))
+    if cmd == "info":
+        if not _marketplace_via_plugin():
+            err = None
+            try:
+                result = marketplace_info(ns.id)
+            except Exception as exc:
+                result, err = None, "asset info failed: %s" % exc
+            if err is None:
+                sys.exit(_out({"ok": True, "op": "info", "result": result}))
+            sys.exit(_out({"ok": False, "op": "info", "error": err}))
+        sys.exit(_out(call("asset_info", {"id": ns.id}, timeout=max(timeout, 180))))
+    if cmd == "insert":
+        args = {"id": ns.id, "parent": ns.parent}
+        if ns.name:
+            args["name"] = ns.name
+        sys.exit(_out(call("insert_asset", args, timeout=max(timeout, 300))))
+    if cmd == "apply":
+        sys.exit(_out(call("apply_asset", {"id": ns.id, "path": ns.path, "prop": ns.prop}, timeout=timeout)))
+    if cmd == "say":
+        sys.exit(_out(call("say", {"text": ns.text}, timeout)))
+    if cmd == "turn":
+        if ns.action == "begin":
+            sys.exit(_out(call("turn_begin", {}, timeout)))
+        args = {}
+        if ns.note:
+            args["note"] = ns.note
+        sys.exit(_out(call("turn_end", args, timeout)))
+    if cmd == "rotate":
+        args = {"path": ns.path, "space": ns.space}
+        if ns.absolute is not None:
+            args["orientation"] = vec3(ns.absolute)
+        else:
+            args["axis"] = ns.axis
+            args["degrees"] = ns.degrees
+        sys.exit(_out(call("rotate", args, timeout)))
+    if cmd == "face":
+        sys.exit(_out(call("face", {"path": ns.path, "target": vec3(ns.target), "axis": ns.axis}, timeout)))
+    if cmd == "shift":
+        sys.exit(_out(call("shift", {"path": ns.path, "offset": vec3(ns.offset), "space": ns.space}, timeout)))
+    if cmd == "scale":
+        sys.exit(_out(call("scale", {"path": ns.path, "factor": ns.factor}, timeout)))
+    if cmd == "duplicate":
+        args = {"path": ns.path, "count": ns.count}
+        if ns.offset:
+            args["offset"] = vec3(ns.offset)
+        if ns.parent:
+            args["parent"] = ns.parent
+        if ns.name:
+            args["name"] = ns.name
+        sys.exit(_out(call("duplicate", args, timeout)))
+    if cmd == "group":
+        args = {"paths": ns.paths, "name": ns.name}
+        if ns.parent:
+            args["parent"] = ns.parent
+        sys.exit(_out(call("group", args, timeout)))
+    if cmd == "pivot":
+        args = {"path": ns.path}
+        if ns.position:
+            args["position"] = vec3(ns.position)
+        if ns.orientation:
+            args["orientation"] = vec3(ns.orientation)
+        sys.exit(_out(call("set_pivot", args, timeout)))
+    if cmd == "terrain":
+        args = {"action": ns.action, "shape": ns.shape,
+                "position": vec3(ns.position), "material": ns.material}
+        if ns.shape == "block":
+            if not ns.size:
+                print("--size x,y,z is required for block", file=sys.stderr)
+                sys.exit(2)
+            args["size"] = vec3(ns.size)
+        else:
+            if ns.radius is None:
+                print("--radius is required for ball", file=sys.stderr)
+                sys.exit(2)
+            args["radius"] = ns.radius
+        sys.exit(_out(call("terrain", args, timeout)))
+    if cmd == "place":
+        args = {"path": ns.path, "position": vec3(ns.position)}
+        if ns.orientation:
+            args["orientation"] = vec3(ns.orientation)
+        sys.exit(_out(call("place", args, timeout)))
+    if cmd == "paint":
+        args = {"paths": ns.paths}
+        if ns.color:
+            args["color"] = ns.color
+        if ns.material:
+            args["material"] = ns.material
+        if ns.transparency is not None:
+            args["transparency"] = ns.transparency
+        if ns.reflectance is not None:
+            args["reflectance"] = ns.reflectance
+        sys.exit(_out(call("paint", args, timeout)))
+    if cmd == "rename":
+        sys.exit(_out(call("rename", {"path": ns.path, "name": ns.name}, timeout)))
+    if cmd == "look":
+        sys.exit(_out(call("look", {"path": ns.path, "distance": ns.distance}, timeout)))
+    if cmd == "count":
+        args = {"scope": ns.scope}
+        if ns.cls:
+            args["class"] = ns.cls
+        sys.exit(_out(call("count", args, timeout)))
+    if cmd == "undo":
+        sys.exit(_out(call("undo", {}, timeout)))
+    if cmd == "anchor":
+        sys.exit(_out(call("anchor", {"paths": ns.paths, "anchored": not ns.off}, timeout)))
+    if cmd == "collide":
+        sys.exit(_out(call("collide", {"paths": ns.paths, "canCollide": not ns.off}, timeout)))
+    if cmd == "light":
+        args = {"path": ns.path, "type": ns.light_type}
+        if ns.color:
+            args["color"] = ns.color
+        if ns.range is not None:
+            args["range"] = ns.range
+        if ns.brightness is not None:
+            args["brightness"] = ns.brightness
+        if ns.shadows:
+            args["shadows"] = True
+        sys.exit(_out(call("light", args, timeout)))
+    if cmd == "sound":
+        args = {"parent": ns.parent, "id": ns.id}
+        if ns.volume is not None:
+            args["volume"] = ns.volume
+        if ns.loop:
+            args["looped"] = True
+        if ns.play:
+            args["play"] = True
+        if ns.name:
+            args["name"] = ns.name
+        sys.exit(_out(call("sound", args, timeout)))
+    if cmd == "weld":
+        sys.exit(_out(call("weld", {"paths": ns.paths}, timeout)))
+    if cmd == "hitbox":
+        args = {"path": ns.path, "padding": ns.padding}
+        if ns.name:
+            args["name"] = ns.name
+        if ns.collide:
+            args["canCollide"] = True
+        sys.exit(_out(call("hitbox", args, timeout)))
+    if cmd == "prompt":
+        args = {"path": ns.path, "action": ns.action, "hold": ns.hold, "distance": ns.distance}
+        if ns.object:
+            args["object"] = ns.object
+        sys.exit(_out(call("prompt", args, timeout)))
+    if cmd == "particles":
+        args = {"path": ns.path, "preset": ns.preset}
+        if ns.rate is not None:
+            args["rate"] = ns.rate
+        if ns.color:
+            args["color"] = ns.color
+        sys.exit(_out(call("particles", args, timeout)))
+    if cmd == "sign":
+        args = {"text": ns.text}
+        if ns.position:
+            args["position"] = vec3(ns.position)
+        if ns.parent:
+            args["parent"] = ns.parent
+        if ns.size:
+            args["size"] = vec3(ns.size)
+        if ns.name:
+            args["name"] = ns.name
+        sys.exit(_out(call("sign", args, timeout)))
+    if cmd == "beam":
+        args = {"from": getattr(ns, "from"), "to": ns.to}
+        for k in ("color", "width", "curve", "name"):
+            v = getattr(ns, k, None)
+            if v is not None:
+                args[k] = v
+        sys.exit(_out(call("beam", args, timeout)))
+    if cmd == "trail":
+        args = {"path": ns.path}
+        for k in ("color", "lifetime", "name"):
+            v = getattr(ns, k, None)
+            if v is not None:
+                args[k] = v
+        sys.exit(_out(call("trail", args, timeout)))
+    if cmd == "explosion":
+        args = {}
+        if ns.position:
+            args["position"] = vec3(ns.position)
+        if ns.radius is not None:
+            args["radius"] = ns.radius
+        sys.exit(_out(call("explosion", args, timeout)))
+    if cmd == "ui_screen":
+        args = {"name": ns.name}
+        if ns.parent:
+            args["parent"] = ns.parent
+        if ns.order is not None:
+            args["order"] = ns.order
+        sys.exit(_out(call("ui_screen", args, timeout)))
+    if cmd == "ui_frame":
+        args = {"parent": ns.parent, "name": ns.name}
+        for k in ("position", "size", "anchor", "color", "transparency", "radius"):
+            v = getattr(ns, k, None)
+            if v is not None:
+                args[k] = v
+        if ns.clip:
+            args["clip"] = True
+        sys.exit(_out(call("ui_frame", args, timeout)))
+    if cmd == "ui_label":
+        args = {"parent": ns.parent, "name": ns.name}
+        for k in ("text", "position", "size", "anchor", "color", "align", "font", "text_size"):
+            v = getattr(ns, k, None)
+            if v is not None:
+                args[k] = v
+        if ns.wrap:
+            args["wrap"] = True
+        sys.exit(_out(call("ui_label", args, timeout)))
+    if cmd == "ui_button":
+        args = {"parent": ns.parent, "name": ns.name}
+        for k in ("text", "position", "size", "anchor", "color", "text_color", "radius", "font", "text_size"):
+            v = getattr(ns, k, None)
+            if v is not None:
+                args[k] = v
+        sys.exit(_out(call("ui_button", args, timeout)))
+    if cmd == "ui_input":
+        args = {"parent": ns.parent, "name": ns.name}
+        for k in ("placeholder", "text", "position", "size", "color", "background", "radius", "text_size"):
+            v = getattr(ns, k, None)
+            if v is not None:
+                args[k] = v
+        sys.exit(_out(call("ui_input", args, timeout)))
+    if cmd == "ui_image":
+        args = {"parent": ns.parent, "name": ns.name}
+        if ns.asset:
+            args["asset"] = ns.asset
+        for k in ("position", "size", "scale"):
+            v = getattr(ns, k, None)
+            if v is not None:
+                args[k] = v
+        sys.exit(_out(call("ui_image", args, timeout)))
+    if cmd == "ui_list":
+        args = {"parent": ns.parent}
+        for k in ("direction", "padding", "halign", "valign"):
+            v = getattr(ns, k, None)
+            if v is not None:
+                args[k] = v
+        sys.exit(_out(call("ui_list", args, timeout)))
+    if cmd == "play":
+        args = {}
+        if ns.mode:
+            args["mode"] = ns.mode
+        sys.exit(_out(call("play", args, timeout)))
+    if cmd == "stop":
+        sys.exit(_out(call("stop", {}, timeout)))
+    if cmd == "logs":
+        args = {"filter": "all"} if ns.all else {}
+        if ns.limit is not None:
+            args["limit"] = ns.limit
+        if ns.since is not None:
+            args["since"] = ns.since
+        sys.exit(_out(call("logs", args, timeout)))
+    if cmd == "attr":
+        args = {"path": ns.path}
+        if ns.set:
+            parsed = {}
+            for kv in ns.set:
+                if "=" not in kv:
+                    print("--set expects K=V", file=sys.stderr)
+                    sys.exit(2)
+                k, v = kv.split("=", 1)
+                try:
+                    v = int(v)
+                except ValueError:
+                    try:
+                        v = float(v)
+                    except ValueError:
+                        if v == "true":
+                            v = True
+                        elif v == "false":
+                            v = False
+                parsed[k] = v
+            args["set"] = parsed
+        if ns.clear:
+            args["clear"] = ns.clear
+        sys.exit(_out(call("attributes", args, timeout)))
+    if cmd == "tag":
+        args = {"paths": ns.paths}
+        if ns.add:
+            args["add"] = ns.add
+        if ns.remove:
+            args["remove"] = ns.remove
+        sys.exit(_out(call("tag", args, timeout)))
+    if cmd == "match":
+        sys.exit(_out(call("match", {"from": ns.from_path, "paths": ns.to}, timeout)))
+    if cmd == "scatter":
+        args = {"path": ns.path, "count": ns.count, "radius": ns.radius, "yJitter": ns.y_jitter}
+        if ns.parent:
+            args["parent"] = ns.parent
+        if ns.name:
+            args["name"] = ns.name
+        sys.exit(_out(call("scatter", args, timeout)))
+    if cmd == "waypoint":
+        sys.exit(_out(call("waypoint", {"label": ns.label}, timeout)))
+
+
+if __name__ == "__main__":
+    main()