@axion-engine/core 🚀

Experimental: A web-native 3D engine currently focused on running React Three Fiber entirely inside a Web Worker.

Axion Engine is a specialized, experimental alternative to @react-three/offscreen. It is designed for developers who need to move their entire rendering loop, React hooks, and scene logic off the main thread to ensure the UI remains responsive even during heavy 3D computations.

✨ Current State

• Multi-threaded R3F: Execute your React Three Fiber components, state, and Three.js objects inside a dedicated Web Worker.
• Vite Native: Optimized for modern Vite projects; handles worker bundling automatically via standard URL patterns.
• Offscreen Handshake: Simplified canvas transfer logic between the Main thread UI and the Worker thread engine.
• Performance-First: Decouples the rendering loop from the browser's main thread to prevent frame drops in complex apps.

📦 Installation

npm install @axion-engine/core three @react-three/fiber react react-dom

🚀 Usage

Axion consists of a Bridge (Main Thread) and an Engine (Worker Thread). Below is the standard setup for a Vite-based project.

1. Main Thread Setup (App.tsx) Initialize your worker and wrap your application in the AxionEngine provider.

TypeScript

import { useMemo } from 'react';
import { AxionCanvas, AxionEngine } from "@axion-engine/core";

function App() {
// Vite automatically bundles the worker using this syntax
const engineWorker = useMemo(() => {
return new Worker(
new URL('@axion-engine/core/worker', import.meta.url),
{ type: 'classic' } // Axion worker is bundled as an IIFE
);
}, []);

    return (
        <div className="app-container">
            {/* 1. The Engine Provider manages the worker instance */}
            <AxionEngine worker={engineWorker}>

                <div className="engine-viewport">
                    {/* 2. The Canvas Component handles the Offscreen Handshake */}
                    <AxionCanvas shadows>
                        {/* Your scene content is managed within the worker */}
                    </AxionCanvas>
                </div>

            </AxionEngine>
        </div>
    );
}

export default App;

🛠 Local Development & Testing

You can test the engine locally using the built-in test environment.

Install dependencies:

npm install

Run the test suite:

npm run test

Open the test page: Navigate to http://localhost:3000/test/ to see the worker-side React scene rendering in action.

🏗 Why Axion?

Axion Engine is currently an experiment in creating a more "monolithic" and self-contained worker architecture for 3D web applications. While @react-three/offscreen provides a versatile bridge, Axion is being built as a dedicated foundation for large-scale simulations (such as Orion Realms) where worker-thread stability and high-performance threading are the primary requirements.

📄 License

MIT © Vikas