@uptimizr/unreal 0.1.0

package/bridge/Uptimizr.h

@@ -0,0 +1,103 @@
+// Uptimizr — Unreal Engine (web export) telemetry bridge shim (copy-in asset).
+//
+// This is the engine-side half of the `@uptimizr/unreal` connector (ADR 0045). It is a
+// thin, dumb Emscripten shim: each frame it reads the active `APlayerCameraManager` pose
+// and FPS, and (on demand) a raycast pick, then pushes the RAW values across the JS
+// interop boundary to the browser-side connector exposed on `window.__uptimizr_unreal__`.
+//
+// It carries NO analytics logic, NO identifiers, and NO schema knowledge. It performs NO
+// coordinate math: it pushes Unreal's native world-space values (left-handed, z-up,
+// centimeters) unchanged. The JS connector owns the single normalization path
+// (z-up -> y-up rebase, cm -> m scale) so every engine stays consistent.
+//
+// Feasibility (ADR 0045 / issue #112): Epic has no official UE5 HTML5/WASM target (it was
+// deprecated after UE 4.24) and Pixel Streaming is server-side. This shim therefore targets
+// the real, Emscripten-based, client-side web exports that DO exist and render into a
+// `<canvas>`: the community UE4.24-4.27 HTML5 forks (ufna/UE-HTML5,
+// SpeculativeCoder/UnrealEngine-HTML5-ES3) and the experimental Wonder Interactive /
+// SimplyStream UE5.1-5.4 WASM+WebGPU toolchain. All are Emscripten, so the EM_JS / cwrap
+// interop this shim relies on is available by construction. Outside Emscripten (e.g. the
+// desktop editor) every entry point compiles to a no-op so it is safe to leave wired in.
+//
+// Privacy (ADR 0003): only low-cardinality, non-PII telemetry crosses the bridge — poses,
+// FPS, and developer-assigned object names. The shim MUST NOT invent identifiers or forward
+// raw input text.
+
+#pragma once
+
+#include "CoreMinimal.h"
+
+class UWorld;
+
+/**
+ * Wire-protocol version this shim was authored against. It MUST match the JS connector's
+ * `BRIDGE_PROTOCOL_VERSION` (see `@uptimizr/web-export`). `FUptimizrTelemetry::Initialize`
+ * asserts the live bridge reports the same value before pushing anything.
+ */
+#define UPTIMIZR_BRIDGE_PROTOCOL_VERSION 1
+
+/**
+ * Per-frame telemetry sampler for an Unreal web export. Construct one (or use the global
+ * accessed by the `extern "C"` entry points below), `Initialize()` once the export's host
+ * page and the `@uptimizr/unreal` connector are up, then call `Tick()` every frame from any
+ * actor/component tick. Push picks from your own click/interaction handler via `ReportPick`
+ * or the convenience `TraceAndReportPick`.
+ */
+class FUptimizrTelemetry
+{
+public:
+	/**
+	 * Read the live bridge's `protocolVersion` and assert it equals
+	 * `UPTIMIZR_BRIDGE_PROTOCOL_VERSION`. Returns false (and stays disabled) on mismatch or
+	 * when no bridge is present, so a stale shim never pushes against an incompatible API.
+	 */
+	bool Initialize();
+
+	/** True once `Initialize()` has succeeded against a compatible bridge. */
+	bool IsInitialized() const { return bInitialized; }
+
+	/**
+	 * Sample the active camera pose and accumulate FPS, pushing a pose every frame and a
+	 * perf sample roughly once per second. Pass the world your gameplay runs in and the
+	 * frame's delta seconds. No-op until `Initialize()` succeeds.
+	 */
+	void Tick(UWorld* World, float DeltaSeconds);
+
+	/**
+	 * Push a developer-named object and the RAW world-space hit point (cm, z-up,
+	 * left-handed). Call this from your own interaction code when a pick resolves.
+	 */
+	void ReportPick(const FString& ObjectName, const FVector& WorldHitPoint);
+
+	/**
+	 * Convenience: line-trace forward from the active camera and, on a hit, report the hit
+	 * actor's name + impact point via {@link ReportPick}. Returns true if something was hit.
+	 */
+	bool TraceAndReportPick(UWorld* World, float MaxDistanceCm = 1.0e5f);
+
+	/** Stop pushing; safe to call repeatedly. */
+	void Shutdown();
+
+private:
+	bool bInitialized = false;
+
+	// FPS / long-frame accumulation across a ~1s reporting window.
+	float PerfWindowSeconds = 0.0f;
+	int32 PerfWindowFrames = 0;
+	int32 PerfWindowLongFrames = 0;
+};
+
+/** Access the process-wide telemetry instance the `extern "C"` entry points drive. */
+FUptimizrTelemetry& UptimizrTelemetry();
+
+// cwrap / ccall entry points — let the JS host drive init/teardown by symbol name if it
+// prefers (e.g. `Module.cwrap('UptimizrBridge_Init', 'number', [])`). The per-frame Tick is
+// intentionally NOT exported: drive it from C++ where the world/delta are already in hand.
+extern "C"
+{
+	/** Initialize the global sampler. Returns 1 on success, 0 on protocol mismatch / no bridge. */
+	int UptimizrBridge_Init();
+
+	/** Shut the global sampler down. */
+	void UptimizrBridge_Shutdown();
+}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import type { EngineBridge, NativeFrame, TrackWebExportOptions, WebExportCollectorOptions, WebExportSession } from "@uptimizr/web-export";
+import type { Collector } from "@uptimizr/sdk-core";
+/**
+ * Unreal's native world coordinate frame: left-handed, **z-up**, **centimeters**
+ * (`unitScale: 100` = 100 world units per meter).
+ */
+export declare const UNREAL_FRAME: NativeFrame;
+/** The engine id used for connector provenance and the collector name. */
+export declare const UNREAL_CONNECTOR_NAME = "unreal";
+export type UnrealCollectorOptions = Omit<WebExportCollectorOptions, "name" | "frame">;
+export type TrackUnrealOptions = Omit<TrackWebExportOptions, "name" | "frame">;
+/**
+ * The Unreal collector — register it with an sdk-core client via `client.use(...)`.
+ * Wires the JS-only tier and exposes the engine bridge (default global
+ * `window.__uptimizr_unreal__`) for the engine-side shim. See the package docs for
+ * the web-target feasibility caveat.
+ */
+export declare function unrealCollector(options?: UnrealCollectorOptions): Collector;
+/**
+ * One-call Unreal integration: create a client, register {@link unrealCollector},
+ * and start the session with Unreal's connector provenance (ADR 0018). Returns the
+ * client and the {@link EngineBridge} the Unreal shim pushes through.
+ */
+export declare function trackUnreal(options: TrackUnrealOptions): WebExportSession;
+export type { EngineBridge };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,qBAAqB,EACrB,yBAAyB,EACzB,gBAAgB,EACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,WAAiE,CAAC;AAE7F,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,WAAW,CAAC;AAE9C,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,yBAAyB,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;AACvF,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,qBAAqB,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;AAE/E;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,SAAS,CAE/E;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,gBAAgB,CAEzE;AAED,YAAY,EAAE,YAAY,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,50 @@
+/**
+ * `@uptimizr/unreal` — the Unreal Engine (web export) connector for Uptimizr
+ * (ADR 0045). **Best-effort, pending a viable WASM/HTML5 target.**
+ *
+ * Epic deprecated the official HTML5/Emscripten target after UE 4.24, and Pixel
+ * Streaming renders server-side (no client WASM scene to read), so the bridged tier
+ * does not fit a stock modern Unreal build today. The package and bridge contract
+ * are defined now so they drop in cleanly if a community HTML5 fork or a future
+ * official web target appears. The **JS-only tier works on any web export** that
+ * renders into a `<canvas>`.
+ *
+ * This connector is **two-part**:
+ *
+ * - a **JS-only tier** (this package, no engine code) — pointer heatmaps, rAF FPS,
+ *   and error capture straight from the canvas DOM; and
+ * - a **bridged tier** — a thin engine-side shim (an Emscripten `EM_JS` / `cwrap`
+ *   shim from the C++ web target, see `bridge/`) pushes camera pose / picks / perf
+ *   over the versioned {@link EngineBridge}.
+ *
+ * Unreal's native world frame is **left-handed, z-up, centimeters**. It is the only
+ * engine that exercises the non-`y` up-axis and non-1 unit-scale paths: world-space
+ * payloads are rebased z-up → y-up **and** scaled cm → m before reaching the
+ * canonical wire frame (ADR 0018 / ADR 0045 §5).
+ */
+import { trackWebExport, webExportCollector } from "@uptimizr/web-export";
+/**
+ * Unreal's native world coordinate frame: left-handed, **z-up**, **centimeters**
+ * (`unitScale: 100` = 100 world units per meter).
+ */
+export const UNREAL_FRAME = { handedness: "left", upAxis: "z", unitScale: 100 };
+/** The engine id used for connector provenance and the collector name. */
+export const UNREAL_CONNECTOR_NAME = "unreal";
+/**
+ * The Unreal collector — register it with an sdk-core client via `client.use(...)`.
+ * Wires the JS-only tier and exposes the engine bridge (default global
+ * `window.__uptimizr_unreal__`) for the engine-side shim. See the package docs for
+ * the web-target feasibility caveat.
+ */
+export function unrealCollector(options = {}) {
+    return webExportCollector({ ...options, name: UNREAL_CONNECTOR_NAME, frame: UNREAL_FRAME });
+}
+/**
+ * One-call Unreal integration: create a client, register {@link unrealCollector},
+ * and start the session with Unreal's connector provenance (ADR 0018). Returns the
+ * client and the {@link EngineBridge} the Unreal shim pushes through.
+ */
+export function trackUnreal(options) {
+    return trackWebExport({ ...options, name: UNREAL_CONNECTOR_NAME, frame: UNREAL_FRAME });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAU1E;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAgB,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC;AAE7F,0EAA0E;AAC1E,MAAM,CAAC,MAAM,qBAAqB,GAAG,QAAQ,CAAC;AAK9C;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkC,EAAE;IAClE,OAAO,kBAAkB,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,qBAAqB,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;AAC9F,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,OAA2B;IACrD,OAAO,cAAc,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,qBAAqB,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;AAC1F,CAAC"}