In the DSH (DeepSeek Harness) ecosystem, the petween plugin is responsible for animation orchestration and scheduling. However, pets are usually only static displays or have simple positional movement, lacking interactivity. petween-physics (package name petween-physics) is a companion plugin for petween that adds a physics engine layer to pets. It treats pets as entities affected by gravity, supporting physics behaviors such as drag-and-throw, wall bouncing, ground sliding, and grab-back.

Core Features

The plugin provides a complete throwing physics model, with the following core capabilities:

  1. Drag-and-throw: During dragging, the plugin estimates hand speed within a sampling window. Upon release, the pet launches based on the estimated velocity.
  2. Motion simulation: The pet falls under gravity and bounces off the four walls of the screen. The physics engine ensures the pet always remains within the viewport.
  3. Collision feedback: When hitting a wall, the plugin can play a squash (deformation) animation, or switch to a specific pose image, then restore it after a set duration.
  4. Ground logic: When the bounce height falls below a configured threshold, the pet transitions into ground-sliding mode, decelerating under ground friction until it settles. If the release speed is too low, it simply stays in place without launching.
  5. Interaction control: Users can grab the pet back at any time during flight. Once the pet settles, its position is automatically persisted. When the page becomes hidden or the session ends, the pet settles immediately. When not flying, the plugin does not hold position control.

Installation and Enablement

Before use, the following environment requirements must be met:

  • Main plugin dependency: petween (version ≥ 1.2.0) must be installed first.
  • Build tooling: Node.js version ≥ 22.18, and pnpm.

Installation steps:

  1. Clone the repository locally:
    git clone https://github.com/Traveritas/petween-physics.git
    cd petween-physics
  1. Install dependencies and build (the repository does not include build artifacts; this must be executed before use):
    pnpm install
    pnpm run build
  1. Register the plugin in DSH (link: points to the local clone directory):
    dsh plugin --profile web add link:/path/to/petween-physics
  1. Restart dsh web to apply the configuration.

Configuration and Parameters

All physics parameters can be adjusted at runtime through settings cards and are automatically saved to disk.

Settings Card Location

Open the DSH settings panel. After the main plugin “Petween” card, you can find the “Petween Physics” card.

Configuration File

The configuration file is stored at ~/.dsh/petween-physics/config.json (i.e., $DSH_HOME/petween-physics/config.json). When upgrading from an older version of dsh-motion-pet-physics, configuration is automatically migrated to this directory on first launch.

Main Parameters

The card contains the following grouped settings:
* Physics: gravitational acceleration, elasticity coefficient, horizontal air damping, launch multiplier, settle speed threshold, etc.
* Wall-hit animation: enable/disable deformation animation, select animation ID, whether to interrupt the current animation.
* Wall-hit image switching: enable/disable image switching, select pose slot, hold duration.
* Ground sliding: minimum bounce height, ground friction, sliding animation ID.
* Collision box: whether to ignore transparent pixels, transparent pixel threshold.
* Advanced: sampling window, debounce time, tolerance, etc.

Uninstallation Notes

Uninstalling the plugin does not delete the registered default bounce animation (user:physics-bounce-pop). These animations remain in the main plugin petween’s animation library and can be managed by the user in the main plugin editor.

Working Principle

The plugin uses a dual-host architecture:

  • Host side: responsible for registering the HTTP API (GET/PUT /api/petween-physics/config), atomically writing the configuration file, and registering default animations to the main plugin’s animation library when the service is available.
  • Client side: responsible for physics calculations (semi-implicit Euler integration) and interaction logic. It communicates with the main plugin through the slots system, subscribes to drag gestures and requests position control, and calculates bounce height to determine whether to continue bouncing or enter sliding mode.

Development and Extension

The plugin’s source code has a clear structure, divided into Host and Client entry points for easier maintenance.

Development Commands

pnpm test          # Run tests
pnpm run typecheck # Type checking
pnpm run build     # Build lib/

Dual-Host Form

In addition to the DSH Web plugin form, the plugin also supports a Petween Desktop desktop companion entry. This means the plugin can reuse the same physics logic and service interfaces in desktop applications.