Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

5.7 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
//
// Backend-neutral fast-path component memory.
//
// The generated ptrAccessors (ptrAccessors.generated.ts) read and write a
// component's fields against three typed-array views + a base byte offset. Where
// those views come from is the one thing that differs between backends, so it is
// the only thing abstracted here — the accessor logic itself is shared verbatim:
//
//   * web  (WasmMemoryProvider):   the whole wasm HEAP as F32/U32/U8 views, and a
//     per-entity byte offset from the wasm-exported ptr function.
//   * native (NativeMemoryProvider): a zero-copy ArrayBuffer over one native ECS
//     component (the host's generated `es_<Component>_buffer(entity)` binding),
//     viewed as F32/U32/U8, with offset 0.
//
// The native host exposes a buffer only when its compiler proves all accessed
// offsets agree with wasm32 and the component is trivially copyable. Otherwise
// resolution returns null and BuiltinBridge uses generated member bindings.

import type { Entity } from '../../types';
import type { CppRegistry, ESEngineModule } from '../../wasm';
import { PTR_LAYOUTS } from '../../wasm/ptrLayouts.generated';

/**
 * Heap views + base byte offset for one component instance. The resolver reuses a
 * single instance across calls (it only ever writes the four fields), so callers
 * must consume it immediately and never retain it.
 */
export interface ComponentHeap {
    f32: Float32Array;
    u32: Uint32Array;
    u8: Uint8Array;
    ptr: number;
}

/** Fills `out` with the heap views + base ptr for `entity`'s component; returns
 *  false when the entity has no live component (skip the read/write). */
export type ComponentHeapResolver = (entity: Entity, out: ComponentHeap) => boolean;

/**
 * Where the fast path gets a component's memory. One implementation per engine
 * backend; the BuiltinBridge holds one and both `resolvePtrSetter` and
 * `resolvePtrGetter` go through it.
 */
export interface MemoryProvider {
    /**
     * Resolve a per-entity heap-view filler for `cppName`, or null if this backend
     * has no fast-path binding for the component (the bridge then falls back to the
     * method-based path).
     */
    resolveComponentHeap(cppName: string): ComponentHeapResolver | null;
}

/**
 * Resolve the wasm-exported pointer function for `cppName` — `(entity) => byte
 * offset of that entity's component in the wasm heap`, or null if the module lacks
 * the export or the component has no layout. Shared by WasmMemoryProvider and the
 * bridge's (web-only) resolvePtrFn.
 */
export function resolveWasmPtrFn(
    module: ESEngineModule | null,
    cppRegistry: CppRegistry | null,
    cppName: string,
): ((entity: Entity) => number) | null {
    const layout = PTR_LAYOUTS[cppName];
    if (!layout || !module || !cppRegistry) return null;
    const mod = module as unknown as Record<string, unknown>;
    const fn = mod[layout.ptrFn] as ((r: CppRegistry, e: number) => number) | undefined;
    if (!fn) return null;
    return (e: Entity) => fn(cppRegistry, e);
}

/**
 * Web/emscripten backend: the whole wasm HEAP, indexed by a per-entity byte
 * offset. Behaviourally identical to the pre-abstraction inline path — same
 * ptr function, same `mod.HEAP*` views, same "skip when ptr is 0".
 */
export class WasmMemoryProvider implements MemoryProvider {
    constructor(
        private readonly module: ESEngineModule,
        private readonly cppRegistry: CppRegistry,
    ) {}

    resolveComponentHeap(cppName: string): ComponentHeapResolver | null {
        const getPtrFn = resolveWasmPtrFn(this.module, this.cppRegistry, cppName);
        if (!getPtrFn) return null;
        const mod = this.module;
        return (entity: Entity, out: ComponentHeap): boolean => {
            const ptr = getPtrFn(entity);
            if (!ptr) return false;
            // HEAP* views are re-read each call: emscripten swaps them out on heap
            // growth, so a cached reference can go stale.
            out.f32 = mod.HEAPF32;
            out.u32 = mod.HEAPU32;
            out.u8 = mod.HEAPU8;
            out.ptr = ptr;
            return true;
        };
    }
}

/** A host-injected zero-copy accessor: `entity -> ArrayBuffer` over the native
 *  ECS component, or a nullish value when the entity has no live component. */
export type NativeComponentBufferFn = (entity: number) => ArrayBuffer | null | undefined;

/**
 * Native (embedded-Dawn) backend: each component is reached through the host's
 * generated `es_<Component>_buffer(entity)` binding, which hands back a zero-copy
 * ArrayBuffer over that entity's native component. The accessors then write it at
 * offset 0. `scope` is where those globals live (the QuickJS global object on a
 * device; a plain object in tests).
 *
 * The buffer is re-fetched on every access on purpose: a SparseSet growth moves
 * the dense array, invalidating any previously handed-out ArrayBuffer.
 */
export class NativeMemoryProvider implements MemoryProvider {
    constructor(
        private readonly scope: Record<string, unknown> =
            globalThis as unknown as Record<string, unknown>,
    ) {}

    resolveComponentHeap(cppName: string): ComponentHeapResolver | null {
        const bufFn = this.scope[`es_${cppName}_buffer`] as NativeComponentBufferFn | undefined;
        if (typeof bufFn !== 'function') return null;
        return (entity: Entity, out: ComponentHeap): boolean => {
            const buf = bufFn(entity);
            if (!buf) return false;
            const words = Math.floor(buf.byteLength / 4);
            out.f32 = new Float32Array(buf, 0, words);
            out.u32 = new Uint32Array(buf, 0, words);
            out.u8 = new Uint8Array(buf);
            out.ptr = 0;
            return true;
        };
    }
}