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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
"""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};
'''