Installation

npm install @balancy/core

Development Notes

Build

npm run build          # build core + webview, then copy to Unity plugin
npm run build:core     # build core only
npm run build:webview  # build webview + copy to Unity plugin

Unity Plugin Copy Path

The copy:webview:force script copies the built WebView bundle to the sibling plugin_cpp_unity repo:

plugin_cpp_typescript/packages/core/  -->  plugin_cpp_unity/WebView/Resources/WebGL/

This expects plugin_cpp_unity to be cloned as a sibling of plugin_cpp_typescript:

Projects/
  plugin_cpp_typescript/   <-- this repo
  plugin_cpp_unity/        <-- Unity plugin repo (sibling)

The copy is skipped in CI (CI=true). Locally, it runs automatically after build:webview.

Previously this path was hardcoded to Pavel's Mac (/Volumes/PavelData/Projects/...). It now uses a relative path and cross-platform Node.js fs.copyFileSync instead of cp, so it works on Windows (cmd.exe, PowerShell), macOS, and Linux.

Persistent WebView preparation (TypeScript)

Balancy.API.prepareWebView(onReady?) is explicit opt-in. It can be called before SDK initialization/data readiness; the request is remembered until onDataUpdated makes scripts available. Balancy.Main.stop() clears this intent.

Preparation installs the bridge and the current script bundle in a hidden iframe. Repeated View opens reuse that context and do not resend/recompile the bundle. On each internal data update, a prepared client compares script contents. Unchanged scripts preserve the shell. Changed scripts recreate an idle shell; an active View, including a hidden one, remains intact until its clear acknowledgement. Changes during preparation coalesce, and readiness waits for the final shell. A queued successor survives the replacement.

This matches the Unity persistent lifecycle. The low-level BalancyWebView class expects callers to supply scripts directly; automatic data readiness handling belongs to RenderViewsManager / the public SDK API.

See bridge ownership and memory checks for script cleanup responsibilities and diagnostics. Tests use mocked backend responses; validate the complete WASM/backend integration with your staging project before production.