Getting Started

Welcome to the Nexus Engine SDK. The Nexus Engine is a powerful, data-driven framework for building highly scalable, modular spatial web applications and 3D experiences using React Three Fiber.

Installation

Install the core engine via npm:

npm install @neural-workspace/nexus-engine-core

Ensure you have the required peer dependencies installed:

npm install react react-dom three @react-three/fiber @react-three/drei

Basic Usage

The Nexus Engine is entirely data-driven. You interact with it by providing a unified config prop containing nodes (static 3D objects) and systems (dynamic logic, plugins, and game loops).

Here is a simple example of spawning a scene with a floor, a red box, and loading the player-system dynamically from the Neural Workspace.

import React, { useState } from 'react';
import { NexusEngine } from '@neural-workspace/nexus-engine-core';

function App() {
  const [engineConfig] = useState({
    // Nodes define the static 3D layout of your scene
    nodes: [
      {
        id: 'ambient-light',
        type: 'light',
        subType: 'ambient',
        properties: { intensity: 1, color: '#ffffff' }
      },
      {
        id: 'floor',
        type: 'mesh',
        subType: 'plane',
        position: [0, -0.5, 0],
        scale: [20, 20, 1], // X, Y scale for planes
        rotation: [-Math.PI / 2, 0, 0],
        properties: { color: '#333333' }
      },
      {
        id: 'my-box',
        type: 'mesh',
        subType: 'box',
        position: [2, 0.5, 2],
        scale: [2, 2, 2],
        properties: { color: '#ef4444' }
      }
    ],
    // Systems are powerful plugins that provide logic (e.g. physics, players, AI)
    systems: [
      {
        type: 'ground-system',
        is3D: true,
        config: {
          size: 20,
          cellSize: 0.5,
          debug: false
        }
      },
      {
        type: 'player-system',
        is3D: true,
        config: {
          modelUrl: '/models/my-character.glb',
          walkAnimationUrl: '/models/animations/walk.glb',
          idleAnimationUrl: '/models/animations/idle.glb',
          fallAnimationUrl: '/models/animations/fall.glb',
          position: [0, 3, 0],
          speed: 4
        }
      }
    ]
  });

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <NexusEngine 
        apiKey="YOUR_NEURAL_WORKSPACE_API_KEY" // Used to download marketplace plugins
        apiEndpoint="https://api.neural-workspace.com" // Backend endpoint
        config={engineConfig} 
      />
    </div>
  );
}

export default App;

System Loading and API Keys

The core engine is incredibly lightweight because it does not bundle complex systems. Instead, it dynamically fetches them over the network at runtime.

When the <NexusEngine /> mounts, it checks the config.systems array:

1. Local Registry Check: It first checks if the system has been manually registered locally using SystemRegistry.register(sysId, Component).
2. Dynamic Delivery: If the system is not found locally, the engine automatically contacts the apiEndpoint with your apiKey. It verifies your license and streams the compiled system bundle directly into your user's browser, seamlessly executing it.

If an API key is missing or invalid, or if you lack the license for a requested plugin, a fatal engine error will be displayed to the user.

Writing Custom Systems

You can easily bypass the marketplace and inject your own proprietary systems locally. A system is simply a React component that takes advantage of @react-three/fiber hooks like useFrame.

import { useRef } from 'react';
import { useFrame } from '@react-three/fiber';
import { SystemRegistry, NexusEngine } from '@neural-workspace/nexus-engine-core';

// 1. Define your custom system
function CustomSpinSystem({ speed = 1 }) {
  const meshRef = useRef<any>();

  useFrame((state, delta) => {
    if (meshRef.current) {
      meshRef.current.rotation.y += speed * delta;
    }
  });

  return (
    <mesh ref={meshRef} position={[0, 2, 0]}>
      <sphereGeometry args={[1, 32, 32]} />
      <meshStandardMaterial color="#3b82f6" />
    </mesh>
  );
}

// 2. Register it with the Engine BEFORE the NexusEngine mounts
SystemRegistry.register('custom-spin', CustomSpinSystem);

// 3. Use it in your config!
function App() {
  return (
    <NexusEngine 
      config={{
        nodes: [],
        systems: [
          {
            type: 'custom-spin', // Matches the registered ID
            is3D: true,
            config: { speed: 2.5 }
          }
        ]
      }} 
    />
  );
}

Architecture Notes

• Data-Driven: Because the state of the engine is entirely controlled by the config prop, it perfectly pairs with external CMS systems, visual editors, or backend databases.
• React Ecosystem: Nodes and systems execute within a <Canvas /> context provided by @react-three/fiber. You have full access to ThreeJS primitives and R3F hooks.
• Events: Use the engineEventBus exported by @neural-workspace/nexus-engine-core to send cross-system messages without prop drilling.

Enjoy building the next generation of spatial web apps with the Nexus Engine!