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
#!/usr/bin/env python3
"""EHT entry point — run with: python -m eht [options]"""
import argparse
from pathlib import Path
from .parser import CppParser
from .type_system import TypeSystem
from .abi import compute_abi_hash
from .entity_layout import parse_entity_layout, generate_ts as generate_entity_ts
from .constants import parse_constants, canonical as const_canonical, generate_ts as generate_consts_ts
from .generators import (
EmbindGenerator, TypeScriptGenerator, MetadataGenerator,
PtrLayoutGenerator, EditorAPIGenerator, NativeBindingsGenerator, AotComponentsGenerator,
NativeFunctionsGenerator,
)
from .generators.native_functions import Alias
def _write_lf(path, text):
# Bytes, not text mode: text mode writes CRLF on Windows, and every
# generated file then differs from the committed LF one.
path.write_bytes(text.encode('utf-8'))
def _emit_native_functions(args) -> int:
"""Emit the opt-in QuickJS wrappers for the engine's binding entry points —
the same declarations embind registers, so the two cannot drift."""
headers = []
for path in args.native_functions:
if not path.is_file():
print(f"[FAIL] --native-functions: no such header: {path}")
return 1
# The generated TU includes the header the way the binding TUs do: by its
# path under src/. Deriving it (rather than pasting a basename onto a
# fixed directory) is what lets a header move without the generated file
# pointing at where it used to be.
parts = path.resolve().parts
if 'src' not in parts:
print(f"[FAIL] --native-functions: {path} is not under src/, so its include cannot be derived")
return 1
include = '/'.join(parts[len(parts) - 1 - parts[::-1].index('src') + 1:])
headers.append((include, path.read_text(encoding='utf-8')))
try:
aliases = [Alias.parse(spec) for spec in (args.native_functions_alias or [])]
except ValueError as err:
print(f"[FAIL] --native-functions-alias: {err}")
return 1
gen = NativeFunctionsGenerator(headers, shim_header=args.native_shim, aliases=aliases)
if aliases and args.native_functions_alias_output is None:
print("[FAIL] --native-functions-alias needs --native-functions-alias-output "
"(the aliased wrappers are a TU of their own)")
return 1
if args.native_functions_alias_output is not None:
args.native_functions_alias_output.parent.mkdir(parents=True, exist_ok=True)
print(f"Generating: {args.native_functions_alias_output}")
_write_lf(args.native_functions_alias_output, gen.generate_aliases())
if args.native_functions_alias_header is not None:
args.native_functions_alias_header.parent.mkdir(parents=True, exist_ok=True)
print(f"Generating: {args.native_functions_alias_header}")
_write_lf(args.native_functions_alias_header, gen.generate_alias_header())
if args.native_functions_output is not None:
content = gen.generate()
args.native_functions_output.parent.mkdir(parents=True, exist_ok=True)
print(f"Generating: {args.native_functions_output}")
_write_lf(args.native_functions_output, content)
print(f" {len(gen.emitted)} entry point(s) bound")
# The TS half: the same entry points as the object the SDK's plugins call, so
# a plugin reaches whichever core is present without knowing which. Committed
# (the SDK builds from source without running EHT), unlike the C++ wrappers.
if args.native_functions_ts is not None:
args.native_functions_ts.parent.mkdir(parents=True, exist_ok=True)
print(f"Generating: {args.native_functions_ts}")
_write_lf(args.native_functions_ts, gen.generate_ts())
# Never a silent cap: what the wrappers cannot marshal is what still needs a
# hand-written binding, so say it every run.
for skip in gen.skipped:
print(f" skipped {skip.name}: {skip.reason}")
return 0
def _emit_native(components, enums, args) -> None:
"""Emit the opt-in native (QuickJS) bindings from the parsed reflection —
the native sibling of WebBindings.generated.cpp, one reflection source."""
only = None
if args.native_components:
only = {n.strip() for n in args.native_components.split(',') if n.strip()}
args.native_output.parent.mkdir(parents=True, exist_ok=True)
print(f"Generating: {args.native_output}")
native_gen = NativeBindingsGenerator(
components, enums, shim_header=args.native_shim, only=only,
)
_write_lf(args.native_output, native_gen.generate())
def main() -> int:
parser = argparse.ArgumentParser(description='EHT - ESEngine Header Tool')
parser.add_argument('--input', '-i', type=Path, nargs='+',
default=[Path('src/esengine/ecs/components')],
help='Input directories')
parser.add_argument('--output', '-o', type=Path,
default=Path('src/esengine/bindings'),
help='Output directory for C++ bindings')
parser.add_argument('--ts-output', type=Path, default=Path('sdk'),
help='Output directory for TypeScript')
# Addressable like the other two outputs, so a freshness check can generate a
# whole set into a scratch tree and compare — rather than writing over the
# committed files it is trying to judge.
parser.add_argument('--aot-output', type=Path, default=Path('src/esengine/aot'),
help='Output directory for the AOT component resolvers')
parser.add_argument('--entity-header', type=Path,
default=Path('src/esengine/core/Types.hpp'),
help='Header declaring Entity::Layout = PackedId<index, gen>')
parser.add_argument('--const-root', type=Path, nargs='+',
default=[Path('src/esengine')],
help='Roots scanned for ES_CONST and for ES_ENUM outside --input')
parser.add_argument('--verbose', '-v', action='store_true')
# Opt-in native (QuickJS) bindings. Off by default so the standard EHT run and
# its committed *.generated.* files are unchanged; a native build passes this
# to emit NativeBindings.generated.cpp into its build tree from the same source.
parser.add_argument('--native-output', type=Path, default=None,
help='Also emit native QuickJS bindings to this .cpp path')
parser.add_argument('--native-components', type=str, default=None,
help='Comma-separated component names to emit (default: all)')
parser.add_argument('--native-shim', type=str, default='esn_shim.hpp',
help='Shim header the generated native TU includes')
# With --native-output, emit ONLY the native bindings and skip the embind /
# editor / TS generation. A native build just needs NativeBindings.generated.cpp;
# this keeps that invocation single-purpose and from touching the committed
# web/editor/TS *.generated.* files at all (no throwaway output dirs needed).
parser.add_argument('--native-only', action='store_true',
help='With --native-output: emit only the native bindings')
# Opt-in QuickJS wrappers for the engine's binding ENTRY POINTS (renderer_*,
# uiLayout_*, …), parsed from the bindings headers embind registers from.
parser.add_argument('--native-functions', type=Path, nargs='+', default=None,
help='Bindings headers to emit native QuickJS wrappers for')
parser.add_argument('--native-functions-output', type=Path, default=None,
help='Where to write the generated wrappers (.cpp)')
parser.add_argument('--native-functions-ts', type=Path, default=None,
help='Also write the TS-side native engine API (.ts)')
# A second implementation of one C surface in the same binary (PhysX beside
# Jolt): <src>=<dst>:<GATE> wraps every <src>* entry point again as <dst>*,
# behind GATE, and the alias header renames that implementation's symbols.
parser.add_argument('--native-functions-alias', type=str, action='append', default=None,
help='Also wrap <src>* entry points as <dst>* behind GATE: <src>=<dst>:<GATE>')
parser.add_argument('--native-functions-alias-output', type=Path, default=None,
help='Where to write the aliased wrappers and their registration (.cpp)')
parser.add_argument('--native-functions-alias-header', type=Path, default=None,
help='Write the #define rename header for the aliases (.hpp)')
args = parser.parse_args()
print("EHT - ESEngine Header Tool")
# Function wrappers are parsed from declarations, not component reflection —
# emit them before (and independently of) the component pass.
if args.native_functions:
if (args.native_functions_output is None and args.native_functions_ts is None
and args.native_functions_alias_output is None):
print("[FAIL] --native-functions needs --native-functions-output, "
"--native-functions-ts and/or --native-functions-alias-output.")
return 1
code = _emit_native_functions(args)
if code != 0 or args.native_output is None:
return code
cpp_parser = CppParser()
for input_dir in args.input:
print(f"Parsing: {input_dir}")
cpp_parser.parse_directory(input_dir)
# An enum that crosses says so at its declaration; where it is declared is
# not the boundary's business. Scanned rather than listed, as ES_CONST is.
cpp_parser.parse_enums_outside(args.const_root, args.input)
if cpp_parser.warnings:
cpp_parser.print_warnings()
# Abort before codegen on malformed metadata — emitting bindings from a bad
# annotation would bake the mistake into committed *.generated.* files.
if cpp_parser.errors:
cpp_parser.print_errors()
print(f"[FAIL] {len(cpp_parser.errors)} annotation error(s); aborting before codegen.")
return 1
# A type no generator recognises is emitted VERBATIM by each of them, so an
# ES_PROPERTY the boundary cannot marshal used to compile and then fail when a
# scene added the component ("unbound types"), with a TS type of `number` over
# it. Refuse it here, where the field still has a name.
uncarried = TypeSystem(cpp_parser.enums).uncarried_properties(cpp_parser.components)
if uncarried:
for comp, prop, cpp_type in uncarried:
print(f"[FAIL] {comp}.{prop}: ES_PROPERTY type '{cpp_type}' does not cross the"
" boundary. Either drop the annotation (MeshRenderer's geometry payload is"
" the precedent: un-annotated, set through its own binding), or teach"
" tools/eht/type_system.py to carry the type.")
return 1
# Emit components/enums in a stable alphabetical order so the generated files
# are byte-reproducible across machines — Path.rglob order is filesystem-
# dependent, which otherwise churns every committed *.generated.* file when a
# different dev regenerates. (The ABI hash already canonicalizes by sorting.)
cpp_parser.components.sort(key=lambda c: c.name)
cpp_parser.enums.sort(key=lambda e: e.name)
if args.verbose:
print(f" Found {len(cpp_parser.enums)} enums")
print(f" Found {len(cpp_parser.components)} components")
for comp in cpp_parser.components:
print(f" - {comp.name}: {len(comp.properties)} properties")
if not cpp_parser.components:
print("Warning: No components found!")
return 1
# ── Native-only fast path ──
# A native build needs just NativeBindings.generated.cpp, from the same
# reflection — so skip all embind/editor/TS work and touch no committed files.
if args.native_only:
if args.native_output is None:
print("[FAIL] --native-only requires --native-output.")
return 1
_emit_native(cpp_parser.components, cpp_parser.enums, args)
print("[OK] Done (native bindings only)!")
return 0
# ── Boundary ABI: single source of truth ──
# Compute pointer layouts and the ABI hash first; both the C++ bindings and
# the TS metadata embed the same hash so connect() can verify they match.
ptr_gen = PtrLayoutGenerator(cpp_parser.components, cpp_parser.enums)
# The entity split is a boundary fact with the same failure mode as an
# offset — a handle that decodes to another entity — so it is in the hash.
entity = parse_entity_layout(args.entity_header)
print(f"Entity layout: index={entity[0]} gen={entity[1]}")
# Constants that cross say so at their declaration; a wrong one decodes a
# stored cell into a different tile rather than failing.
consts = parse_constants(args.const_root)
print(f"Boundary constants: {len(consts)}")
abi_hash = compute_abi_hash(
cpp_parser.components, cpp_parser.enums, ptr_gen.layouts, entity,
const_canonical(consts)
)
print(f"ABI layout hash: {abi_hash}")
# ── C++ Editor API ──
# Before the first write, not between the two: the editor API landed in a
# directory nobody had created yet whenever the output root was fresh.
args.output.mkdir(parents=True, exist_ok=True)
editor_api_path = args.output / 'EditorAPI.generated.cpp'
print(f"Generating: {editor_api_path}")
editor_gen = EditorAPIGenerator(cpp_parser.components, cpp_parser.enums)
_write_lf(editor_api_path, editor_gen.generate())
# ── C++ Embind Bindings ──
embind_path = args.output / 'WebBindings.generated.cpp'
print(f"Generating: {embind_path}")
embind_gen = EmbindGenerator(
cpp_parser.components, cpp_parser.enums,
layout_asserts=ptr_gen.generate_layout_asserts(),
abi_hash=abi_hash,
)
_write_lf(embind_path, embind_gen.generate())
# ── Component resolvers for compiled systems ──
# Committed like the two above: a host that dispatches a compiled system
# needs the type half of the contract, and it must not be a second table.
aot_dir = args.aot_output
aot_dir.mkdir(parents=True, exist_ok=True)
aot_gen = AotComponentsGenerator(cpp_parser.components, cpp_parser.enums)
for name, text in (('AotComponents.generated.hpp', aot_gen.generate_header()),
('AotComponents.generated.cpp', aot_gen.generate_source())):
print(f"Generating: {aot_dir / name}")
_write_lf(aot_dir / name, text)
# ── Native QuickJS Bindings (opt-in) ──
if args.native_output is not None:
_emit_native(cpp_parser.components, cpp_parser.enums, args)
# Resolve the TS source directory robustly. Callers historically pass either
# the package root (`sdk`) or the source dir (`sdk/src`); detect which by
# looking for the `ecs/` subfolder. Previously a `sdk/src` argument made every
# `/ 'src' /` path resolve to a non-existent `sdk/src/src`, silently skipping
# component.generated.ts / ptrLayouts / ptrAccessors. Generation must never
# silently no-op a file.
ts_root = args.ts_output
if (ts_root / 'ecs').is_dir():
ts_src_dir = ts_root
else:
ts_src_dir = ts_root / 'src'
ts_src_dir.mkdir(parents=True, exist_ok=True)
def write_ts(rel: str, content: str) -> None:
out = ts_src_dir / rel
out.parent.mkdir(parents=True, exist_ok=True)
print(f"Generating: {out}")
_write_lf(out, content)
# ── TypeScript Definitions ──
ts_gen = TypeScriptGenerator(cpp_parser.components, cpp_parser.enums)
ts_content = ts_gen.generate()
write_ts('wasm/wasm.generated.ts', ts_content)
write_ts('ecs/bridge/registryOps.generated.ts', ts_gen.generate_registry_ops())
# ── Component Metadata ──
meta_gen = MetadataGenerator(cpp_parser.components, cpp_parser.enums, abi_hash=abi_hash)
write_ts('ecs/component.generated.ts', meta_gen.generate())
# ── Entity split ──
write_ts('wasm/entityLayout.generated.ts', generate_entity_ts(*entity))
# ── Boundary constants ──
write_ts('wasm/constants.generated.ts', generate_consts_ts(consts))
# ── Pointer Layouts & Accessors ──
write_ts('wasm/ptrLayouts.generated.ts', ptr_gen.generate())
write_ts('ecs/bridge/ptrAccessors.generated.ts', ptr_gen.generate_accessors())
print("[OK] Done!")
return 0
if __name__ == '__main__':
raise SystemExit(main())