hydra-three
Source: README.md

hydra-three

three.js-powered fork of hydra-synth focused on creative coding with 3D scene APIs while keeping Hydra-style live coding workflows.

Project status

  • This Hydra fork is not being actively developed anymore.
  • It is superseded by triode, a three.js (3D)-first live-coding environment built on Hydra and inspired by Hydra.
  • This repository remains available for historical reference and existing integrations.

Distribution Model

  • Official distribution for this fork is via GitHub tags and release artifacts from this repository.
  • CDN usage should reference a pinned tag in this repository.
  • The npm package name hydra-synth is owned upstream; this fork does not rely on upstream npm publishing for releases.
  • package.json is marked private: true to avoid accidental npm registry publish under the upstream package name.
  • Do not use npm i hydra-synth for this fork unless you intentionally want upstream hydra-synth.
  • For this fork, install from this repository tag: npm i github:kasparsj/hydra-three#v1.0.0 three.

Runtime Contract

  • Runtime target is browser execution (WebGL + DOM APIs required).
  • The ESM package entry is browser-only; importing in pure Node/SSR without a browser-like runtime is unsupported.
  • For server-side build pipelines, run Hydra code in browser contexts and publish artifacts from CI.

Project Site

  • GitHub Pages publishes docs and runnable examples from this repository.
  • Interactive playground: https://kasparsj.github.io/hydra-three/playground/index.html
  • Versioned docs are published under /docs/latest/ and /docs/vX.Y.Z/.
  • Local site build output: site-dist/
  • Build locally:
npm run build
npm run site:build
npm run site:build:versioned

10-minute quickstart

Option A: Browser script tag (fastest)

Use jsDelivr from this repository:

<script src="https://cdn.jsdelivr.net/gh/kasparsj/hydra-three@v1.0.0/dist/hydra-synth.js"></script>
<script>
  const hydra = new Hydra({ detectAudio: false });
  osc(8, 0.1, 0.8).out();
</script>

For production, pin to a release tag or commit (do not use floating refs).

Success criteria:

  • You see animated output immediately.
  • Hydra is available on window.

Option B: npm + bundler

npm i github:kasparsj/hydra-three#v1.0.0 three

Do not replace this with npm i hydra-synth; that resolves to the upstream package, not this fork.

import Hydra from "hydra-synth";

const hydra = new Hydra({
  detectAudio: false,
  makeGlobal: true,
});

osc(8, 0.1, 0.8).out();

Non-global mode is also supported:

import Hydra from "hydra-synth";

const hydra = new Hydra({
  detectAudio: false,
  makeGlobal: false,
});

const H = hydra.synth;
H.osc(8, 0.1, 0.8).out();

Vite note

If Vite reports ReferenceError: global is not defined, add:

define: {
  global: {},
}

Refs:

  • <https://github.com/vitejs/vite/discussions/5912#discussioncomment-1724947>
  • <https://github.com/vitejs/vite/discussions/5912#discussioncomment-2908994>

Local development

npm ci
npm run dev

This starts a Vite live-reload dev server using dev/index.html and dev/index.js.

Useful checks:

npm run ci:check
npm run lint
npm run typecheck
npx playwright install chromium firefox
npm run test:smoke:browser
npm run site:build

GUI note:

  • gui.init() now tries local vendored dat.gui first (/vendor/dat.gui.min.js, vendor/dat.gui.min.js), then CDN fallback.
  • If all script loads fail, it falls back to a no-op GUI object so runtime code does not crash.

Example

// setup perspective camera, enabling camera controls (alt+click to rotate, alt+scroll to zoom)
perspective([2, 2, 3], [0, 0, 0], { controls: true });

// create geometry and material
const geom = gm.box();
const mat = osc().rotate(noise(1).mult(45)).phong();

// compose scene
const sc = scene().lights().mesh(geom, mat).out();

update = () => {
  const box = sc.at(0);
  box.rotation.x += 0.01;
  box.rotation.y += 0.01;
};

More examples: examples/README.md

3D APIs (summary)

Camera

  • perspective(eye, target, options)
  • ortho(eye, target, options)

Scene

  • scene() creates a scene handle and exposes scene composition helpers.

Geometry

  • Geometry functions are exposed under gm.
  • Example: gm.box().

Material

  • Material functions are exposed under mt.
  • Example: mt.meshPhong().

Production guidance

Use these docs before shipping:

Trust signals

  • CI runs build + smoke + package checks on Node 20 and 22.
  • CI runs real Chromium and Firefox smoke tests of examples/quickstart.html on Node 20.
  • CI runs non-global and multi-instance 3D browser smoke tests on Chromium and Firefox.
  • CI validates all source examples for syntax integrity and runs generated examples + playground preset browser smoke coverage in Chromium.
  • Release tags (v*) run version/changelog/tag metadata verification and attach tarball + checksum artifacts.
  • GitHub Pages deploys generated docs and runnable examples from repository sources on every push to main.

License

AGPL-3.0-only (see LICENSE).

Generated from repository docs and examples.