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.

3.1 KB
Raw Blame
"""The packed Entity split, read from the C++ header that owns it.

An entity handle crosses the boundary as a bare u32. The SDK unpacks it with a
shift and a mask, so a split it disagrees with is not an error — it is a handle
that decodes to ANOTHER ENTITY'S index, and the frame is merely wrong. That has
happened: `installNativeAot` assembled a 20-bit mask by hand against a 22-bit
truth, and every world over 2^20 entities read one component off another entity's
row.

The split therefore gets what every other boundary fact has: one author (the C++
`Entity::Layout`), a generated TS projection, and a term in the ABI layout hash
so a WASM binary and an SDK bundle built from different splits refuse each other
at `connect()` rather than decoding each other's handles.

Not found is a FAILURE, never a default. A fallback here would emit a plausible
split from a header it could not read, which is the one outcome worse than
stopping.
"""

import re
from pathlib import Path
from typing import Tuple

#: `using Layout = PackedId<22, 10>;` — index bits, then generation bits.
_LAYOUT = re.compile(r'using\s+Layout\s*=\s*PackedId\s*<\s*(\d+)\s*,\s*(\d+)\s*>\s*;')


def parse_entity_layout(header: Path) -> Tuple[int, int]:
    """Return `(index_bits, gen_bits)` from the Entity declaration in `header`."""
    if not header.is_file():
        raise SystemExit(f"[FAIL] entity layout: no such header: {header}")
    text = header.read_text(encoding='utf-8')
    found = _LAYOUT.findall(text)
    if not found:
        raise SystemExit(
            f"[FAIL] entity layout: no `using Layout = PackedId<i, g>;` in {header}. "
            "The split is a boundary fact and cannot be guessed.")
    if len(found) > 1:
        raise SystemExit(
            f"[FAIL] entity layout: {len(found)} PackedId layouts in {header}; "
            "which one is Entity's cannot be decided here.")
    index_bits, gen_bits = int(found[0][0]), int(found[0][1])
    if index_bits + gen_bits != 32:
        raise SystemExit(
            f"[FAIL] entity layout: PackedId<{index_bits}, {gen_bits}> is not 32 bits. "
            "The handle is a u32 on both sides.")
    return index_bits, gen_bits


def generate_ts(index_bits: int, gen_bits: int) -> str:
    """The TS half. No imports: `types.ts` is what everything else reaches."""
    return f'''// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    entityLayout.generated.ts
 * @brief   The packed Entity split, from `Entity::Layout` in core/Types.hpp
 * @details Generated by EHT - DO NOT EDIT
 *
 * A handle crosses as a bare u32, so a split this disagrees with decodes to
 * another entity rather than failing. It is in the ABI layout hash for that
 * reason: a WASM binary and an SDK bundle built from different splits refuse
 * each other at `connect()`.
 *
 * No imports on purpose — `types.ts` re-exports these, and everything else
 * reaches them there.
 */

/** Low bits of a handle: the registry slot. */
export const ENTITY_INDEX_BITS = {index_bits};

/** High bits: bumped when a slot is recycled, so a stale handle compares unequal. */
export const ENTITY_GEN_BITS = {gen_bits};
'''