Sheepdog Sim

One dog, one flock, one field. A calm, cel-shaded browser game about guiding sheep through a pasture gate. Get behind the flock, move patiently and use a well-timed bark to bring stragglers home.

Play Sheepdog Sim · Controls and help · Report a bug

In the field

• Choose a flock of 25, 75 or 200 sheep and guide every sheep into the pen.
• Move, sprint and bark with keyboard, gamepad or touch controls.
• Switch between the overhead Classic camera and the closer Follow view.
• Find the entrance through an in-world highlight and an offscreen direction cue.
• Personalize your dog’s coat and name, choose flock breeds and name individual sheep in Studio. Compact phone controls leave room for the animal preview; larger screens use a side panel.
• Explore a golden-hour field with dense grass, authored trees, moving clouds, an animated farmhand and a quieter, spatial soundscape.
• Keep local personal bests and optionally compare online solo times for each flock size. Edit the running name assigned to your device.

Online identity and score requests are fail-soft. Play, completion and local personal bests continue when the score service is unavailable.

No account is required to play. This is the single-player version 3 client; campaign, survival and multiplayer modes are not included.

Controls

Action	Keyboard	Gamepad	Touch
Move	W A S D or arrows	Left stick	Left joystick
Sprint	Shift	Right trigger or A / Cross	Sprint button
Bark	Space	B / Circle or X / Square	Bark button
Change camera	C	Y / Triangle	Camera button
Pause	Escape or pause button	Use the on-screen pause button	Pause button

After stamina runs out, release Sprint and press again to start another sprint. Holding it down through recovery does not automatically restart it. Partial stick movement provides a slower walking pace.

Settings includes keyboard remapping, reduced motion, quality, audio levels and a colorblind dog marker. In Studio, drag the preview or use the orbit controls; choose a camera preset to inspect the dog from another angle.

Run locally

Requirements:

• Node.js 22 or newer;
• a current browser with WebGPU or WebGL2.

git clone https://github.com/matthew-kissinger/sds.git
cd sds
npm ci
npm run dev

Open the local URL printed by Vite.

The client runs without a local score server. To run the full test suite, including the retained score-service tests, install its dependencies too:

npm ci --prefix worker

Useful commands:

npm test
npm run lint
npm run typecheck
npm run typecheck:worker
npm run build
npm run preview
npm run probe:boot
npm run probe:release
npm run check:discovery

Run npm run build before the preview and built-artifact checks. See the testing guide for validation expectations. Current evidence and remaining device or performance limitations are tracked in STATUS.md.

Architecture

The application is split into four deliberate boundaries:

sim/       deterministic fixed-step herding simulation
app/       React Three Fiber, Three.js, input, audio and player interface
assets/    runtime assets plus editable sources and bake manifests
tools/     deterministic bakes, diagnostics and release verification
worker/    retained identity and score service; separate from the v3 client

The simulation imports no Three.js, React, DOM or network code. The renderer uses one TSL material path for WebGPU and WebGL2. Zustand is the shared state authority for the scene and player interface.

The field is assembled from reproducible source:

• terrain, grass, treeline and scatter placement are deterministic bakes;
• the active treeline is an original, procedurally authored sculpted-oak family, baked into instanced geometry with no external model loading;
• sheep, the skinned dog and farmer, fences and farm structures are code-authored;
• material and atmosphere systems are TSL source;
• every audio file is a committed, provenance-tracked source with its provider, prompt, processing, duration, size and digest recorded in the audio ledger;
• authoring concepts are retained separately from runtime assets.

Read the version 3 architecture reset for what was retained from version 2, what was removed and why the codebase was rebuilt. Asset-specific recipes and provenance are documented under assets/, including trees, dog, farmer and audio.

Release discipline

Production deploys use the manually dispatched Pages workflow, pinned to a full commit SHA on main. It installs dependencies, runs lint, typechecks, tests and the build, archives the artifact, then verifies the live release and discovery pages.

Contributor checks additionally cover:

• deterministic fixtures and a running production preview;
• a built-artifact scan that permits only the score REST client and excludes rooms, WebSockets, multiplayer, deferred scale and debug code;
• complete 25, 75 and 200 sheep runs on both renderer backends;
• desktop and mobile interaction, layout and audio checks;
• asset source, license, secret and local-artifact checks;
• release and rollback procedures for the static client.

The deployed release manifest records the source commit and artifact identity. Device coverage and performance numbers in STATUS.md describe measured configurations, not a guarantee for every phone or PC. Production publication requires owner approval.

Public builds contain no multiplayer client, room flow, bundled Worker or 5,000-sheep code. Solo-time boards use the existing score service through the isolated field-v3 partition. Multiplayer remains a future product decision, not a dormant launch flag.

Contributing

Start with CONTRIBUTING.md, then read AGENTS.md and the relevant document under spec/. The spec is the product contract. When implementation and spec disagree, document the decision rather than adding a compatibility branch.

Bug reports should include the browser, device, renderer backend, flock size, seed when known, reproduction steps and console output. Security issues should follow SECURITY.md.

License

Source code is licensed under GNU AGPL-3.0-or-later, copyright Matthew Kissinger.

Runtime and authoring assets are covered by the asset ledger and LICENSE-ASSETS. Do not assume a code license applies to third-party or generated media. Hosted modified versions must provide corresponding source and retain the applicable notices.