Web integration

Hiber3D is designed to run seamlessly in web environments across both desktop and mobile platforms. It includes a number of features that make it easy to integrate with modern web technologies. The game engine is rendered inside a <canvas> element and controlled via a TypeScript-friendly API.

This section covers the main aspects of Hiber3D’s web integration, including project setup, API usage, and event handling.

Generating the WebAssembly module

During the compile process, three modules are generated for your project:

• @hiber3d/web: Provides the TypeScript and React interface for interacting with the generated WebAssembly modules.
• [ProjectName]_webgl: WebGL-specific runtime module.
• [ProjectName]_webgpu: WebGPU-specific runtime module.

Graphic Mode

Hiber3D supports two rendering backends: WebGL and WebGPU. The engine automatically detects the browser’s capabilities and selects the appropriate mode. If both are available, WebGPU is preferred for performance reasons.

Interop Events

Events are the primary mechanism for communication between game modules and systems. They’re also used for interactions between the web layer and the WebAssembly (WASM) core. Internally, this is powered by a double-buffered event bus for optimal performance and thread safety.

Connecting events to the web layer

Events can be exposed to the web layer using specific macros. These macros must be added to type-reflected structures defined in a .hpp file.

Available macros:

• HIBER3D_INTEROP_SEND_TO_JS
• HIBER3D_INTEROP_RECEIVE_FROM_JS
• HIBER3D_INTEROP_SEND_AND_RECEIVE_FROM_JS

#pragma once
 
#include <Hiber3D/Interop/Defines.hpp>
 
struct ReadableFromJS {
  float value;
};
struct WritableFromJS {
  std::string value;
  std::optional<std::string> name;
};
struct ReadableAndWritableFromJS {
  bool value;
  std::vector<std::string> names;
};
 
HIBER3D_REFLECT(HIBER3D_TYPE(ReadableFromJS), HIBER3D_MEMBER(value));
HIBER3D_REFLECT(HIBER3D_TYPE(WritableFromJS), HIBER3D_MEMBER(value));
HIBER3D_REFLECT(HIBER3D_TYPE(ReadableAndWritableFromJS), HIBER3D_MEMBER(value));
 
HIBER3D_INTEROP_SEND_TO_JS(ReadableFromJS)
HIBER3D_INTEROP_RECEIVE_FROM_JS(WritableFromJS)
HIBER3D_INTEROP_SEND_AND_RECEIVE_FROM_JS(ReadableAndWritableFromJS);

const Component = () => {
  const { api } = useHiber3D();
 
  useEffect(() => {
    // Set up listeners for game events
      const listener = api.onReadableFromJS((payload) => {
        console.log("Game event was sent with payload: ", payload);
      });
    
      const secondListener = api.onReadableAndWriteableFromJS((payload) => {
        console.log("Another game event was sent with payload: ", payload);
      });
 
    // Clean up
    return () => {
      api.removeEventCallback(listener);
      api.removeEventCallback(secondListener);
    };
  }, [api]);
 
  const handleClick = () => {
    // Send events to the game
    api.writeWriteableFromJS({value: "Hello", name: "World"});
    api.writeReadableAndWriteableFromJS({value: true, names: ["Hello", "World"]});
  };
 
  return (
    <div>
      <button onClick={handleClick}>Game Action</button>
    </div>
  );
};

React application

@hiber3d/web

This module is automatically generated during the build process of your project. It provides the TypeScript API and React components required to integrate Hiber3D into your web application.

<Hiber3D />

The root component that mounts the Hiber3D engine. It takes a build prop containing the WebGL and WebGPU modules and renders the game engine within a <canvas>. If the EditorModule is included, the engine enters Editor mode.

Usage

import { moduleFactory as webGPU } from "Example_webgpu";
import { moduleFactory as webGL } from "Example_webgl";
 
export const App = () => (
  <Hiber3D build={{ webGPU, webGL }}>
    <ExampleEvent />
  </Hiber3D>
);
 

useHiber3D

A React hook available to children of <Hiber3D />. It exposes useful references and the API object.

Usage

import { useHiber3D } from "@hiber3d/web";
 
const Component = () => {
  const { api, canvasRef, mainRef } = useHiber3D();
 
  return null;
};
 

Returns

• api - The interface for sending and receiving events.
• canvasRef - Ref to the game’s <canvas> element.
• mainRef - Ref to the <main> element.
• log - Access engine log output.
• addMethodListener / removeMethodListener - Hooks for intercepting TypeScript-side method calls.

Properties

• build - Object containing webGPU and webGL module factories.
• canvas - Optional canvas configuration.
• config.Editor - { Enabled: boolean, Mode: "play" | "edit" }
• webUI - Optional web UI configuration. Accepts enableInEditMode: boolean and children: ReactNode;
• logs - Access to the logs from the engine