chore(general): add manual render loop + improve react rendering

Author: simonedevit

packages/library/src/core/Scene.tsx

@@ -8,6 +8,7 @@ import type { RootContainer, EngineContext } from '@types';
 import Reactylon, { ROOT_IDENTIFIER } from '../reconciler';
 import { useContextBridge } from 'its-fine';
 import type { StoreApi } from 'zustand';
+import { Logger } from '@dvmstudios/reactylon-common';
 
 export type SceneProps = React.PropsWithChildren<{
     /**
@@ -33,7 +34,7 @@ export type SceneProps = React.PropsWithChildren<{
 export let activeScene: BabylonScene | null = null;
 
 export const Scene = ({ children, sceneOptions, onSceneReady, isGui3DManager, xrDefaultExperienceOptions, physicsOptions, _context, ...rest }: SceneProps) => {
-    const { engine, isMultipleCanvas, isMultipleScene, disposeEngine } = _context as EngineContext;
+    const { engine, isMultipleCanvas, isMultipleScene, disposeEngine, markSceneAsReady } = _context as EngineContext;
     const rootContainer = useRef<Nullable<RootContainer>>(null);
     const reconciler = useRef(Reactylon());
     const store = useRef<StoreApi<Store>>(null);
@@ -132,11 +133,22 @@ export const Scene = ({ children, sceneOptions, onSceneReady, isGui3DManager, xr
                         <SceneContext.Provider value={store.current}>{children}</SceneContext.Provider>
                     </Bridge>,
                     rootContainer.current!,
+                    {
+                        onFirstCommit: () => {
+                            if (!scene.activeCamera) {
+                                Logger.warn(
+                                    'Scene - No active camera after first commit. If you use a declarative camera, ensure it becomes scene.activeCamera (or create one procedurally in onSceneReady).',
+                                );
+                            }
+                            markSceneAsReady?.();
+                        },
+                    },
                 );
             }
         })();
 
         return () => {
+            // the callback will be executed only if there are no more scenes
             reconciler.current.unmount(rootContainer.current!, () => {
                 activeScene = null;
                 disposeEngine();
@@ -163,7 +175,7 @@ export const Scene = ({ children, sceneOptions, onSceneReady, isGui3DManager, xr
             </Bridge>,
             rootContainer.current!,
         );
-    });
+    }, [children]);
 
     return null;
 };

packages/library/src/reconciler.ts

@@ -617,24 +617,29 @@ function createReconciler() {
     );
 }
 
+type RenderCallbacks = {
+    onFirstCommit?: () => void;
+};
+
 type ReactylonHandler = {
-    render: (element: any, rootContainer: RootContainer) => void;
+    render: (element: any, rootContainer: RootContainer, callbacks?: RenderCallbacks) => void;
     unmount: (rootContainer: RootContainer, disposeEngine: EngineContext['disposeEngine']) => void;
 };
 
-export const roots = new Map<any, FiberRoot>();
+export const roots = new Map<any, { root: FiberRoot; didFirstCommit: boolean }>();
 
 const Reactylon = (): ReactylonHandler => {
     const reconciler = createReconciler();
     return {
-        render: (element, rootContainer) => {
-            let root = roots.get(rootContainer);
+        render: (element, rootContainer, callbacks) => {
+            let rootEntry = roots.get(rootContainer);
             // first render
-            if (!root) {
+            if (!rootEntry) {
                 // Create a container using the reconciler's createContainer method
                 // @ts-expect-error - @types/react-reconciler doesn't define new types (where for reconciler >= 0.31.0 arguments of createContainer are 10 and not 8)
-                root = reconciler.createContainer(rootContainer, false, null, false, null, '', console.error, console.error, console.error, null);
-                roots.set(rootContainer, root);
+                const root = reconciler.createContainer(rootContainer, false, null, false, null, '', console.error, console.error, console.error, null);
+                rootEntry = { root, didFirstCommit: false };
+                roots.set(rootContainer, rootEntry);
                 reconciler.injectIntoDevTools({
                     //findFiberByHostInstance: reconciler.findHostInstance,
                     bundleType: process.env.NODE_ENV === 'development' ? 1 : 0,
@@ -643,14 +648,20 @@ const Reactylon = (): ReactylonHandler => {
                 });
             }
             // Update the container with the specified component to trigger the rendering process
-            reconciler.updateContainer(element, root, null, null);
+            reconciler.updateContainer(element, rootEntry.root, null, () => {
+                if (!rootEntry.didFirstCommit) {
+                    rootEntry.didFirstCommit = true;
+                    callbacks?.onFirstCommit?.();
+                }
+            });
         },
 
-        unmount(container: FiberRoot, disposeEngine): void {
+        unmount(rootContainer: RootContainer, disposeEngine): void {
             Logger.log(`unmount - container unmounted`);
-            const root = roots.get(container);
-            reconciler.updateContainer(null, root, null, () => {
-                roots.delete(container);
+            const rootEntry = roots.get(rootContainer);
+            if (!rootEntry) return;
+            reconciler.updateContainer(null, rootEntry.root, null, () => {
+                roots.delete(rootContainer);
                 if (roots.size === 0) {
                     // no more scenes so dispose the engine
                     disposeEngine?.();

packages/library/src/types/types.ts

@@ -91,4 +91,5 @@ export type RootContainer = {
 
 export type EngineContext = EngineStore & {
     disposeEngine: () => void;
+    markSceneAsReady?: () => void;
 };

packages/library/src/web/Engine.tsx

@@ -32,9 +32,37 @@ export type EngineProps = React.PropsWithChildren<{
      * This prop is only for testing purpose and should not be passed to this component.
      */
     _nullEngine?: NullEngine;
+    /**
+     * Overrides Reactylon's default render-loop scheduling.
+     *
+     * By default, Reactylon starts a continuous Babylon.js render loop via `engine.runRenderLoop(...)`
+     * once all scenes are marked as ready.
+     *
+     * When `manualRenderLoop` is provided, Reactylon will **not** call `engine.runRenderLoop`.
+     * Instead, it will invoke this callback exactly once at the moment the render loop would normally start.
+     *
+     * This is primarily intended for **tests** (deterministic stepping) or advanced integrations that
+     * require full control over scheduling.
+     *
+     * @param renderFrame A function that renders a single frame using Reactylon's internal rules
+     * (e.g., multi-scene view selection). Call it manually to step rendering deterministically.
+     * @param engine The Babylon.js engine instance. Optional; provided for advanced use-cases
+     * (e.g., starting/stopping a continuous loop manually).
+     *
+     */
+    manualRenderLoop?: (renderFrame: () => void, engine: WebGLEngine | WebGPUEngine) => void;
 }>;
 
