openrtc-netcode-react 3.0.1 → 3.0.2

package/README.md

@@ -1,21 +1,31 @@
 # openrtc-netcode-react
 
-React context and hooks for `openrtc-netcode`.
+React context and hooks for an explicitly activated `openrtc-netcode` client.
 
 ```tsx
-import { NetcodeProvider, usePeers, useNetVar } from 'openrtc-netcode-react';
+import { NetcodeProvider, useNetVar } from 'openrtc-netcode-react';
 
 function Score() {
-  const peers = usePeers();
   const [score, setScore] = useNetVar('score', 0);
-  return <button onClick={() => setScore(score + 1)}>{peers.length}: {score}</button>;
+  return <button onClick={() => void setScore(score + 1)}>{score}</button>;
 }
-
-export function App() {
-  return (
-    <NetcodeProvider options={{ apiKey: 'pk_live_...' }}>
-      <Score />
-    </NetcodeProvider>
-  );
+// Construct and join client with your activated OpenRTC Room first.
+export function Game({ client }) {
+  return <NetcodeProvider client={client} autoStart={false}><Score /></NetcodeProvider>;
 }
 ```
+
+`useNetVar` follows key/client changes and state reset without retaining retired
+match handles. Ownership still applies; a non-owner setter rejects. Provider
+auto-start errors go to `onError` (or console.error), including cleanup errors.
+Keep a supplied client and options stable across ordinary renders.
+
+For high-frequency 3D rendering, use `useNetworkObjectIds(kind)` for structure
+and `client.objects.read(id)` in the engine frame loop; sample a SnapshotBuffer
+into pooled vectors. This avoids collection clones and React renders for motion.
+`useNetworkObject(id)` and `useNetworkObjects(kind)` suit lower-frequency UI.
+Objects returned by imperative read and hooks are deeply frozen. Use object
+mutation APIs rather than changing nested fields.
+
+Wire v2 requires the coordinated major release; see core netcode migration,
+authority, bounds and validation documentation.

package/dist/index.d.ts

@@ -4,14 +4,18 @@ export interface NetcodeProviderProps extends PropsWithChildren {
     client?: NetcodeClient;
     options?: NetcodeOptions;
     autoStart?: boolean;
+    onError?: (error: Error) => void;
 }
