Files
UniversalTrain-ai/controller/vocabulary.py
T
chenlin c32df70326
Checks / Layout, translation and Colab checks (push) Has been cancelled
Checks / Ruff (push) Has been cancelled
Checks / Framework tests (native backend, CPU) (push) Has been cancelled
Checks / Portable Rust controller (push) Has been cancelled
release: v0.1 generic robot training and application platform
2026-11-05 11:05:01 +08:00

162 lines
6.4 KiB
Python

"""The gamepad vocabulary: what a pad can say, for looking up.
`vocabulary.json` beside this file is the dictionary. This reads it and nothing
else -- there is no list in this module, deliberately, because a list here would
be the second copy and the one that goes out of date.
python -m controller --vocabulary
Consumers are elsewhere and each attaches its own meanings: a deploy manifest's
`[[fsm.button]]`, a task's `controls.yaml`. That direction is this package's
rule, stated at the top of `__init__.py`: nothing here has an opinion about what
a stick means.
"""
from __future__ import annotations
import functools
import json
from importlib.resources import files
from pathlib import Path
#: The dictionary. Beside this module so `python -m controller` and an editable
#: install find the same bytes, and shipped as package data -- see `pyproject`.
PATH = Path(__file__).resolve().parent / "vocabulary.json"
SCHEMA = "kk-control-vocabulary/2"
@functools.lru_cache(maxsize=1)
def load() -> dict:
doc = json.loads(files("controller").joinpath("vocabulary.json").read_text("utf-8"))
if doc.get("schema") != SCHEMA:
raise ValueError(f"{PATH}: schema is {doc.get('schema')!r}, not {SCHEMA!r}")
return doc
def buttons() -> tuple[str, ...]:
"""Every button a binding may name, the ten plus the four directions."""
doc = load()
return tuple(b["name"] for b in doc["buttons"] + doc["dpad"])
def axes() -> tuple[str, ...]:
"""Every axis, in the order the wire carries them."""
return tuple(a["name"] for a in load()["axes"])
def keys() -> tuple[str, ...]:
"""Every key a binding may name.
The numeric keypad, and the letters a task has asked for. MuJoCo's viewer
calls the user callback **in addition to** its own shortcuts and binds every
letter, so a letter does two things at once there. `_keys_note` in the
dictionary says which, and why a key there is a press and nothing else.
"""
return tuple(k["name"] for k in load()["keys"])
def key_codes() -> dict[str, dict]:
"""`{name: {"glfw": int, "browser": str}}`, for a host that reads one of
those and has to arrive at the contract's name."""
return {k["name"]: {"glfw": k["glfw"], "browser": k["browser"]}
for k in load()["keys"]}
def modifiers() -> dict[str, tuple[str, ...]]:
"""`{name: keys}`: a modifier is down while either of its keys is.
`ctrl`, `shift` and `alt`, each the left and the right key. A keyboard
binding names one on its own or in front of a key -- `shift+key_j` -- and a
mode switch names one as its `with`. `_modifiers_note` has the rule.
"""
return {m["name"]: tuple(m["keys"]) for m in load()["modifiers"]}
def keystroke(spec: str) -> tuple[str | None, str]:
"""`"shift+key_j"` -> `("shift", "key_j")`; `"key_j"` -> `(None, "key_j")`;
`"ctrl"` -> `(None, "ctrl")`.
What a keyboard binding names: a key, a modifier on its own, or a modifier
held with a key. Raises for anything else, naming what it is not -- a key
nobody reports binds nothing, and would look exactly like one that did.
"""
mods = modifiers()
known = frozenset(keys()) | frozenset(mods)
# Whole names first: `keypad_+` is a key whose name ends in a plus, not a
# chord. A modifier's name has no plus, so a chord splits at the first one.
if spec in known:
return None, spec
modifier, _, key = spec.partition("+")
held = {k for ks in mods.values() for k in ks}
if modifier in mods and key in known and key not in mods and key not in held:
return modifier, key
raise ValueError(
f"{spec!r} is not a key, a modifier ({', '.join(mods)}), or a modifier and a key "
f"(`shift+key_j`). The keys are {' '.join(keys())}"
)
def gestures() -> tuple[str, ...]:
return tuple(g["name"] for g in load()["gestures"])
def absent() -> dict[str, str]:
"""Controls the pad has and the service does not publish, and why.
Kept in the dictionary rather than left out of it: a name that is missing
reads as an oversight, and `view` is a decision.
"""
return {a["name"]: a["why"] for a in load()["absent"]}
def describe() -> str:
"""The whole thing, rendered. What `--vocabulary` prints."""
doc = load()
out = ["buttons (a `pad = ` in [[fsm.button]])"]
out.append(" " + " ".join(b["name"] for b in doc["buttons"]))
out.append(" " + " ".join(b["name"] for b in doc["dpad"]))
for name, why in absent().items():
out.append(f" not `{name}`: {why}")
out.append("")
out.append("keys (a `key = ` in [[fsm.button]])")
doc_keys = doc["keys"]
out.append(" " + " ".join(k["name"] for k in doc_keys))
# One line per contiguous run of GLFW codes. The keypad is one run and the
# letters are not -- a single `first-last` span printed "glfw 320-70" once
# they were added, which reads as a range and is not one.
runs, start = [], 0
for i in range(1, len(doc_keys) + 1):
if i == len(doc_keys) or doc_keys[i]["glfw"] != doc_keys[i - 1]["glfw"] + 1:
a, b = doc_keys[start], doc_keys[i - 1]
runs.append(
f"glfw {a['glfw']}" + (f"-{b['glfw']}" if b is not a else "")
+ f" browser {a['browser']}" + (f"..{b['browser']}" if b is not a else "")
)
start = i
out.append(" " + "; ".join(runs) if len(runs) <= 3 else
f" {len(runs)} runs of codes; see `controller/vocabulary.json`")
out.append(" " + "\n ".join(doc["_keys_note"][:5]))
out.append("")
out.append("modifiers (`with = ` on a key switch; `shift+key_j` in a controls.yaml)")
out.append(" " + " ".join(f"{m}: {' '.join(ks)}" for m, ks in modifiers().items()))
out.append("")
out.append("axes (a `source = ` in a task's controls.yaml)")
for a in doc["axes"]:
lo, hi = a["range"]
out.append(f" {a['name']:<8}[{lo}, {hi}]" + (f" {a['note']}" if "note" in a else ""))
out.append(" " + doc["_axes_note"])
out.append("")
out.append("gestures (an `on = ` in [[fsm.button]])")
for g in doc["gestures"]:
out.append(f" {g['name']:<10}{g['fires']}")
out.append(" " + doc["_gestures_note"])
unresolved = [(b["name"], b["unresolved"]) for b in doc["buttons"] if "unresolved" in b]
if unresolved:
out.append("")
out.append("unresolved")
for name, why in unresolved:
out.append(f" {name}: {why}")
return "\n".join(out) + "\n"