# SuperHQ Motion experiment: playground

Controllable motion. Runs in your browser.

This is a research experiment, not a released model. It shows how far a small
learned locomotion model, combined with game-side runtime code and a few
authored clips, gets toward natural game movement. Expect visible artifacts.

## Controls

| Input | Action |
| --- | --- |
| W A S D | Move relative to the camera |
| Shift / Ctrl + Shift | Jog / sprint |
| Space | Jump (standing, walking, jogging or sprinting) |
| C | Toggle crouch |
| F / G | Dash / lunge |
| H | Knockback test (pushed away from the camera) |
| Drag, scroll, hold right mouse | Look, zoom, shoulder view |
| P / R | Pause / reset |

Open **?** to switch the display character (Eric or the joint mannequin) and
the display floor guard. Jumps and actions need the Natural style and standing
height; Carrying and Zombie styles do not support them.

## What is learned and what is code

| Part | Source |
| --- | --- |
| Idle, walk, jog, sprint, crouch, carrying and zombie poses | Learned locomotion model (616,591 parameters) |
| Standing crouch and standing jump poses | Learned action model (699,053 parameters) |
| Running jump | Learned stride plus runtime code: waits for a support foot, plants it with IK, drives push-off and landing compression, time-warps the stride's flight. Not a learned running-jump policy. |
| Dash, lunge, knockback and get-up, ledge climb | Authored CC0 clips replayed and blended into and out of the learned locomotion |
| Turning, strafing | Code rotates the forward gait; no learned strafe, backpedal or pivot |
| Gravity, collisions, horizontal travel | Example host physics |

The playground loads both model packages (1,315,644 parameters, about 5.26 MB
of FP32 weights) and runs inference locally at 60 Hz.

## Known limitations

- Running jumps take off 0.05–0.32 s after the press, because the jog stride
  has long airborne phases and takeoff waits for a foot on the ground.
- Feet slide during ordinary locomotion and in some transitions; turning is a
  code-driven rotation.
- Stopping from a run passes through a walk and takes about 1.5 s.
- Dash and lunge arms are posed for a shield and sword; the character holds
  nothing.
- The authored clips hold the head lowered by about 12° at idle and 20–23°
  when running. A constant 10.9° head-pitch conversion bias in the training
  data is removed before display.
- Ledge climbing needs a game-provided ledge and is not available in this
  flat playground.
- Development checks only; no blinded or user acceptance study.

## Run locally

Serve the Space directory over localhost and open `index.html`. HTTPS or
localhost is needed for weight checksum verification.

```sh
python3 -m http.server 8025 --bind 127.0.0.1
```

## JavaScript

```js
import {MotionGameController} from './src/game-controller.js';

const controller = await MotionGameController.load(
  new URL('./model/', location.href),
  new URL('./actions/', location.href),
  {clipsURL: new URL('./clips/action-clips.json', location.href)}
);

// At a fixed 60 Hz:
const pose = controller.step({moving: true, jog: true, heading: 0});
controller.requestJump();                       // once per input edge
controller.requestAction('dash');               // 'dash', 'lunge', 'knockback', 'climb'
controller.requestAction('knockback', {direction: [1, 0]});
```

`rootPosition` and `localQuaternions` describe the canonical pose. Apply
`worldPosition` and `heading` once as the parent transform. For display, pass
the pose through `correctHeadPitch` from `src/pose.js`.

A game can supply its own physics host with `reset()`, `state()`, `launch()`
and `step()`; `place(height)` is needed for climbing. An optional
`resolveHorizontal` callback passed to `step()` resolves travel against game
geometry. `rawComposedPose` and `blendCorrection` expose runtime corrections.

## Credits and licenses

Weights: CC BY 4.0. Runtime code: MIT. Locomotion data: 100STYLE (CC BY 4.0)
and Quaternius Universal Animation Library 1 and 2 (CC0). Character: "Eric
Rigged 001" by Renderpeople (CC BY 4.0). See ATTRIBUTION.md.