-export declare function NetcodeProvider({ client, options, autoStart, children }: NetcodeProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<NetcodeClient | null>>;
+export declare function NetcodeProvider({ client, options, autoStart, onError, children }: NetcodeProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<NetcodeClient | null>>;
 export declare function useNetcode(): NetcodeClient;
 export declare function useLobby(): NetcodeLobby | null;
 export declare function usePeers(): NetcodePeer[];
 export declare function usePeerStats(): NetcodePeerStats[];
 export declare function useNetVar<T>(key: string, initial: T, options?: NetVarOptions): [T, (value: T) => Promise<void>];
 export declare function useNetworkObjects(kind?: string): NetcodeObjectState[];
+/** Entity presence only. Motion is read imperatively without React rerenders. */
+export declare function useNetworkObjectIds(kind?: string): readonly string[];
+export declare function useNetworkObject(id: string): Readonly<NetcodeObjectState> | undefined;
 export declare function useNetcodeVoicePeers(): NetcodeVoicePeer[];
 export declare function useNetcodeEvent<K extends NetcodeEventName>(event: K, handler: (payload: NetcodeEvents[K]) => void): void;
 export declare function useNetcodeMessage<T = unknown>(type: string, handler: MessageHandler<T>): void;

package/dist/index.js

@@ -1,15 +1,24 @@
-import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useState, } from 'react';
+import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from 'react';
 import { createNetcode, } from 'openrtc-netcode';
 const NetcodeContext = createContext(null);
-export function NetcodeProvider({ client, options, autoStart = true, children }) {
+export function NetcodeProvider({ client, options, autoStart = true, onError, children }) {
     const resolvedClient = useMemo(() => client ?? createNetcode(options), [client, options]);
+    const errorHandler = useRef(onError);
+    errorHandler.current = onError;
     useEffect(() => {
         if (!autoStart) {
             return undefined;
         }
-        void resolvedClient.start();
+        const reportError = (error) => {
+            const reason = error instanceof Error ? error : new Error(String(error));
+            if (errorHandler.current)
+                errorHandler.current(reason);
+            else
+                console.error('[openrtc-netcode-react] client lifecycle failed', reason);
+        };
+        void resolvedClient.start().catch(reportError);
         return () => {
-            void resolvedClient.stop();
+            void resolvedClient.stop().catch(reportError);
         };
     }, [autoStart, resolvedClient]);
     return createElement(NetcodeContext.Provider, { value: resolvedClient }, children);
@@ -24,7 +33,11 @@ export function useNetcode() {
 export function useLobby() {
     const client = useNetcode();
     const [lobby, setLobby] = useState(() => client.lobby);
-    useEffect(() => client.on('lobby', setLobby), [client]);
+    useEffect(() => {
+        const stop = client.on('lobby', setLobby);
+        setLobby(client.lobby);
+        return stop;
+    }, [client]);
     return lobby;
 }
 export function usePeers() {
@@ -71,22 +84,70 @@ export function usePeerStats() {
 }
 export function useNetVar(key, initial, options) {
     const client = useNetcode();
-    const netVar = useMemo(() => client.state.define(key, initial, options), [client, key]);
-    const [value, setValue] = useState(() => netVar.value);
-    useEffect(() => netVar.onChange((next) => setValue(next)), [netVar]);
-    const setNetVar = useCallback((next) => netVar.set(next), [netVar]);
+    const store = useMemo(() => {
+        client.state.define(key, initial, options);
+        const read = () => {
+            const value = client.state.get(key);
+            return value === undefined ? initial : value;
+        };
+        let snapshot = read();
+        return {
+            getSnapshot: () => snapshot,
+            subscribe: (notify) => {
+                const stop = client.state.subscribe(key, () => { snapshot = read(); notify(); });
+                snapshot = read();
+                return stop;
+            },
+            set: (next) => client.state.define(key, initial, options).set(next),
+        };
+    }, [client, key, options?.owner]);
+    const value = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+    const setNetVar = useCallback((next) => store.set(next), [store]);
     return [value, setNetVar];
 }
 export function useNetworkObjects(kind) {
     const client = useNetcode();
     const [objects, setObjects] = useState(() => filterObjects(client.objects.list(), kind));
     useEffect(() => {
-        const refresh = () => setObjects(filterObjects(client.objects.list(), kind));
+        const refresh = () => setObjects(client.objects.ids(kind)
+            .map((id) => client.objects.read(id)));
         refresh();
-        return client.objects.onChange(refresh);
+        return client.objects.onChange((change) => {
+            if (change.type === 'snapshot')
+                return refresh();
+            setObjects((previous) => {
+                const id = change.type === 'remove' ? change.id : change.object.id;
+                const object = change.type === 'upsert' ? client.objects.read(id) : undefined;
+                const index = previous.findIndex((entry) => entry.id === id);
+                if (!object || (kind && object.kind !== kind)) {
+                    return index < 0 ? previous : previous.filter((entry) => entry.id !== id);
+                }
+                if (index < 0)
+                    return [...previous, object];
+                const next = previous.slice();
+                next[index] = object;
+                return next;
+            });
+        });
     }, [client, kind]);
     return objects;
 }
+/** Entity presence only. Motion is read imperatively without React rerenders. */
+export function useNetworkObjectIds(kind) {
+    const client = useNetcode();
+    const subscribe = useCallback((notify) => client.objects.onStructureChange(notify), [client]);
+    const snapshot = useCallback(() => client.objects.ids(kind), [client, kind]);
+    return useSyncExternalStore(subscribe, snapshot, snapshot);
+}
+export function useNetworkObject(id) {
+    const client = useNetcode();
+    const subscribe = useCallback((notify) => client.objects.onChange((change) => {
+        if (change.type === 'snapshot' || (change.type === 'remove' ? change.id : change.object.id) === id)
+            notify();
+    }), [client, id]);
+    const snapshot = useCallback(() => client.objects.read(id), [client, id]);
+    return useSyncExternalStore(subscribe, snapshot, snapshot);
+}
 export function useNetcodeVoicePeers() {
     const client = useNetcode();
     const [peers, setPeers] = useState(() => client.voice.listPeers());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openrtc-netcode-react",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -40,7 +40,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "openrtc-netcode": "^3.0.1"
+    "openrtc-netcode": "^3.0.2"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0"