Imported from ChenSheng0228/unity_- (AGENTS.md). Install upstream with npx skills add ChenSheng0228/unity_-. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

infer_realtime_serial.py is the CLI entrypoint for realtime serial inference. Core runtime code lives in inference_realtime_local/: serial_emg.py handles device I/O and frame parsing, realtime_pipeline.py runs filtering and ONNX inference, mujoco_renderer.py drives the hand viewer, and serial_app.py wires the producer/consumer loop together. Keep model and render assets at the repository root (*.onnx, hand.xml, hand.skn); put protocol notes in docs/ and large training artifacts under checkpoints/.

Build, Test, and Development Commands

Use uv with Python 3.11 for dependency management, but use mjpython directly for MuJoCo viewer functionality.

• uv sync --frozen installs the locked runtime environment.
• mjpython infer_realtime_serial.py --wear-side right --debug-every 5 runs the main serial + MuJoCo loop.
• EMG_SERIAL_PORT=/dev/ttyUSB0 mjpython infer_realtime_serial.py --wear-side left forces a specific device path when auto-detection is wrong.
• python -m compileall infer_realtime_serial.py inference_realtime_local is the quickest syntax sanity check before committing.

Coding Style & Naming Conventions

Follow the existing Python style: 4-space indentation, type hints on public functions, from __future__ import annotations, and small focused modules. Use snake_case for functions, variables, and files; use UPPER_SNAKE_CASE for hardware/constants such as baud rates and model paths. Prefer explicit Path handling over raw strings, and keep CLI flags long-form and descriptive.

Testing Guidelines

There is no formal automated test suite yet. Do not add unit tests by default; this repo favors fast shared debugging over test scaffolding unless explicitly requested. Validate changes with targeted runs, and record the exact command, wear side, serial port override, and observed behavior in your notes or PR.

Commit & Pull Request Guidelines

Match the current history: short imperative Conventional Commit subjects such as feat: mujoco render or feat: include unity api. Keep PRs narrowly scoped and include:

• what changed and why
• the exact validation command(s) you ran
• hardware/runtime assumptions such as OS, serial device path, and hand side
• screenshots or short clips for renderer or Unity-facing behavior changes

Configuration Tips

Prefer EMG_SERIAL_PORT over hardcoding device paths. Treat ONNX models, .bin captures, and checkpoints as external artifacts: do not rename or move them without updating all path resolution code.