Project structure

When you separate the kit (what Studio produces) from the haptic file (settings that add things like target), your code only calls event ids. The details of each event split into the following two layers.

The two layers

	What it holds	Who authors it
kit manifest (`<kit>-manifest.json`)	kit content: intensity / clip / command vs clip	auto-generated by Hapbeat Studio
haptic file (`haptics.json`, EventMap overlay)	app-side settings: target (which device/body part) / gain override	written by the developer (references the kit)

The manifest is “a description of the kit’s content” and does not hold which device/body part to play on (target) (where to play is an app/operational concern, so it is not put in the kit). The haptic file is what adds it.

Layout

my-app/
  app.py                          ← the firing side (just play an event id)
  haptics.json                    ← the haptic file (references the kit and adds target, etc.)
  kits/
    my-kit/
      my-kit-manifest.json        ← kit content (Studio-generated)
      install-clips/              ← command clips (flashed to the device via Studio)
      stream-clips/
        rain.wav                  ← the WAV the SDK streams in clip mode

// haptics.json
{
  "kit": "kits/my-kit",
  "events": {
    "sample-kit.sine_100hz": { "target": "player_1/chest", "gain": 0.8 },
    "rain.loop":  { "target": "*/back" }
  }
}

Your code only calls event ids

import hapbeat

hb = hapbeat.connect(app_name="MyApp", haptics="haptics.json")
hb.play("sample-kit.sine_100hz")     # to player_1/chest at gain 0.8 (the haptic file decides)
hb.play("rain.loop")      # clip stream to */back

connect(haptics=...) reads the haptic file, pulls in the manifest (intensity/clip) from its kit, and layers the overlay’s target/gain on top. The split is: only “when to play” is code, while “what / where / how strong” is the haptic file.

If you do not need targeting (broadcasting to all is fine), the kit alone is enough:

hb = hapbeat.connect(app_name="MyApp", kit="kits/my-kit")   # specify target per call via play(id, target=)

Authoring flow

Edit the kit in Hapbeat Studio (clips, intensity, command/clip).
Place the kit folder in your project’s kits/.
Write each event’s target (and gain if needed) in haptics.json.
Your code only calls play("event.id").

A fully runnable example: on GitHub, examples/clip_project/ (kit) and examples/osc_remote/ (haptic file + OSC).