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.

16.4 KB
Raw Blame
#!/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())