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.

9.0 KB
Raw Blame
"""Type classification and C++/TypeScript mapping."""

import re
from typing import Dict, List, Optional, Set, Tuple
from .data import Enum


class TypeSystem:
    """Manages type mappings and conversions between C++ and TypeScript."""

    PRIMITIVE_TYPES = {
        'bool', 'i8', 'i16', 'i32', 'i64', 'u8', 'u16', 'u32', 'u64',
        'f32', 'f64', 'float', 'double', 'int', 'unsigned'
    }

    GLM_TYPES = {'glm::vec2', 'glm::vec3', 'glm::vec4', 'glm::quat', 'glm::uvec2'}

    # Small POD structs usable as builtin component fields: serialized via embind,
    # sized for the pointer cursor, mirrored to a TS interface + editor controls.
    # Generalizes the former single Padding special case. Each entry maps a struct
    # name to its ordered (member_name, member_cpp_type) list; the struct must be
    # defined in the esengine:: namespace and included by WebBindings
    # (ui/UITypes.hpp) and be a standard C++ POD.
    #
    # Structs used as a DIRECT component field (Padding/Dimension) must have only
    # primitive members in PtrLayoutGenerator.TYPE_SIZES (they go through the
    # pointer cursor). Structs used ONLY as a `std::vector<Struct>` element are
    # exempt — vectors are never pointer-accessed — so they may carry std::string
    # members.
    CUSTOM_STRUCTS = {
        'Padding': [('left', 'f32'), ('top', 'f32'), ('right', 'f32'), ('bottom', 'f32')],
        'Dimension': [('value', 'f32'), ('unit', 'u8')],
    }

    SKIP_TYPES = {'glm::mat4', 'std::function'}

    # `std::vector<T>` fields the boundary marshals: element C++ type, the embind
    # vector registered for it, and the TS interface that names it. Adding one is
    # an entry here — every generator below reads the registry.
    # Entity lists the native registry wires by hand, so the generators leave them out: a skin's joints go through
    # their own binding, and Children is kept in step with Parent by the hierarchy system. Every other entity list
    # crosses as a generated pair, or the native core silently has none of it.
    HAND_WIRED_ENTITY_LISTS = {'Children', 'MeshSkin'}

    VECTOR_TYPES = {
        'std::vector<Entity>': ('u32', 'VectorEntity', 'VectorEntity'),
        'std::vector<f32>': ('f32', 'VectorFloat', 'VectorFloat'),
    }

    CPP_TO_TS = {
        'bool': 'boolean',
        'i8': 'number', 'i16': 'number', 'i32': 'number', 'i64': 'number',
        'u8': 'number', 'u16': 'number', 'u32': 'number', 'u64': 'number',
        'f32': 'number', 'f64': 'number', 'float': 'number', 'double': 'number',
        'int': 'number', 'unsigned': 'number',
        'std::string': 'string', 'Entity': 'number',
        'glm::vec2': 'Vec2', 'glm::vec3': 'Vec3', 'glm::vec4': 'Vec4',
        'glm::quat': 'Quat', 'glm::uvec2': 'UVec2',
    }

    def __init__(self, enums: List[Enum]):
        self.enums = enums
        self.enum_names: Set[str] = set()
        for e in enums:
            self.enum_names.add(e.name)
            if e.namespace:
                self.enum_names.add(f'{e.namespace}::{e.name}')

    def clean_type(self, cpp_type: str) -> str:
        return cpp_type.replace('const', '').replace('&', '').strip()

    def is_enum(self, cpp_type: str) -> bool:
        return self.clean_type(cpp_type) in self.enum_names

    def get_enum_values(self, cpp_type: str) -> List[str]:
        t = self.clean_type(cpp_type)
        for e in self.enums:
            if e.name == t or f'{e.namespace}::{e.name}' == t:
                return e.values
        return []

    def is_handle(self, cpp_type: str) -> bool:
        t = self.clean_type(cpp_type)
        return 'Handle' in t or t.startswith('resource::')

    def is_entity(self, cpp_type: str) -> bool:
        return self.clean_type(cpp_type) == 'Entity'

    def is_vector(self, cpp_type: str) -> bool:
        return self.clean_type(cpp_type) in self.VECTOR_TYPES

    def vector_elem(self, cpp_type: str) -> Optional[str]:
        """For `std::vector<X>`, return the element type X (stripped); else None."""
        m = re.fullmatch(r'std::vector<(.+)>', self.clean_type(cpp_type))
        return m.group(1).strip() if m else None

    def is_struct_vector(self, cpp_type: str) -> bool:
        """`std::vector<S>` where S is an element the boundary converts one at a
        time — a registered CUSTOM_STRUCT, or a glm vector, both of which embind
        knows as value_objects. Carried as a JS array; never pointer-accessed.
        """
        elem = self.vector_elem(cpp_type)
        return elem is not None and (elem in self.CUSTOM_STRUCTS or elem in self.GLM_TYPES)

    def vector_elem_cpp(self, cpp_type: str) -> str:
        """The element type as generated C++ must SPELL it: a custom struct lives in
        esengine::, a glm one names its own namespace."""
        elem = self.vector_elem(cpp_type)
        return elem if elem in self.GLM_TYPES else f'esengine::{elem}'

    def vector_elem_ts(self, cpp_type: str) -> str:
        """The element's TypeScript name — `Vec2`, not `glm::vec2`."""
        elem = self.vector_elem(cpp_type)
        return self.CPP_TO_TS.get(elem, elem)

    def is_any_vector(self, cpp_type: str) -> bool:
        return self.is_vector(cpp_type) or self.is_struct_vector(cpp_type)

    def is_skip(self, cpp_type: str) -> bool:
        t = self.clean_type(cpp_type)
        return t in self.SKIP_TYPES

    def is_primitive(self, cpp_type: str) -> bool:
        return self.clean_type(cpp_type) in self.PRIMITIVE_TYPES

    def is_glm(self, cpp_type: str) -> bool:
        return self.clean_type(cpp_type) in self.GLM_TYPES

    def is_custom_struct(self, cpp_type: str) -> bool:
        return self.clean_type(cpp_type) in self.CUSTOM_STRUCTS

    def carries(self, cpp_type: str) -> bool:
        """Whether the boundary can marshal an ES_PROPERTY of this type.

        Every generator below asks a question of the form "is it one of these?"
        and falls through to emitting the field verbatim, so a type none of them
        knows reaches embind as `.field(&C::x)` on something embind was never
        told about. That compiles; it fails when a scene ADDS the component.
        """
        t = self.clean_type(cpp_type)
        return (self.is_skip(t) or self.is_primitive(t) or self.is_glm(t)
                or t == 'std::string' or self.is_enum(t) or self.is_handle(t)
                or self.is_entity(t) or t in self.VECTOR_TYPES
                or self.is_struct_vector(t) or self.is_custom_struct(t))

    def uncarried_properties(self, components) -> List[Tuple[str, str, str]]:
        """Every (component, field, type) the boundary would silently mangle."""
        return [(c.name, p.name, self.clean_type(p.cpp_type))
                for c in components for p in c.properties if not self.carries(p.cpp_type)]

    def custom_struct_members(self, cpp_type: str):
        """Return the [(member_name, member_cpp_type), ...] list for a custom struct."""
        return self.CUSTOM_STRUCTS[self.clean_type(cpp_type)]

    def member_ts_type(self, member_cpp_type: str) -> str:
        """TS type for a custom-struct member (always a primitive)."""
        return self.CPP_TO_TS.get(member_cpp_type, 'number')

    def needs_wrapper(self, cpp_type: str) -> bool:
        return self.is_enum(cpp_type) or self.is_handle(cpp_type)

    def is_entity_vector(self, cpp_type: str) -> bool:
        t = self.clean_type(cpp_type)
        return t in self.VECTOR_TYPES and 'Entity' in t

    def needs_wrapper(self, comp) -> bool:
        """Check if a component needs a JS wrapper struct (has enum/handle/entity/
        struct-vector fields that must be converted at the boundary)."""
        for prop in comp.properties:
            if self.is_enum(prop.cpp_type) or self.is_handle(prop.cpp_type) \
               or self.is_entity(prop.cpp_type) or self.is_entity_vector(prop.cpp_type) \
               or self.is_struct_vector(prop.cpp_type):
                return True
        return False

    def get_js_type(self, cpp_type: str) -> str:
        """Get the C++ type to use in JS wrapper structs."""
        t = self.clean_type(cpp_type)
        if self.is_handle(t) or self.is_entity(t):
            return 'u32'
        if self.is_enum(t):
            return 'i32'
        if t in self.VECTOR_TYPES:
            elem_type = self.VECTOR_TYPES[t][0]
            return f'std::vector<{elem_type}>'
        if self.is_struct_vector(t):
            # embind can't auto-convert a JS array to a registered std::vector, so
            # the wrapper field is an emscripten::val (a JS array) and from/toJS
            # convert element-by-element via the element's value_object.
            return 'emscripten::val'
        return t

    def to_typescript(self, cpp_type: str) -> str:
        t = self.clean_type(cpp_type)
        if t in self.CPP_TO_TS:
            return self.CPP_TO_TS[t]
        if self.is_enum(t):
            return 'number'
        if self.is_handle(t):
            return 'number'
        if t in self.VECTOR_TYPES:
            return self.VECTOR_TYPES[t][2]
        if self.is_struct_vector(t):
            return f'{self.vector_elem_ts(t)}[]'
        if t in self.CUSTOM_STRUCTS:
            return t  # the struct name is its own TS interface name
        return 'unknown'