Skip to content
Back to search

posecode

An open-source text language, parser, validator and Three.js renderer for inspectable 3D human movement.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/posecode-dev--posecode/badge.svg)](/listings/posecode-dev--posecode)

HTML

<a href="/listings/posecode-dev--posecode"><img src="/api/listings/posecode-dev--posecode/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Live Playground

Preview, edit, and share movements without installing anything:

**https://posecode.org/play**

---

Local Development

Requirements:

- Node.js 20 or newer - npm

Clone the repository:

git clone https://github.com/posecode-dev/posecode.git
cd posecode

Install dependencies:

npm install

Start the playground:

npm run dev

Run tests:

npm test

Run type checking:

npm run typecheck

Run fidelity evaluations:

npm run eval

Build the playground:

npm run build

---

Editor support

A VS Code extension provides syntax highlighting, ROM diagnostics, and completion for `.posecode` files — see [`editors/vscode`](editors/vscode/README.md). Until it is published, you can get basic highlighting immediately by associating `.posecode` files with Markdown:

"files.associations": {
  "*.posecode": "markdown"
}

See the [editor guide](editors/vscode/README.md#file-association-before-the-extension-is-installed) for VS Code, Cursor, Sublime Text, and Neovim instructions.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 901 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1 align="center">Posecode</h1>
  2. <p align="center">
  3. <b>Kinematic motion as text.</b>
  4. <br />
  5. An inspectable, editable movement format for animation tools, LLMs, and web products.
  6. </p>
  7. <p align="center">
  8. Like Mermaid for movement: small text documents for describing, validating, and rendering
  9. <br />
  10. deterministic human motion without hiding the source inside a black box.
  11. </p>
  12. <p align="center">
  13. <a href="https://posecode.org/play"><b>Live Playground</b></a> ·
  14. <a href="https://posecode.org/moves/">Movement Library</a> ·
  15. <a href="spec/SPEC.md"><b>Language Specification (SPEC.md)</b></a> ·
  16. <a href="spec/llm-authoring.md">LLM Authoring Guide</a> ·
  17. <a href="spec/examples">Examples</a> ·
  18. <a href="packages/posecode-mcp">MCP Server</a>
  19. </p>
  20. <p align="center">
  21. <a href="https://github.com/posecode-dev/posecode/actions/workflows/ci.yml">
  22. <img src="https://github.com/posecode-dev/posecode/actions/workflows/ci.yml/badge.svg" alt="CI status" />
  23. </a>
  24. <a href="https://www.npmjs.com/package/posecode-parser">
  25. <img src="https://img.shields.io/npm/v/posecode-parser.svg?color=emerald" alt="npm version" />
  26. </a>
  27. <a href="https://github.com/posecode-dev/posecode/blob/main/docs/legal/LICENSING.md">
  28. <img src="https://img.shields.io/badge/license-Apache--2.0%20%2B%20AGPL--3.0-blue.svg" alt="Apache 2.0 and AGPL 3.0 licenses" />
  29. </a>
  30. <a href="https://github.com/posecode-dev/posecode/tree/main/packages/posecode-mcp">
  31. <img src="https://img.shields.io/badge/MCP-Compatible-orange.svg" alt="MCP compatible" />
  32. </a>
  33. </p>
  34. ---
  35. ## Why Posecode?
  36. Animation clips and generated trajectories can show movement, but they often hide the semantic decisions that produced it.
  37. Posecode keeps those decisions in readable source. A human can write the document, an animation tool can emit it, or an LLM can draft it. Parsing, validation, editing, and rendering do not require an AI model.
  38. <p align="center">
  39. <img
  40. src="docs/media/jumping-jacks.gif"
  41. width="440"
  42. alt="Jumping jacks rendered from a Posecode document"
  43. />
  44. </p>
  45. <p align="center">
  46. <sub>
  47. One <code>.posecode</code> document —
  48. <code>shoulders: abduct 160</code>,
  49. <code>hips: abduct 30</code>,
  50. <code>repeat 12</code> —
  51. rendered live in the browser.
  52. </sub>
  53. </p>
  54. For example:
  55. > Bend your knees, move your hips backward, and keep your chest upright.
  56. A human may understand that instruction, but a renderer cannot reliably determine:
  57. - which joints should move,
  58. - by how many degrees,
  59. - in which coordinate frame,
  60. - over what duration,
  61. - in what sequence,
  62. - or within which physical limits.
  63. Humans, tools, and language models all need a shared syntax for expressing movement in a renderable and testable form.
  64. Posecode provides that missing representation.
  65. ### See Posecode in 28 seconds
  66. From readable movement source to validated 3D rendering, MCP tools, and a
  67. one-script web embed.
  68. <p align="center">
  69. <a href="docs/launch-media/posecode-cut2-builder-16x9.mp4">
  70. <img
  71. src="docs/launch-media/posecode-cut2-payoff.png"
  72. width="800"
  73. alt="Watch the 28-second Posecode builder demo"
  74. />
  75. </a>
  76. </p>
  77. <p align="center">
  78. <a href="docs/launch-media/posecode-cut2-builder-16x9.mp4"><b>▶ Watch the 28-second builder demo</b></a>
  79. <br />
  80. <sub>Plain text in. Smooth, programmable 3D motion out.</sub>
  81. </p>
  82. ### Movement examples
  83. <table align="center">
  84. <tr>
  85. <td align="center">
  86. <img src="docs/media/deadlift.gif" width="230" alt="Deadlift rendered from Posecode" />
  87. <br />
  88. <sub><code>pelvis: hinge</code> — deadlift</sub>
  89. </td>
  90. <td align="center">
  91. <img src="docs/media/squat.gif" width="230" alt="Squat rendered from Posecode" />
  92. <br />
  93. <sub><code>knees: flex 95</code> — squat</sub>
  94. </td>
  95. <td align="center">
  96. <img src="docs/media/lateral-raise.gif" width="230" alt="Lateral raise rendered from Posecode" />
  97. <br />
  98. <sub><code>shoulders: abduct 90</code> — lateral raise</sub>
  99. </td>
  100. </tr>
  101. </table>
  102. ---
  103. ## Why Not Diffusion Text-to-Motion?
  104. Neural text-to-motion systems can generate impressive movement, but they introduce problems for lightweight, programmable applications.
  105. ### Resource intensive
  106. Many systems require large models and GPU-backed inference, making real-time consumer deployment expensive.
  107. ### Difficult to control
  108. They usually produce coordinate trajectories rather than editable semantic instructions.
  109. It is difficult to request a precise change such as:
  110. > Reduce knee flexion by 10 degrees during the second phase.
  111. ### Hard to validate
  112. Black-box trajectories do not naturally expose readable joint rules, phase definitions, or range-of-motion limits.
  113. ### Hard to debug
  114. When a movement looks wrong, developers may not know which semantic instruction caused the problem.
  115. ---
  116. ## The Posecode Approach
  117. Posecode uses a lightweight, text-driven pipeline.
  118. - **Readable:** movements are stored as small `.posecode` documents.
  119. - **Structured:** joints, actions, angles, timings, and constraints are explicit.
  120. - **Editable:** developers and models can modify individual movement properties.
  121. - **Fast:** parsing and rendering happen client-side.
  122. - **Deterministic:** the same Posecode input produces the same validated representation.
  123. - **Inspectable:** parser warnings and fidelity checks explain problems.
  124. - **Agent-friendly:** the MCP server exposes generation, validation, critique, and sharing tools.
  125. - **Safety-aware:** authored and IK-generated angles are constrained by configured range-of-motion limits.
  126. ---
  127. ## The Idea in 30 Seconds
  128. A `.posecode` file describes movement as timed phases with targeted joint actions.
  129. | 1. Write `.posecode` | 2. Render the movement |
  130. | :--- | :--- |
  131. | **`posecode`** `exercise "Body-weight squat"`<br />**`rig`** `humanoid`<br />**`pose`** `start = standing`<br /><br />**`step`** `"Descend" 1.6s settle`:<br />&nbsp;&nbsp;`hips: flex 80`<br />&nbsp;&nbsp;`knees: flex 95`<br />&nbsp;&nbsp;`ankles: dorsiflex 14`<br />&nbsp;&nbsp;`ground-lock: feet`<br />&nbsp;&nbsp;`cue "Sit the hips back"`<br /><br />**`step`** `"Drive up" 1.2s drive`:<br />&nbsp;&nbsp;`hips: flex 0`<br />&nbsp;&nbsp;`knees: flex 0`<br />&nbsp;&nbsp;`ankles: dorsiflex 0`<br />&nbsp;&nbsp;`ground-lock: feet`<br /><br />**`repeat`** `8` | <img src="docs/media/squat.gif" width="340" alt="Squat animation" /> |
  132. ---
  133. > **OpenAI Build Week 2026:** Posecode existed before the hackathon. During Build Week, the project was extended using **Codex** — running on **GPT-5.6** — as the primary engineering tool for a real batch of shipped work: motion/grounding quality, language contract diagnostics, licensing restructuring, release automation, and product-facing pages. The sections below distinguish previous work from Build Week work using actual commit history, not a roadmap.
  134. ---
  135. ## OpenAI Build Week Extension
  136. ### What existed before Build Week
  137. Before Build Week, Posecode already included:
  138. - the core `.posecode` domain-specific language,
  139. - a parser and intermediate motion representation,
  140. - basic range-of-motion validation,
  141. - a Three.js/WebGL renderer,
  142. - forward kinematics,
  143. - basic inverse-kinematics and ground-lock behavior,
  144. - a browser playground,
  145. - example movement files,
  146. - shareable Posecode links,
  147. - and an MCP server foundation.
  148. This original version was developed primarily with **Claude** as an AI-assisted engineering tool.
  149. That prior work provides the foundation for the project, but it is not presented as the new hackathon contribution.
  150. ### What was added during Build Week
  151. Every item below is a merged, dated pull request built with Codex (GPT-5.6) — see [Build Week Evidence](#build-week-evidence) for direct links.
  152. 1. **Motion and grounding overhaul** — ROM-constrained reach IK, semantic palm/fist/sole/knee/pelvis contact surfaces, multi-contact refinement, stable support handoffs, and XBot-aware grounding ([#76](https://github.com/posecode-dev/posecode/pull/76)).
  153. 2. **Language contract and diagnostics** — Posecode language/IR v0.3 custom start-pose blocks with ROM-checked overrides, live and clip-wide grounding/self-collision diagnostics, and an accessible metric floor guide ([#92](https://github.com/posecode-dev/posecode/pull/92)).
  154. 3. **Licensing restructure** — split the monorepo into an Apache-2.0 standard layer (spec, parser, share, language, LSP, VS Code) and an AGPL-3.0 product layer (render, embed, MCP, eval, playground), with a commercial-license path ([#84](https://github.com/posecode-dev/posecode/pull/84)).
  155. 4. **Release automation** — Changesets-driven npm publishing via GitHub OIDC, MCP Registry publishing, and CI validation of package versions, entry points, and tarball contents ([#66](https://github.com/posecode-dev/posecode/pull/66)).
  156. 5. **Third-party integration readiness** — Posecode 0.2 timing vocabulary (`drive`/`settle`/`flow`/`snap`), a parser validation CLI, and embed compatibility metadata ([#62](https://github.com/posecode-dev/posecode/pull/62)).
  157. 6. **Ground-lock correctness** — parser-owned validation for per-side foot/hand/elbow ground locks and back-contact support for supine movements, replacing silent acceptance of invalid contacts ([#61](https://github.com/posecode-dev/posecode/pull/61), [#64](https://github.com/posecode-dev/posecode/pull/64)).
  158. 7. **LLM-first landing page and product page** — redesigned the landing page around a prompt → Posecode → live 3D story, and added a `/for-products` page documenting the web component, parser, renderer, and MCP server for integrators ([#82](https://github.com/posecode-dev/posecode/pull/82), [#74](https://github.com/posecode-dev/posecode/pull/74)).
  159. 8. **Mobile and search fixes** — mobile toolbar/viewer layout, natural hand orientation, and Google Search indexing corrections ([#78](https://github.com/posecode-dev/posecode/pull/78), [#65](https://github.com/posecode-dev/posecode/pull/65)).
  160. ### Build Week feature status
  161. - [x] Motion/grounding quality overhaul shipped ([#76](https://github.com/posecode-dev/posecode/pull/76))
  162. - [x] Language contract + diagnostics shipped ([#92](https://github.com/posecode-dev/posecode/pull/92))
  163. - [x] Licensing restructure shipped ([#84](https://github.com/posecode-dev/posecode/pull/84))
  164. - [x] Release automation shipped ([#66](https://github.com/posecode-dev/posecode/pull/66))
  165. - [x] Ground-lock correctness shipped ([#61](https://github.com/posecode-dev/posecode/pull/61), [#64](https://github.com/posecode-dev/posecode/pull/64))
  166. - [x] Landing/product pages shipped ([#82](https://github.com/posecode-dev/posecode/pull/82), [#74](https://github.com/posecode-dev/posecode/pull/74))
  167. ---
  168. ## How GPT-5.6 Is Used
  169. During Build Week, Codex sessions ran on **GPT-5.6** (GPT-5.6 Terra), which is the model that powers Codex for this event. GPT-5.6 is the reasoning engine behind every Build Week change listed above: reading the existing monorepo, proposing the ROM-constrained IK and contact-surface design in [#76](https://github.com/posecode-dev/posecode/pull/76), designing the language/IR v0.3 diagnostics in [#92](https://github.com/posecode-dev/posecode/pull/92), and drafting the licensing boundary in [#84](https://github.com/posecode-dev/posecode/pull/84).
  170. A GPT-5.6-powered natural-language-to-Posecode generation feature (describe a movement in plain English, get a validated `.posecode` document back) is a natural next step given the existing [`posecode_authoring_guide` MCP tool](packages/posecode-mcp/README.md), but it is **not yet built** — it is not claimed as shipped functionality here.
  171. ---
  172. ## How Codex Is Used
  173. Codex is the primary engineering tool used for the Build Week extension.
  174. During the hackathon period, Codex was used to:
  175. - inspect and understand the existing monorepo before each change,
  176. - design and implement the ROM-constrained reach IK and contact-surface system ([#76](https://github.com/posecode-dev/posecode/pull/76)),
  177. - design and implement the language/IR v0.3 diagnostics and floor guide ([#92](https://github.com/posecode-dev/posecode/pull/92)),
  178. - restructure package licensing across the monorepo ([#84](https://github.com/posecode-dev/posecode/pull/84)),
  179. - build the Changesets/OIDC npm and MCP Registry release pipeline ([#66](https://github.com/posecode-dev/posecode/pull/66)),
  180. - fix ground-lock validation and silent-acceptance bugs ([#61](https://github.com/posecode-dev/posecode/pull/61), [#64](https://github.com/posecode-dev/posecode/pull/64)),
  181. - redesign the landing page and add the product integration page ([#82](https://github.com/posecode-dev/posecode/pull/82), [#74](https://github.com/posecode-dev/posecode/pull/74)),
  182. - write unit, integration, and evaluation-harness tests for each change,
  183. - and fix mobile UI and search-indexing regressions.
  184. Codex accelerates implementation, but the project remains human-directed. The following decisions were reviewed and selected manually: DSL semantics, system architecture, licensing boundaries, biomechanical constraints, validation policy, user experience, and acceptance or rejection of generated code.
  185. ### Codex development workflow
  186. The Build Week workflow follows this process:
  187. 1. Define a specific product or engineering problem.
  188. 2. Ask Codex to inspect the relevant implementation.
  189. 3. Request one or more possible approaches.
  190. 4. Review the trade-offs and choose the architecture.
  191. 5. Use Codex to implement the selected approach.
  192. 6. Run type checking, tests, and biomechanical evaluations (`npm run eval`).
  193. 7. Inspect failures manually.
  194. 8. Refine the implementation with additional Codex sessions.
  195. 9. Review the final changes before committing.
  196. ---
  197. ## Build Week Evidence
  198. All Build Week work is public, dated, and directly linked below — no placeholders.
  199. ### Build Week pull requests
  200. | PR | Merged | What it did |
  201. | --- | --- | --- |
  202. | [#62](https://github.com/posecode-dev/posecode/pull/62) | 2026-07-15 | Posecode 0.2 timing vocabulary, validation CLI, embed compatibility |
  203. | [#61](https://github.com/posecode-dev/posecode/pull/61) | 2026-07-15 | Per-side ground-lock validation |
  204. | [#65](https://github.com/posecode-dev/posecode/pull/65) | 2026-07-16 | Google Search indexing fix |
  205. | [#66](https://github.com/posecode-dev/posecode/pull/66) | 2026-07-16 | npm + MCP Registry release automation |
  206. | [#64](https://github.com/posecode-dev/posecode/pull/64) | 2026-07-16 | Back ground-lock for supine movements |
  207. | [#74](https://github.com/posecode-dev/posecode/pull/74) | 2026-07-16 | `/for-products` integration page |
  208. | [#76](https://github.com/posecode-dev/posecode/pull/76) | 2026-07-17 | Motion/grounding overhaul: ROM-constrained reach IK, contact surfaces |
  209. | [#78](https://github.com/posecode-dev/posecode/pull/78) | 2026-07-17 | Mobile viewer sizing and natural hand orientation |
  210. | [#82](https://github.com/posecode-dev/posecode/pull/82) | 2026-07-17 | LLM-first landing page redesign |
  211. | [#84](https://github.com/posecode-dev/posecode/pull/84) | 2026-07-17 | Apache-2.0 / AGPL-3.0 licensing restructure |
  212. | [#92](https://github.com/posecode-dev/posecode/pull/92) | 2026-07-19 | Language/IR v0.3, grounding/self-collision diagnostics, floor guide |
  213. ### Build Week comparison
  214. | Before Build Week | Added during Build Week |
  215. | --- | --- |
  216. | Core Posecode DSL | Language/IR v0.3 custom start-pose blocks |
  217. | Basic ROM clamping | Grounding, self-collision, and floor-guide diagnostics |
  218. | Working IK/grounding | ROM-constrained reach IK with semantic contact surfaces |
  219. | Single license file | Apache-2.0 / AGPL-3.0 layered licensing with commercial path |
  220. | Manual publishing | Automated npm + MCP Registry release pipeline |
  221. | Editorial landing page | LLM-first landing page + `/for-products` integration page |
  222. | Existing tests | New diagnostics, IK, and licensing regression tests |
  223. ---
  224. ---
  225. ## Architecture
  226. ```text
  227. ┌─────────────────────────┐
  228. │ Natural-language prompt │
  229. └────────────┬────────────┘
  230. │
  231. ▼
  232. ┌─────────────────────────┐
  233. │ GPT-5.6 authoring layer │
  234. └────────────┬────────────┘
  235. │
  236. ▼
  237. ┌─────────────────────────┐
  238. │ .posecode source │
  239. └────────────┬────────────┘
  240. │
  241. ▼
  242. ┌─────────────────────────┐
  243. │ Parser and ROM checking │
  244. └────────────┬────────────┘
  245. │
  246. ▼
  247. ┌─────────────────────────┐
  248. │ Kinematics and IK layer │
  249. └────────────┬────────────┘
  250. │
  251. ├─────────────────────┐
  252. ▼ ▼
  253. ┌─────────────────────────┐ ┌──────────────────────┐
  254. │ Three.js/WebGL renderer │ │ Fidelity measurements│
  255. └─────────────────────────┘ └──────────┬───────────┘
  256. │
  257. ▼
  258. ┌──────────────────────┐
  259. │ GPT-5.6 Physics │
  260. │ Critic and revision │
  261. └──────────────────────┘
  262. ```
  263. ---
  264. ## Installation and Usage
  265. ### Live Playground
  266. Preview, edit, and share movements without installing anything:
  267. **https://posecode.org/play**
  268. ---
  269. ### Local Development
  270. Requirements:
  271. - Node.js 20 or newer
  272. - npm
  273. Clone the repository:
  274. ```bash
  275. git clone https://github.com/posecode-dev/posecode.git
  276. cd posecode
  277. ```
  278. Install dependencies:
  279. ```bash
  280. npm install
  281. ```
  282. Start the playground:
  283. ```bash
  284. npm run dev
  285. ```
  286. Run tests:
  287. ```bash
  288. npm test
  289. ```
  290. Run type checking:
  291. ```bash
  292. npm run typecheck
  293. ```
  294. Run fidelity evaluations:
  295. ```bash
  296. npm run eval
  297. ```
  298. Build the playground:
  299. ```bash
  300. npm run build
  301. ```
  302. ---
  303. ### Editor support
  304. A VS Code extension provides syntax highlighting, ROM diagnostics, and
  305. completion for `.posecode` files — see
  306. [`editors/vscode`](editors/vscode/README.md). Until it is published, you can
  307. get basic highlighting immediately by associating `.posecode` files with
  308. Markdown:
  309. ```json
  310. "files.associations": {
  311. "*.posecode": "markdown"
  312. }
  313. ```
  314. See the [editor guide](editors/vscode/README.md#file-association-before-the-extension-is-installed)
  315. for VS Code, Cursor, Sublime Text, and Neovim instructions.
  316. ---
  317. ## MCP Server
  318. Posecode includes a Model Context Protocol server for AI agents.
  319. Run it with:
  320. ```bash
  321. npx -y posecode-mcp@latest
  322. ```
  323. Example MCP client configuration:
  324. ```json
  325. {
  326. "mcpServers": {
  327. "posecode": {
  328. "command": "npx",
  329. "args": ["-y", "posecode-mcp@latest"]
  330. }
  331. }
  332. }
  333. ```
  334. The MCP server exposes:
  335. - `validate_posecode`
  336. - `render_posecode`
  337. See [`packages/posecode-mcp`](packages/posecode-mcp) for the complete configuration and tool documentation.
  338. ---
  339. ## Web Component Embed
  340. Embed a Posecode player on a page:
  341. ```html
  342. <script src="https://unpkg.com/posecode-embed/dist/posecode-embed.js"></script>
  343. <posecode-player src="/movements/squat.posecode"></posecode-player>
  344. ```
  345. The player can be used in:
  346. - documentation,
  347. - educational content,
  348. - exercise guides,
  349. - blog posts,
  350. - and movement libraries.
  351. ---
  352. ## Core Libraries
  353. Install the parser:
  354. ```bash
  355. npm install posecode-parser
  356. ```
  357. Install the renderer:
  358. ```bash
  359. npm install posecode-render
  360. ```
  361. Example:
  362. ```ts
  363. import { parse } from "posecode-parser";
  364. import { createViewer } from "posecode-render";
  365. const source = `
  366. posecode exercise "Lateral raise"
  367. rig humanoid
  368. pose start = standing
  369. step "Raise" 1.4s settle:
  370. shoulders: abduct 90
  371. `;
  372. const { ir, errors, warnings } = parse(source);
  373. if (!ir || errors.length > 0) {
  374. console.error(errors);
  375. } else {
  376. console.warn(warnings);
  377. const viewer = createViewer(document.querySelector("#viewer"));
  378. viewer.load(ir);
  379. viewer.play();
  380. }
  381. ```
  382. The `#viewer` element is an HTML `<canvas>`.
  383. ### Exporting motion (BVH)
  384. `posecode-render` can bake a movement into a [Biovision Hierarchy](https://en.wikipedia.org/wiki/Biovision_Hierarchy)
  385. (`.bvh`) file for import into Blender and other animation tools. In the
  386. playground, use the **Download BVH** button; programmatically:
  387. ```ts
  388. import { parse } from "posecode-parser";
  389. import { exportBVH } from "posecode-render";
  390. const { ir } = parse(source);
  391. const bvh = exportBVH(ir!, { fps: 30 }); // string, ready to write to disk
  392. ```
  393. Options: `fps` (default 30), `scale` (default 1 = metres; pass `100` for
  394. centimetres), `includeFingers` (default false), and `proportions` for a
  395. calibrated rig.
  396. - **Coordinate system:** right-handed, **Y-up**, figure faces **+Z** in the
  397. rest pose (identical to the renderer and Three.js). Enable Blender's "Y up"
  398. BVH import option.
  399. - **Units:** metres by default.
  400. - **Rotation channels:** `Zrotation Xrotation Yrotation` (Euler order `ZXY`).
  401. - **Scope:** this exports the *authored* joint motion plus root travel/turn. It
  402. does not yet re-run the renderer's contact/IK solve, so IK-dependent movements
  403. (e.g. `reach: hand_left floor`) export the authored pose rather than the
  404. solved one. See [issue #63](https://github.com/posecode-dev/posecode/issues/63).
  405. ### Exporting motion (glTF / GLB)
  406. For web animation pipelines, `posecode-render` can export the rig **and** a
  407. baked animation clip as a glTF/GLB asset. In the playground, use **Download
  408. glTF**; programmatically:
  409. ```ts
  410. import { parse } from "posecode-parser";
  411. import { exportGLTF } from "posecode-render";
  412. const { ir } = parse(source);
  413. const glb = await exportGLTF(ir!); // GLB ArrayBuffer (default)
  414. const gltf = await exportGLTF(ir!, { binary: false }); // glTF JSON object
  415. ```
  416. The result loads with Three.js [`GLTFLoader`](https://threejs.org/docs/#GLTFLoader.load),
  417. and the clip plays on the included rig:
  418. ```ts
  419. const gltf = await new GLTFLoader().loadAsync(url);
  420. const mixer = new THREE.AnimationMixer(gltf.scene);
  421. mixer.clipAction(gltf.animations[0]).play();
  422. ```
  423. - Joint nodes are named by Posecode bone id; the animated root is `posecode_root`.
  424. - **Limitations:** exports the procedural mannequin rig, not a humanoid/Mixamo
  425. skeleton, so there is **no retargeting** onto external rigs yet, and (as with
  426. BVH) it bakes the authored motion, not the contact/IK-solved motion. See
  427. [issue #90](https://github.com/posecode-dev/posecode/issues/90).
  428. ---
  429. ## How Posecode Stays Honest
  430. Posecode uses multiple layers of checking.
  431. ### 1. Range-of-motion clamping
  432. Joint angles are constrained before rendering.
  433. For example:
  434. ```posecode
  435. knees: flex 200
  436. ```
  437. is clamped to the configured knee-flexion limit and produces a warning instead of rendering an impossible angle.
  438. ### 2. Kinematic evaluation
  439. The engine measures the actual resulting skeleton after:
  440. - parsing,
  441. - forward kinematics,
  442. - inverse kinematics,
  443. - and ground-lock corrections.
  444. ### 3. Geometric fidelity invariants
  445. Movement examples can define expected properties.
  446. For example, a deadlift may require:
  447. - sufficient torso pitch,
  448. - limited forward knee travel,
  449. - stable foot contact,
  450. - and symmetrical hip movement.
  451. ### 4. GPT-5.6 Physics Critic
  452. The Build Week critic interprets the movement and deterministic measurements together.
  453. It explains biomechanical problems in natural language and proposes specific revisions.
  454. ---
  455. ## Packages
  456. | Package | Purpose |
  457. | --- | --- |
  458. | [`posecode-language`](packages/posecode-language) | Language definitions and editor support |
  459. | [`posecode-parser`](packages/posecode-parser) | Converts `.posecode` text into a validated, range-constrained intermediate representation |
  460. | [`posecode-render`](packages/posecode-render) | Renders animated figures with Three.js, forward kinematics, and IK |
  461. | [`posecode-share`](packages/posecode-share) | Encodes Posecode documents into URL-safe share tokens |
  462. | [`posecode-mcp`](packages/posecode-mcp) | Exposes Posecode capabilities to AI agents through MCP |
  463. | [`posecode-eval`](packages/posecode-eval) | Runs headless biomechanical and geometric fidelity evaluations |
  464. | [`playground`](playground) | Interactive editor, 3D viewport, warnings, generation, critique, and sharing |
  465. ---
  466. ## Technology
  467. Posecode is built with:
  468. - TypeScript
  469. - JavaScript
  470. - Node.js
  471. - Three.js
  472. - WebGL
  473. - Vite
  474. - CodeMirror
  475. - Model Context Protocol
  476. - Zod
  477. - Vitest
  478. - Playwright
  479. - esbuild
  480. - GPT-5.6
  481. - Codex
  482. ---
  483. ## Scope
  484. ### Version 0.1
  485. Posecode currently focuses on:
  486. - single-person human movement,
  487. - fitness,
  488. - physiotherapy demonstrations,
  489. - posture,
  490. - dance,
  491. - education,
  492. - rehabilitation visualization,
  493. - forward kinematics,
  494. - ground locking,
  495. - ROM-constrained inverse kinematics,
  496. - hip hinging,
  497. - standing, seated, and lying poses,
  498. - basic scene props,
  499. - and browser-based rendering.
  500. ### Deferred
  501. The following are outside the current scope:
  502. - two-person or partner motion,
  503. - comprehensive collision detection and rigid-body dynamics,
  504. - detailed object physics,
  505. - advanced equipment simulation,
  506. - multi-joint finger animation,
  507. - FBX or GLB animation export,
  508. - and medical diagnosis.
  509. ---
  510. ## Limitations and Safety
  511. Posecode is an engineering and visualization project.
  512. Its range-of-motion values and biomechanical checks are based on general reference data and simplified models.
  513. They are not:
  514. - medical advice,
  515. - diagnosis,
  516. - injury-prevention guarantees,
  517. - physiotherapy prescriptions,
  518. - or a substitute for a qualified professional.
  519. Generated movements should be reviewed by a qualified expert before being used for healthcare, rehabilitation, or safety-critical applications.
  520. ---
  521. ## Potential Applications
  522. Posecode could support:
  523. - game and character animation,
  524. - fitness instruction,
  525. - exercise visualization,
  526. - anatomy education,
  527. - physiotherapy demonstrations,
  528. - posture training,
  529. - dance and choreography prototyping,
  530. - sports technique analysis,
  531. - robotics research,
  532. - synthetic motion-data generation,
  533. - and embodied AI systems.
  534. ---
  535. ## Repository Structure
  536. ```text
  537. posecode/
  538. ├── packages/
  539. │ ├── posecode-language/
  540. │ ├── posecode-parser/
  541. │ ├── posecode-render/
  542. │ ├── posecode-share/
  543. │ ├── posecode-mcp/
  544. │ └── posecode-eval/
  545. ├── playground/
  546. ├── editors/
  547. ├── spec/
  548. ├── docs/
  549. ├── scripts/
  550. └── README.md
  551. ```
  552. ---
  553. ## Testing
  554. Run all unit tests:
  555. ```bash
  556. npm test
  557. ```
  558. Run coverage:
  559. ```bash
  560. npm run coverage
  561. ```
  562. Run type checking:
  563. ```bash
  564. npm run typecheck
  565. ```
  566. Run biomechanical evaluations:
  567. ```bash
  568. npm run eval
  569. ```
  570. The CI workflow verifies that the project:
  571. - builds successfully,
  572. - passes type checking,
  573. - passes unit tests,
  574. - and satisfies configured movement invariants.
  575. ---
  576. ## Background
  577. Posecode follows the design study:
  578. > *Kinematic Motion Definition Protocols for Large Language Models*
  579. The project explores whether semantic, text-based movement programs can provide a controllable and inspectable alternative to black-box motion generation.
  580. ## Language Specification and Contracts
  581. Posecode separates its normative protocol definition from optional prompt aids:
  582. - **[Normative Protocol Specification (`spec/SPEC.md`)](spec/SPEC.md)** (or on the web at [posecode.org/spec.html](https://posecode.org/spec.html)): The authoritative specification defining grammar, bones, joint actions, range-of-motion limits, contact semantics (`ground-lock`, `reach`, `pin`, `grip`), solver invariants, and intermediate representation (IR).
  583. - **[LLM Authoring Guide (`spec/llm-authoring.md`)](spec/llm-authoring.md)** (or on the web at [posecode.org/llm-guide.html](https://posecode.org/llm-guide.html)): A self-contained, task-oriented prompt guide for drafting `.posecode` documents with generative models.
  584. ### Contact Semantics Quick Reference
  585. - **`pin moves the body`**: Translates the figure's floating root so an effector meets an anchor (`pin: knee_left floor`). A phase accepts at most one pin.
  586. - **`reach moves the limb`**: Directs inverse kinematics along the limb chain without translating the root (`reach: hand_left floor`).
  587. - **`ground-lock`**: Preserves existing planted support on the floor (`ground-lock: feet`). Multiple simultaneous ground contacts (such as both feet planted) must be handled by `ground-lock` or separate `reach` directives, never multiple pins.
  588. - **`grip`**: Two-hand support on a declared `bar` or `dip-bars` prop.
  589. - **`cue`**: Display-only coaching text; it never alters kinematics, constraints, or playback.
  590. See also:
  591. - [`docs/market-research.md`](docs/market-research.md)
  592. ---
  593. ## Character assets
  594. The hosted playground currently uses an Adobe Mixamo character and one showcase animation under the applicable Adobe terms. These binary assets are not covered by Posecode's software licenses. See [third-party notices](docs/legal/THIRD_PARTY_NOTICES.md).
  595. The renderer also includes a zero-asset procedural figure and accepts compatible humanoid GLB characters through `characterUrl`.
  596. ### Multiple character appearances (`avatar avatar1` / `avatar2` / `avatar3`)
  597. All built-in characters use the same `rig humanoid` skeleton topology. An
  598. optional `avatar` directive selects appearance without redefining that rig (see
  599. [`spec/SPEC.md`](spec/SPEC.md)). Pass `characterUrls` (selector → GLB URL map)
  600. to `createViewer` instead of a single `characterUrl`; `ir.avatar` is used when
  601. present and `ir.rig` supplies the default selector otherwise. Switching
  602. documents, or editing the `avatar` directive, swaps the visible character. A
  603. selector with no entry in the map (or any load failure) falls back to the
  604. procedural figure. See
  605. [`packages/posecode-render/README.md`](packages/posecode-render/README.md#usage)
  606. for the option, and `packages/posecode-embed`'s `character` attribute docs for
  607. the same behavior in the web component (absent by default; set an explicit URL
  608. to pin one character regardless of `avatar`).
  609. ### Bringing your own character rig
  610. Pass a `characterUrl` (fixed) or `characterUrls` (per-selector, see above) pointing
  611. to a skinned GLB to replace the bundled Mixamo character. Requirements:
  612. - **Format:** glTF binary (`.glb`) containing a `THREE.SkinnedMesh`.
  613. - **Rest pose:** T-pose.
  614. - **Bone naming:** Mixamo convention. Names may carry the `mixamorig:` /
  615. `mixamorigN:` namespace prefix — it's stripped automatically. These bones
  616. must all be present:
  617. - Torso/head: `Hips`, `Spine`, `Spine2`, `Neck`, `Head`
  618. - Arms: `LeftArm`, `LeftForeArm`, `LeftHand`, `RightArm`, `RightForeArm`, `RightHand`
  619. - Legs: `LeftUpLeg`, `LeftLeg`, `LeftFoot`, `RightUpLeg`, `RightLeg`, `RightFoot`
  620. - Fingers (first phalanx only): `LeftHandThumb1`, `LeftHandIndex1`,
  621. `LeftHandMiddle1`, `LeftHandRing1`, `LeftHandPinky1`, and the
  622. `RightHand*1` equivalents
  623. If any required bone is missing, loading the character rejects and the
  624. viewer silently falls back to the zero-asset procedural figure — a bad rig
  625. never breaks the scene.
  626. The simplest way to source a compatible rig is [mixamo.com](https://www.mixamo.com):
  627. export a character in T-pose with "skin with skeleton," then convert
  628. FBX → GLB (e.g. with Blender's glTF exporter or `FBX2glTF`). Bone names come
  629. out Mixamo-compatible automatically.
  630. The bone map and retarget/calibration logic live in
  631. [`packages/posecode-render/src/character.ts`](packages/posecode-render/src/character.ts).
  632. Supporting a different naming convention (e.g. VRM humanoid bones) means
  633. editing the `BONE_MAP` table and `plainName()` prefix-stripping there.
  634. ---
  635. ## Licensing
  636. Posecode is open source with a clear standard and product boundary:
  637. | Layer | Components | License |
  638. | --- | --- | --- |
  639. | Open standard | Specification, examples, parser, share codec, language service, LSP, VS Code extension | Apache-2.0 |
  640. | Product layer | Renderer, web embed, MCP server, eval harness, hosted playground | AGPL-3.0-only |
  641. Organizations that need to use an AGPL component in a closed-source product may contact [hello@posecode.org](mailto:hello@posecode.org?subject=Posecode%20commercial%20license) about a separate commercial agreement.
  642. Earlier grants are unchanged. MIT revisions remain MIT, and the 0.2.2 npm packages remain Apache-2.0. See [licensing](docs/legal/LICENSING.md), [commercial licensing](docs/legal/COMMERCIAL-LICENSE.md), and [trademark policy](docs/legal/TRADEMARK.md).
  643. ---
  644. ## Feedback and Support
  645. Feedback and contributions are welcome.
  646. - Email: [hello@posecode.org](mailto:hello@posecode.org?subject=Posecode%20Feedback)
  647. - Issues: [GitHub Issues](https://github.com/posecode-dev/posecode/issues)
  648. ---
  649. <p align="center">
  650. <b>Animation tools, LLMs, and web products need movement they can inspect.</b>
  651. <br />
  652. <b>Posecode makes movement readable source.</b>
  653. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.