Skip to main content

Versioning

protocol_version is a string "<major>.<minor>" matching ^\d+\.\d+$.

  • Breaking changes bump the major ("2.0").
  • Backwards-compatible additions — new constraint types, new option fields with defaults, new response extension fields — bump the minor ("1.1").

Changes by version​

  • 1.3 — the optional ground_height constraint: points on the ground the character moves over, so a route can step or drop between levels. Opt-in: servers list "ground_height" in supported_constraints; a server that doesn't keeps refusing it with unsupported_constraint, and a 1.2 client never sends it.
  • 1.2 — references as prompts, each composing exactly like a text segment: the motion_reference segment (a clip as the prompt) with limits.max_reference_frames, and the video_reference segment (a video as the prompt, by https URL or inline base64) with limits.max_video_bytes and limits.max_video_seconds; and the invalid_request error code. Opt-in per type: servers advertise "motion_reference" / "video_reference" in supported_segments (supports_motion_reference_mixed is then always true for a motion reference). A 1.0 client never sends either and sees no change; a server that doesn't list a type keeps refusing it with unsupported_segment. Clarified (1.0 meanings unchanged: rest_translation / rest_rotation are parent-local, and fill_mode: "rest" pins to rest_rotation): clients SHOULD send identity rest_rotation on every joint, so parent frames are world-aligned at rest and rotations read as "turned from rest"; a server that cannot honour a non-identity rest_rotation MUST reject the request with 400 invalid_skeleton rather than ignore it. See Rest rotations.

Comparison​

Servers compare versions numerically, not lexicographically. So:

"1.10" > "1.2"     ✓ (10 > 2)
"1.10" > "1.2"     ✗ (string compare)

A v1.x server MUST accept any request protocol_version matching ^1\.\d+$ and SHOULD ignore unknown additive fields. A request with a different major version MUST be rejected with version_unsupported.

Multi-major servers​

A server MAY support multiple major protocol versions concurrently and dispatch based on the request's protocol_version. The extensions.MMCP_motion.version in the response always echoes the version actually served.

What clients should do​

  1. Read Capabilities.protocol_version once at startup.
  2. Send your request with the protocol version you implemented against.
  3. Treat unknown response fields as additive — log them, don't crash.
  4. On version_unsupported, surface a clear error to the user with a pointer to upgrade the plugin.
Don't pin to minor

Pin your client to the major version, not the exact minor. A v1.0 client should send "protocol_version": "1.0" and accept responses from any v1.x server. New minor versions are opt-in via new request fields, which old clients never send.