-export const Engine = ({ engineOptions, loadingScreenOptions, canvasId = 'reactylon-canvas', _nullEngine, isMultipleCanvas, forceWebGL, ...rest }: EngineProps) => {
+export const Engine = ({
+    engineOptions,
+    loadingScreenOptions,
+    canvasId = 'reactylon-canvas',
+    _nullEngine,
+    isMultipleCanvas,
+    forceWebGL,
+    manualRenderLoop,
+    ...rest
+}: EngineProps) => {
     const [context, setContext] = useState<EngineContext | null>(null);
     const engineRef = useRef<{
         engine: WebGLEngine | WebGPUEngine;
@@ -44,6 +72,10 @@ export const Engine = ({ engineOptions, loadingScreenOptions, canvasId = 'reacty
     const canvasRef = useRef<HTMLCanvasElement>(null);
 
     const children = Children.toArray(rest.children) as Array<React.ReactElement>;
+    const initialScenesRef = useRef(children.length);
+    const readyScenesRef = useRef(0);
+    const isRenderLoopStarted = useRef(false);
+
     const isMultipleScene = children.length > 1;
 
     useEffect(() => {
@@ -75,20 +107,36 @@ export const Engine = ({ engineOptions, loadingScreenOptions, canvasId = 'reacty
                 const { component, animationStyle } = loadingScreenOptions;
                 engine.loadingScreen = new CustomLoadingScreen(canvas as HTMLCanvasElement, component, animationStyle) as unknown as ILoadingScreen;
             }
-            engine.runRenderLoop(() => {
+            const renderFrame = () => {
                 const camera = engine!.activeView?.camera;
                 engine!.scenes.forEach(scene => {
-                    if (!scene.activeCamera) {
-                        // meantime you are setting a camera
-                        Logger.warn('Engine - runRenderLoop - Waiting for active camera...');
-                    }
-                    if (scene.cameras?.length > 0) {
+                    if (scene.activeCamera) {
                         if (!isMultipleScene || scene.activeCamera === camera) {
                             scene.render();
                         }
                     }
                 });
-            });
+            };
+
+            const startRenderLoop = () => {
+                if (isRenderLoopStarted.current) return;
+                isRenderLoopStarted.current = true;
+
+                if (manualRenderLoop) {
+                    manualRenderLoop(renderFrame, engine);
+                    return;
+                }
+                engine.runRenderLoop(renderFrame);
+            };
+
+            const markSceneAsReady = () => {
+                readyScenesRef.current += 1;
+                // start render loop only when all scenes are marked as ready
+                if (readyScenesRef.current >= initialScenesRef.current) {
+                    startRenderLoop();
+                }
+            };
+
             engineRef.current = {
                 engine,
                 onResizeWindow: () => engine.resize(),
@@ -99,6 +147,7 @@ export const Engine = ({ engineOptions, loadingScreenOptions, canvasId = 'reacty
                 engine,
                 isMultipleCanvas: !!isMultipleCanvas,
                 isMultipleScene,
+                markSceneAsReady,
                 disposeEngine: () => {
                     window.removeEventListener('resize', engineRef.current!.onResizeWindow);
                     engineRef.current!.engine.dispose();