@ue-shed/observatory 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +53 -0
- package/dist/actor-feed.d.ts +90 -0
- package/dist/actor-feed.d.ts.map +1 -0
- package/dist/actor-feed.js +566 -0
- package/dist/actor-feed.js.map +1 -0
- package/dist/actor-identity.d.ts +6 -0
- package/dist/actor-identity.d.ts.map +1 -0
- package/dist/actor-identity.js +22 -0
- package/dist/actor-identity.js.map +1 -0
- package/dist/actor-models.d.ts +78 -0
- package/dist/actor-models.d.ts.map +1 -0
- package/dist/actor-models.js +28 -0
- package/dist/actor-models.js.map +1 -0
- package/dist/actor-stream-protocol.d.ts +86 -0
- package/dist/actor-stream-protocol.d.ts.map +1 -0
- package/dist/actor-stream-protocol.js +305 -0
- package/dist/actor-stream-protocol.js.map +1 -0
- package/dist/index.d.ts +173 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +161 -0
- package/dist/index.js.map +1 -0
- package/dist/presentation.d.ts +9 -0
- package/dist/presentation.d.ts.map +1 -0
- package/dist/presentation.js +8 -0
- package/dist/presentation.js.map +1 -0
- package/dist/world-observation.d.ts +232 -0
- package/dist/world-observation.d.ts.map +1 -0
- package/dist/world-observation.js +335 -0
- package/dist/world-observation.js.map +1 -0
- package/package.json +49 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 UE Shed contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# `@ue-shed/observatory`
|
|
2
|
+
|
|
3
|
+
Actor discovery, stable identity, bounded snapshots and deltas, retained spatial projection, and
|
|
4
|
+
focus operations. The first implemented slice powers Map Review's Live World Scout through validated
|
|
5
|
+
Remote Control calls and a local binary transform stream.
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
npm install --save-exact @ue-shed/observatory @ue-shed/unreal-connection
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Install the matching `UEShedObservatory` plugin from the same release manifest. The package is
|
|
12
|
+
headless: a host owns its own IPC/UI adaptation and no Workbench or extension UI is required.
|
|
13
|
+
|
|
14
|
+
## Live actor observation
|
|
15
|
+
|
|
16
|
+
`Observatory.observe(endpoint, options)` owns the full demand-driven observation lifecycle and
|
|
17
|
+
returns an Effect `Stream` of `WorldObservationState`:
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
Observatory.observe(endpoint, { cadenceHz: 30 }).pipe(
|
|
21
|
+
Stream.runForEach((state) => Effect.sync(() => render(state)))
|
|
22
|
+
);
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
It negotiates `StartActorObservation` over Remote Control, opens a scoped named-pipe server for the
|
|
26
|
+
returned pipe name, installs the actor catalog, and applies decoded USOT v1 transform batches into
|
|
27
|
+
`WorldObservationState` (`connecting` → `live` → `stale` → …). Resets and session changes reacquire a
|
|
28
|
+
fresh catalog automatically; sustained rejection or negotiation failure surfaces a typed
|
|
29
|
+
`ActorObservationSessionError` or `ActorObservationRecoveryExhaustedError` after a bounded number of
|
|
30
|
+
recovery attempts. `StopActorObservation` is always called when the stream's scope closes.
|
|
31
|
+
`Observatory.setObservationCadence(endpoint, cadenceHz)` retunes a running producer without closing
|
|
32
|
+
that stream's named-pipe session.
|
|
33
|
+
|
|
34
|
+
When the connected editor cannot stream (`not_supported`, e.g. non-Windows), `observe` falls back to
|
|
35
|
+
bounded `GetActorSnapshot` polling at ≤10 Hz and emits `polling_fallback` states instead of failing.
|
|
36
|
+
|
|
37
|
+
`snapshot` and `focus` remain for one-shot CLI and compatibility use.
|
|
38
|
+
|
|
39
|
+
The lower-level `ActorFeed` service (`actorFeedLayer`, `acquireActorFeedScoped`) owns just the
|
|
40
|
+
named-pipe transport and incremental USOT decoding, with a bounded sliding `PubSub` so a slow
|
|
41
|
+
subscriber only ever sees the newest packet rather than an unbounded backlog.
|
|
42
|
+
|
|
43
|
+
## Performance evidence
|
|
44
|
+
|
|
45
|
+
```powershell
|
|
46
|
+
pnpm benchmark:observatory # deterministic host decode/apply + Canvas paint
|
|
47
|
+
pnpm benchmark:observatory:live # running fixture editor in PIE; host + Workbench IPC/Canvas
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The live command defaults to `http://127.0.0.1:30001`; set `UE_SHED_REMOTE_CONTROL_ENDPOINT` to
|
|
51
|
+
override it. It validates `L_CameraLoad`, the three fixture class counts, and PIE before measuring
|
|
52
|
+
the Unreal producer, named-pipe host, and a real Electron Workbench World Scout presentation. The
|
|
53
|
+
Workbench phase must sustain at least 10 painted transform sequences per second.
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
import { type RemoteControlClientShape } from "@ue-shed/unreal-connection";
|
|
2
|
+
import { Context, Effect, Layer, Schema, type Scope, Stream } from "effect";
|
|
3
|
+
import { type ActorStreamPacket } from "./actor-stream-protocol.js";
|
|
4
|
+
import { type WorldObservationState } from "./world-observation.js";
|
|
5
|
+
export interface ActorFeedMetrics {
|
|
6
|
+
readonly bytesReceived: number;
|
|
7
|
+
readonly decodeLimitDrops: number;
|
|
8
|
+
readonly deliveryReplacements: number;
|
|
9
|
+
readonly malformedPackets: number;
|
|
10
|
+
readonly packetsReceived: number;
|
|
11
|
+
readonly startedMonotonicMs: number;
|
|
12
|
+
readonly transportErrors: number;
|
|
13
|
+
}
|
|
14
|
+
/** One accepted live packet as observed at the host boundary, for benchmarks and diagnostics. */
|
|
15
|
+
export interface ActorObservationDiagnostic {
|
|
16
|
+
readonly actorsChanged: number;
|
|
17
|
+
readonly actorsSampled: number;
|
|
18
|
+
readonly decodeApplyMs: number;
|
|
19
|
+
readonly missingSequences: number;
|
|
20
|
+
readonly producerReplacements: number;
|
|
21
|
+
readonly receiverReplacements: number;
|
|
22
|
+
readonly samplingDurationMicros: number;
|
|
23
|
+
readonly sequence: bigint;
|
|
24
|
+
}
|
|
25
|
+
declare const ActorFeedError_base: Schema.Class<ActorFeedError, Schema.TaggedStruct<"ActorFeedError", {
|
|
26
|
+
readonly message: Schema.String;
|
|
27
|
+
readonly operation: Schema.Literals<readonly ["listen", "decode_limit"]>;
|
|
28
|
+
readonly pipeName: Schema.String;
|
|
29
|
+
readonly retrySafe: Schema.Boolean;
|
|
30
|
+
}>, import("effect/Cause").YieldableError>;
|
|
31
|
+
export declare class ActorFeedError extends ActorFeedError_base {
|
|
32
|
+
}
|
|
33
|
+
export interface ActorFeedShape {
|
|
34
|
+
readonly latestPacket: Effect.Effect<ActorStreamPacket | undefined>;
|
|
35
|
+
readonly metrics: Effect.Effect<ActorFeedMetrics>;
|
|
36
|
+
readonly packets: Stream.Stream<ActorStreamPacket>;
|
|
37
|
+
}
|
|
38
|
+
declare const ActorFeed_base: Context.ServiceClass<ActorFeed, "@ue-shed/observatory/ActorFeed", ActorFeedShape>;
|
|
39
|
+
export declare class ActorFeed extends ActorFeed_base {
|
|
40
|
+
}
|
|
41
|
+
export interface ActorFeedOptions {
|
|
42
|
+
readonly capacity?: number;
|
|
43
|
+
readonly maxMalformedPackets?: number;
|
|
44
|
+
readonly pipeName: string;
|
|
45
|
+
}
|
|
46
|
+
/** Scoped acquisition usable directly (bypassing `Context`) when the pipe name is dynamic. */
|
|
47
|
+
export declare function acquireActorFeedScoped(options: ActorFeedOptions): Effect.Effect<ActorFeedShape, ActorFeedError, Scope.Scope>;
|
|
48
|
+
export declare function actorFeedLayer(options: ActorFeedOptions): Layer.Layer<ActorFeed, ActorFeedError>;
|
|
49
|
+
export declare function makeActorFeedTestLayer(feed?: Partial<ActorFeedShape>): Layer.Layer<ActorFeed>;
|
|
50
|
+
declare const ActorObservationControlError_base: Schema.Class<ActorObservationControlError, Schema.TaggedStruct<"ActorObservationControlError", {
|
|
51
|
+
readonly endpoint: Schema.String;
|
|
52
|
+
readonly message: Schema.String;
|
|
53
|
+
readonly operation: Schema.Literals<readonly ["start", "stop", "status"]>;
|
|
54
|
+
readonly retrySafe: Schema.Boolean;
|
|
55
|
+
readonly status: Schema.optional<Schema.Number>;
|
|
56
|
+
}>, import("effect/Cause").YieldableError>;
|
|
57
|
+
export declare class ActorObservationControlError extends ActorObservationControlError_base {
|
|
58
|
+
}
|
|
59
|
+
declare const ActorObservationSessionError_base: Schema.Class<ActorObservationSessionError, Schema.TaggedStruct<"ActorObservationSessionError", {
|
|
60
|
+
readonly endpoint: Schema.String;
|
|
61
|
+
readonly expectedSessionId: Schema.String;
|
|
62
|
+
readonly message: Schema.String;
|
|
63
|
+
readonly receivedSessionId: Schema.String;
|
|
64
|
+
}>, import("effect/Cause").YieldableError>;
|
|
65
|
+
export declare class ActorObservationSessionError extends ActorObservationSessionError_base {
|
|
66
|
+
}
|
|
67
|
+
declare const ActorObservationRecoveryExhaustedError_base: Schema.Class<ActorObservationRecoveryExhaustedError, Schema.TaggedStruct<"ActorObservationRecoveryExhaustedError", {
|
|
68
|
+
readonly attempts: Schema.Int;
|
|
69
|
+
readonly endpoint: Schema.String;
|
|
70
|
+
readonly message: Schema.String;
|
|
71
|
+
}>, import("effect/Cause").YieldableError>;
|
|
72
|
+
export declare class ActorObservationRecoveryExhaustedError extends ActorObservationRecoveryExhaustedError_base {
|
|
73
|
+
}
|
|
74
|
+
export interface ObserveActorFeedOptions {
|
|
75
|
+
readonly cadenceHz: number;
|
|
76
|
+
readonly capacity?: number;
|
|
77
|
+
readonly maxConsecutiveRejectedBatches?: number;
|
|
78
|
+
readonly maxMalformedPackets?: number;
|
|
79
|
+
readonly maxRecoveryAttempts?: number;
|
|
80
|
+
readonly onDiagnostic?: (diagnostic: ActorObservationDiagnostic) => Effect.Effect<void>;
|
|
81
|
+
readonly pipeName?: string;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Own the full observation lifecycle: negotiate `StartActorObservation`, install/reacquire
|
|
85
|
+
* catalogs, decode and apply transform packets, recover from reset/session faults with a bounded
|
|
86
|
+
* attempt budget, and always call `StopActorObservation` when the returned stream's scope closes.
|
|
87
|
+
*/
|
|
88
|
+
export declare function observeActorFeed(remote: RemoteControlClientShape, endpoint: string, options: ObserveActorFeedOptions): Stream.Stream<WorldObservationState, ActorObservationSessionError | ActorObservationRecoveryExhaustedError>;
|
|
89
|
+
export {};
|
|
90
|
+
//# sourceMappingURL=actor-feed.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"actor-feed.d.ts","sourceRoot":"","sources":["../src/actor-feed.ts"],"names":[],"mappings":"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"}
|