SnapBeat SDK

Package: com.amanotes.snapbeat
Version: 1.8.0

Unity WebGL SDK for HTML/JavaScript control of rhythm games with external song loading and game state management.

Features

• 🎮 WebGL JavaScript API for external control
• 🎯 Song data loading from JSON
• 🎨 Game state management (Play, Pause, Stop, Seek)
• 🚀 Audio timing synchronization
• 🔧 Event callbacks for game events

Documentation

• Architecture (read first): Docs/SnapBeat-Architecture.md
• Implementation guide: Docs/SnapBeat-Implementation-Guide.md
• Readiness gate: Docs/readiness-gate.md

Installation

1. Add the package

Add to Packages/manifest.json:

{
  "dependencies": {
    "com.amanotes.snapbeat": "1.8.0"
  },
  "scopedRegistries": [
    {
      "name": "npmjs",
      "url": "https://registry.npmjs.org/",
      "scopes": [
        "com.amanotes"
      ]
    }
  ]
}

2. Project setup

After Unity resolves the package, wire the WebGL template, scene, and SDK prefab.

Automated (recommended): Window → SnapBeat → Setup

This imports the WebGL template if needed, sets Player Settings → WebGL → Template to SnapBeat, creates host assets under Assets/AmaDev/SnapBeat/ (prefab + build config), wires SnapBeatData Folder to Assets/AmaDev/SnapBeat/SnapBeatData, and adds an unpacked SnapBeatSDK to the current scene. It does not edit Build Settings — add your scenes manually.

GDK development: edit the live template at MagicTilesDev/Assets/WebGLTemplates/SnapBeat/, then Window → SnapBeat → Export WebGL Template Package to refresh SnapBeat-WebGLTemplate.unitypackage.

Manual:

1. Import WebGL template — double-click
   Packages/com.amanotes.snapbeat/SnapBeat-WebGLTemplate.unitypackage
   and import into Assets/WebGLTemplates/SnapBeat/.
2. Set WebGL template — Edit → Project Settings → Player → WebGL → Publishing Settings → Template → SnapBeat.
3. Add SnapBeatSDK to your scene — either:
   • GameObject → Amanotes → SnapBeatSDK, or
   • drag Packages/com.amanotes.snapbeat/Runtime/SnapBeatSDK-RhythmEngine.prefab into the Hierarchy.
4. Build Settings — add your game scenes for WebGL (order matters if using Load Next Scene).
5. Wire your game — on RhythmEngineGameController, assign your game's RhythmContext in the Inspector (see the implementation guide).

HTML callbacks (setup flow)

SnapBeat uses one bridge GameObject named SnapBeatSDK:

| Direction | Mechanism | |-----------|-----------| | JS → Unity | unityInstance.SendMessage("SnapBeatSDK", "MethodName", arg) — method must be public on any component attached to that GameObject | | Unity → JS | SnapBeatSDK.SendMessageToWeb(json) → window.SendMessageToWeb(json) in index.html |

Recommended wiring (Editor only)

1. Scene 0: SnapBeatSDK prefab (DontDestroyOnLoad) — bootstraps and optionally loads another scene when Load Next Scene is enabled.
2. Same GameObject: add your HTML callback handler — RhythmEngineGameController, ExampleGameController, or your own script with StartGame / PauseGame / etc.
3. Window → SnapBeat → Setup adds a default game controller only when none are present yet.
4. With RhythmEngine: assign RhythmContext on RhythmEngineGameController in the Inspector.

Smoke test from browser console

unityInstance.SendMessage("SnapBeatSDK", "PingHost", "hello");
// Unity logs: [SnapBeat ← HTML] PingHost("hello")
// Unity sends: {"type":"pong","echo":"hello"} to window.SendMessageToWeb

Quick Start

1. Complete Installation above (Window → SnapBeat → Setup or manual steps).
2. Build for WebGL and open the host page — copy SnapBeatData/ into the build output (via build config SnapBeatData Folder), then the template auto-loads the fixture from theme-commands.txt.
3. Drive the game from JavaScript — public methods on the SnapBeatSDK GameObject:

// After the Unity instance is ready:
unityInstance.SendMessage("SnapBeatSDK", "LoadSongData", "https://example.com/song.json");
unityInstance.SendMessage("SnapBeatSDK", "StartGame");
unityInstance.SendMessage("SnapBeatSDK", "PauseGame");
unityInstance.SendMessage("SnapBeatSDK", "SeekGame", "5000");

// Smoke test (on SnapBeatSDK):
unityInstance.SendMessage("SnapBeatSDK", "PingHost", "hello");

Unity events back to the page go through window.SendMessageToWeb(json). See HTML callbacks above and Docs/SnapBeat-Implementation-Guide.md for the full handler list.

API Reference

Key classes

SnapBeatSDK (bridge only — does not implement game commands)

• SendMessageToWeb(json) — Unity → JS
• SetReadiness(id, ready) — readiness gate
• PingHost(message) — smoke test

RhythmEngineGameController (when MagicTilesCore is installed)

• HTML → Unity: LoadSongData, StartGame, PauseGame, ResumeGame, StopGame, SeekGame, SetAutoPlay, SetAudioSpeed
• Assign RhythmContext in the Inspector

ExampleGameController (without RhythmEngine)

• Same method names as above; logs only — replace with your controller

See: Architecture and Implementation Guide

Dependencies

• Unity 2021.3+
• Unity WebGL platform
• com.amanotes.rhythmjson: 2.1.0
• com.unity.nuget.newtonsoft-json: 3.0.0

Version History

See CHANGELOG.md