hydra-three
Source: docs/getting-started.md

Getting Started

This guide is optimized for first success in under 10 minutes. Official distribution for this fork is via pinned Git tags and artifacts in this repository. This repository is intentionally private: true in package.json to prevent accidental npm registry publish under the upstream package name.

Runtime note: this package targets browser execution. Importing it in pure Node/SSR without a browser-like runtime is unsupported.

1. Choose your runtime path

Script tag (fastest)

<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 tag or commit (avoid floating refs).

npm + bundler

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

Important: npm i hydra-synth installs upstream hydra-synth, not this fork.

import Hydra from "hydra-synth";

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

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

For non-global mode:

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();

In non-global mode, assign lifecycle hooks through hydra.synth:

const H = hydra.synth;
H.update = () => {};

2. Confirm baseline behavior

You should see:

  • a canvas attached to the page
  • animated output
  • no runtime exceptions in console

3. Try a 3D sample

perspective([2, 2, 3], [0, 0, 0], { controls: true });
const sc = scene().lights().mesh(gm.box(), osc().phong()).out();

You can also run examples from the GitHub Pages site examples gallery. For parameter-editable sketches, use the interactive playground at https://kasparsj.github.io/hydra-three/playground/index.html.

4. Local project setup

npm ci
npm run dev
npm run ci:check
npx playwright install chromium firefox
npm run test:smoke:browser

The repo dev entrypoint is dev/index.js.

GUI fallback behavior:

  • GUI init tries local vendored dat.gui first.
  • If unavailable, runtime falls back to a no-op GUI adapter instead of throwing.

5. Known Vite issue

If you get ReferenceError: global is not defined, add:

define: {
  global: {},
}

See:

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

6. Continue with core docs

Generated from repository docs and examples.