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
"""Component metadata generator (component.generated.ts)."""
import json
from typing import Dict, List, Optional, Tuple
from ..data import Component, Enum, Property
from ..type_system import TypeSystem
from ..field_utils import (
is_color_field, build_enum_value_map, convert_default_ts, format_number,
)
def _is_number(s: str) -> bool:
try:
float(s.rstrip('fF'))
return True
except (TypeError, ValueError):
return False
def _is_skeletal_asset(asset_type: str) -> bool:
"""Half of a skeleton/atlas pair, which travels as one descriptor instead."""
return asset_type.endswith('_skeleton') or asset_type.endswith('_atlas')
class MetadataGenerator:
"""Generates component.generated.ts with defaults and metadata."""
def __init__(self, components: List[Component], enums: List[Enum],
abi_hash: str = ''):
self.components = components
self.enums = enums
self.types = TypeSystem(enums)
self._enum_values = build_enum_value_map(enums)
self.abi_hash = abi_hash
def _get_asset_fields(self, comp: Component) -> List[Dict[str, str]]:
fields = []
for prop in comp.properties:
asset_type = prop.annotations.get('asset')
if asset_type and not _is_skeletal_asset(asset_type):
fields.append({'field': prop.name, 'type': asset_type})
return fields
def _get_skeletal_descriptor(self, comp: Component) -> Optional[Dict[str, str]]:
"""The skeleton/atlas pair a skeletal component carries, and whose runtime.
A pair rather than two independent asset fields because neither half means
anything alone: loading a skeleton without its atlas gets you an armature
with no images. `runtime` is the prefix, so a consumer can tell a Spine
pair from a DragonBones one without a second descriptor kind.
"""
skel_field = atlas_field = runtime = None
for prop in comp.properties:
asset_type = prop.annotations.get('asset') or ''
if asset_type.endswith('_skeleton'):
skel_field = prop.name
runtime = asset_type[:-len('_skeleton')]
elif asset_type.endswith('_atlas'):
atlas_field = prop.name
if skel_field and atlas_field and runtime:
return {'skeletonField': skel_field, 'atlasField': atlas_field, 'runtime': runtime}
return None
def _is_number_list(self, prop) -> bool:
"""A list of numbers the boundary marshals as a registered embind vector.
Apart from `entityFields` because that list also re-aims entity references
when a prefab is instantiated; these are values, and a reference is not.
"""
t = self.types.clean_type(prop.cpp_type)
return t in self.types.VECTOR_TYPES and 'entity_ref' not in prop.annotations
def _is_entity_list(self, comp: Component, prop) -> bool:
"""A list of entities crossing as a generated pair, as other lists do on the native core."""
t = self.types.clean_type(prop.cpp_type)
return (t in self.types.VECTOR_TYPES and 'entity_ref' in prop.annotations
and comp.name not in self.types.HAND_WIRED_ENTITY_LISTS)
def _get_entity_fields(self, comp: Component) -> List[str]:
return [p.name for p in comp.properties if 'entity_ref' in p.annotations]
def _get_color_fields(self, comp: Component) -> List[str]:
return [p.name for p in comp.properties if is_color_field(p, self.types)]
def _get_field_meta(self, comp: Component) -> List[Tuple[str, List[Tuple[str, str]]]]:
"""Build per-field editor-presentation metadata (the FieldMeta shape) from
ES_PROPERTY annotations. An enum-TYPED field also gets its `enum` dropdown
options generated straight from the C++ enum values (single source — no TS
`enumOptions(...)` mirror); a field annotated `flags` is a bitmask, so its
curated bit list stays in TS and the dropdown is suppressed. `gradient`/`curve`
carry TS-only state and stay TS-side. Returns [(field, [(metaKey, jsLiteral), ...])].
"""
out: List[Tuple[str, List[Tuple[str, str]]]] = []
for prop in comp.properties:
a = prop.annotations
entries: List[Tuple[str, str]] = []
# The dropdown enum is the field's own enum type, or — for an int field
# kept as i32 — the `enum=SomeEnum` annotation. A `flags` field is a
# bitmask (curated bit list lives in TS), so no single-choice dropdown.
enum_name = (self.types.clean_type(prop.cpp_type)
if self.types.is_enum(prop.cpp_type) else a.get('enum'))
if enum_name and 'flags' not in a:
vals = self.types.get_enum_values(enum_name)
if vals:
opts = ', '.join(
f"{{ label: '{v}', value: {i} }}" for i, v in enumerate(vals)
)
entries.append(('enum', f'[{opts}]'))
if 'min' in a:
entries.append(('min', format_number(a['min'])))
if 'max' in a:
entries.append(('max', format_number(a['max'])))
if 'step' in a:
entries.append(('step', format_number(a['step'])))
if 'slider' in a:
entries.append(('slider', 'true'))
if 'unit' in a:
entries.append(('unit', json.dumps(a['unit'], ensure_ascii=False)))
if 'label' in a:
entries.append(('label', json.dumps(a['label'], ensure_ascii=False)))
if 'tooltip' in a:
entries.append(('tooltip', json.dumps(a['tooltip'], ensure_ascii=False)))
if 'category' in a:
entries.append(('category', json.dumps(a['category'], ensure_ascii=False)))
if 'advanced' in a:
entries.append(('advanced', 'true'))
if 'enum_source' in a:
entries.append(('enumSource', json.dumps(a['enum_source'], ensure_ascii=False)))
if 'label_source' in a:
entries.append(('labelSource', json.dumps(a['label_source'], ensure_ascii=False)))
if 'bitmask_source' in a:
entries.append(('bitmask', '{ source: ' + json.dumps(a['bitmask_source'], ensure_ascii=False) + ' }'))
if 'normalized_of' in a:
entries.append(('normalizedOf', json.dumps(a['normalized_of'], ensure_ascii=False)))
if 'shown_when' in a:
entries.append(('shownWhen', self._shown_when(comp, prop, a['shown_when'])))
if entries:
out.append((prop.name, entries))
return out
def _shown_when(self, comp: Component, prop, raw: str) -> str:
"""`shown_when=<field>:<State>|<State>` as `{ field, values: [n, ...] }`.
The states are resolved HERE, against the discriminator's own enum, because
this is where the enums are: the rule ships the numbers the data stores, and
reordering the enum moves the rule with it. A state that is not a member of
that enum is an error and not a 0 — a rule aimed at the wrong value hides a
field in the state it belongs to, which reads as the field having vanished.
"""
loc = f'{comp.name}.{prop.name}'
field, _, states = raw.partition(':')
sibling = next((p for p in comp.properties if p.name == field), None)
if sibling is None:
raise ValueError(f"{loc}: shown_when reads '{field}', which is not a field here")
t = self.types.clean_type(sibling.cpp_type)
enum_name = t if self.types.is_enum(t) else sibling.annotations.get('enum')
members = self.types.get_enum_values(enum_name) if enum_name else []
values: List[int] = []
for state in states.split('|'):
state = state.strip()
if members:
if state not in members:
raise ValueError(
f"{loc}: shown_when names '{state}', which {enum_name} has no member of"
)
values.append(members.index(state))
elif t == 'bool':
if state not in ('true', 'false'):
raise ValueError(
f"{loc}: shown_when on the bool '{field}' takes true or false, not '{state}'"
)
values.append(1 if state == 'true' else 0)
else:
raise ValueError(
f"{loc}: shown_when reads '{field}', which is {t} — a state is an enum"
' member or a bool'
)
return '{ field: ' + json.dumps(field) + ', values: [' + ', '.join(map(str, values)) + '] }'
def _get_editor_defaults(self, comp: Component) -> List[Tuple[str, str]]:
"""Collect `editor_default=` creation overrides as [(field, tsLiteral)].
The value goes through the SAME converter as the C++ ctor default, so an
annotation supports exactly the member-initializer grammar (number, bool,
Enum::Member, braced vector). A value the converter would silently turn
into 0 is a hard error — a wrong creation default baked into the generated
file is the drift this annotation exists to kill.
"""
out: List[Tuple[str, str]] = []
for prop in comp.properties:
raw = prop.annotations.get('editor_default')
if raw is None:
continue
loc = f'{comp.name}.{prop.name}'
t = self.types.clean_type(prop.cpp_type)
if self.types.is_enum(t):
member = raw.split('::')[-1].strip()
enum_short = t.split('::')[-1]
vals = self.types.get_enum_values(t)
if member not in (vals or []):
raise ValueError(
f"{loc}: editor_default '{raw}' names no member of {enum_short}")
# convert_default_ts resolves enum members from a `X::Member`
# form; normalize so `editor_default=Orthographic` also works.
raw = f'{enum_short}::{member}'
elif t == 'bool':
if raw not in ('true', 'false'):
raise ValueError(f"{loc}: editor_default '{raw}' must be true or false")
elif t in TypeSystem.PRIMITIVE_TYPES:
if not _is_number(raw):
raise ValueError(f"{loc}: editor_default '{raw}' must be numeric")
elif t in TypeSystem.GLM_TYPES:
if not (raw.startswith('{') and raw.endswith('}')):
raise ValueError(
f"{loc}: editor_default '{raw}' must be a braced initializer for {t}")
else:
raise ValueError(
f"{loc}: editor_default is not supported for type '{prop.cpp_type}'")
shadow = Property(name=prop.name, cpp_type=prop.cpp_type,
default_value=raw.strip().strip('{}') if t in TypeSystem.GLM_TYPES else raw,
annotations=prop.annotations)
out.append((prop.name, convert_default_ts(shadow, self.types, self._enum_values)))
return out
def _get_replicated_fields(self, comp: Component) -> List[str]:
return [p.name for p in comp.properties if 'replicated' in p.annotations]
def _get_skip_serialize_fields(self, comp: Component) -> List[str]:
return [p.name for p in comp.properties if 'skip_serialize' in p.annotations]
def _get_readonly_fields(self, comp: Component) -> List[str]:
return [p.name for p in comp.properties if 'readonly' in p.annotations]
def _get_animatable_fields(self, comp: Component) -> List[str]:
fields = []
for prop in comp.properties:
if 'animatable' not in prop.annotations:
continue
t = self.types.clean_type(prop.cpp_type)
if t == 'glm::vec2':
fields.extend([f'{prop.name}.x', f'{prop.name}.y'])
elif t == 'glm::vec3':
fields.extend([f'{prop.name}.x', f'{prop.name}.y', f'{prop.name}.z'])
elif t == 'glm::vec4':
if is_color_field(prop, self.types):
fields.extend([f'{prop.name}.r', f'{prop.name}.g', f'{prop.name}.b', f'{prop.name}.a'])
else:
fields.extend([f'{prop.name}.x', f'{prop.name}.y', f'{prop.name}.z', f'{prop.name}.w'])
elif t == 'glm::quat':
# The components, plus `.angle` for the Z turn a 2D scene thinks
# in. `.angle` is a way IN (it keeps the other two axes), not a
# second representation — a channel named `.z` for the Z EULER
# angle would take the name the z COMPONENT needs, and a 3D
# rotation could then only be animated by flattening it.
fields.extend([f'{prop.name}.x', f'{prop.name}.y', f'{prop.name}.z',
f'{prop.name}.w', f'{prop.name}.angle'])
else:
fields.append(prop.name)
return fields
# TS helper types a generated data interface field may reference (imported from
# './types'); custom-struct names (Padding/Dimension) come instead from
# './wasm.generated'.
_BASE_TS_TYPES = {'Entity', 'Vec2', 'Vec3', 'Vec4', 'Quat', 'Color'}
def _enum_ts_names(self) -> set:
"""Every enum name the generated wasm module publishes, which is where a
component-data field's enum type is imported from."""
if self._enum_names_cache is None:
self._enum_names_cache = {e.name for e in self.types.enums}
return self._enum_names_cache
_enum_names_cache = None
def _data_ts_type(self, prop: Property) -> str:
"""TS type for a component-DATA field — the plain serialized shape, not the
embind/Registry shape `TypeSystem.to_typescript` produces (which maps vectors
to emscripten wrappers and is color-blind). A color vec4 -> Color, an entity
ref -> Entity, an Entity vector -> Entity[], glm vecs -> their {x,y,..} types,
a registered custom struct -> its own interface name."""
t = self.types.clean_type(prop.cpp_type)
if is_color_field(prop, self.types):
return 'Color'
# Vectors before the scalar entity check: `entity_ref` also tags
# `std::vector<Entity>` (Children.entities), which must stay an array.
if self.types.is_entity_vector(t):
return 'Entity[]'
if t in self.types.VECTOR_TYPES:
return f'{self.types.CPP_TO_TS[self.types.VECTOR_TYPES[t][0]]}[]'
if self.types.is_struct_vector(t):
return f'{self.types.vector_elem_ts(t)}[]'
if self.types.is_handle(t):
return 'number'
if 'entity_ref' in prop.annotations or self.types.is_entity(t):
return 'Entity'
# The enum, not the width it is stored in: the generator knows which one
# (either the field IS one, or ES_PROPERTY(enum=) names it) and dropping
# that leaves every C++-backed enum field in the SDK typed `number`.
if self.types.is_enum(t):
return t.split('::')[-1]
named = prop.annotations.get('enum')
if named:
return named
if t in self.types.CUSTOM_STRUCTS:
return t
if t in ('glm::vec2', 'glm::uvec2'):
return 'Vec2'
if t == 'glm::vec3':
return 'Vec3'
if t == 'glm::vec4':
return 'Vec4'
if t == 'glm::quat':
return 'Quat'
if t == 'std::string':
return 'string'
if t == 'bool':
return 'boolean'
return 'number'
def _gen_interfaces(self):
"""Emit one `export interface <Name>Data` per component (the C++ field shape),
and report which './types' and './wasm.generated' helper types are referenced
so generate() can import exactly those. The skip rule matches the defaults
loop so each interface lists exactly the fields its defaults object carries."""
lines: List[str] = [
'// C++-backed builtin component data shapes — the ES_COMPONENT struct fields,',
'// generated so the TS field types cannot drift from the C++ structs. A consumer',
'// adds any TS-only authoring field (e.g. Camera.showFrustum) by extending these.',
'',
]
used_base: set = set()
used_struct: set = set()
for comp in self.components:
if not comp.properties:
continue
field_lines: List[str] = []
for prop in comp.properties:
if self.types.is_skip(prop.cpp_type) and prop.cpp_type not in self.types.VECTOR_TYPES:
continue
ts = self._data_ts_type(prop)
base = ts[:-2] if ts.endswith('[]') else ts
if base in self._BASE_TS_TYPES:
used_base.add(base)
elif base in self.types.CUSTOM_STRUCTS or base in self._enum_ts_names():
used_struct.add(base)
# `optional` relaxes the WRITE side only: the struct always has the
# field, and a reader gets the default. See parser.FLAG_ANNOTATIONS.
mark = '?' if 'optional' in prop.annotations else ''
field_lines.append(f' {prop.name}{mark}: {ts};')
# The SDK's tier, from ES_COMPONENT(stability=). It has to sit on the
# declaration: a release tag in this file's header would not survive
# the declaration bundle a project compiles against.
tier = comp.annotations.get('stability')
if tier:
lines.append('/**')
lines.append(f' * The fields of the engine\'s `{comp.name}` component, generated from')
lines.append(' * the C++ struct so the two shapes cannot drift.')
lines.append(' *')
lines.append(f' * @{tier}')
lines.append(' */')
lines.append(f'export interface {comp.name}Data {{')
lines.extend(field_lines)
lines.append('}')
lines.append('')
return lines, used_base, used_struct
def generate(self) -> str:
# Build the data interfaces first so we know which helper types to import.
iface_lines, used_base, used_struct = self._gen_interfaces()
lines = [
'/**',
' * @file component.generated.ts',
' * @brief Auto-generated component metadata',
' * @details Generated by EHT - DO NOT EDIT',
' */',
'',
"import type { AssetFieldType } from '../scene/scene';",
"import type { FieldMeta } from './component';",
]
if used_base:
lines.append(f"import type {{ {', '.join(sorted(used_base))} }} from '../types';")
if used_struct:
lines.append(f"import type {{ {', '.join(sorted(used_struct))} }} from '../wasm/wasm.generated';")
lines.append('')
lines += [
'/**',
' * Single-source-of-truth hash of the C++/TS boundary ABI (component',
' * schema + pointer layouts). The WASM module exposes the same digest via',
' * getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to',
' * run on mismatch, because mismatched offsets read the wrong heap bytes.',
' */',
f"export const ABI_LAYOUT_HASH = '{self.abi_hash}';",
'',
'/**',
' * One asset-valued field of a component: which field, and what kind of',
' * asset it holds. Declaring it is what gives the field dependency',
' * tracking, cook inclusion, `@uuid:` refs and hot-update.',
' *',
' * @public',
' */',
'export interface AssetFieldMeta {',
' field: string;',
' type: AssetFieldType;',
'}',
'',
'/**',
' * A skeleton/atlas field PAIR, which has to be declared together: the two',
' * files are one asset, and loading either alone yields nothing to draw.',
' *',
' * @public',
' */',
'export interface SkeletalFieldMeta {',
' skeletonField: string;',
' atlasField: string;',
' /** Which runtime the pair belongs to — `spine`, `dragonbones`. */',
' runtime: string;',
'}',
'',
'export interface ComponentMetaEntry {',
' defaults: Record<string, unknown>;',
' /**',
' * Creation-time overrides authored at the C++ ES_PROPERTY site via',
' * `editor_default=` — where the authoring default deliberately differs',
' * from the C++ ctor value in `defaults`. Component registration merges',
' * these over `defaults`; `defaults` alone is the runtime ctor truth.',
' */',
' editorDefaults?: Record<string, unknown>;',
' /**',
' * The bool field that gates this component\'s part in the entity\'s',
' * visibility, authored `renderable=<field>` at the C++ ES_COMPONENT',
' * site. Absent = nothing of this component is hidden by hiding its',
' * entity. ONE answer for both realms: the runtime folds visibility',
' * onto these fields, and the editor\'s eye reaches exactly them.',
' */',
' renderableField?: string;',
' /**',
' * Runtime-only state that must never persist, authored `transient` at',
' * the C++ ES_COMPONENT site — scene serialization omits it.',
' */',
' transient?: boolean;',
' assetFields: AssetFieldMeta[];',
' skeletal?: SkeletalFieldMeta;',
' entityFields: string[];',
' /**',
' * Fields whose value is a LIST, which has no place in the zero-copy',
' * component buffer a native host writes through — its storage is a',
' * pointer. Each crosses as its own generated',
' * `es_<Component>_<field>_get/_set` pair. Entity lists predate this',
' * and keep the hand-written pair the registry wires them by.',
' */',
' listFields?: string[];',
' /**',
' * List fields whose elements are NUMBERS, which the web boundary',
' * marshals as a registered embind vector rather than a JS array.',
' * Apart from `entityFields`: that list also re-aims references when',
' * a prefab is instantiated, and a weight is a value, not a reference.',
' */',
' numberListFields?: string[];',
' colorFields: string[];',
' animatableFields: string[];',
' /**',
' * Fields authored `replicated` at the C++ ES_PROPERTY site — the',
' * single source of truth for what the network replication layer',
' * syncs (RC11). Whole-field granularity; absent = nothing replicates.',
' */',
' replicatedFields?: string[];',
' /** Fields authored `skip_serialize` — runtime-only state scene serialization omits. */',
' skipSerializeFields?: string[];',
' /**',
' * Fields authored `readonly` — engine-COMPUTED outputs (e.g. Transform\'s',
' * world-space fields), never authoring inputs. The editor must not project',
' * them back into the World: writing their (stale/zero) model value clobbers',
' * the value the engine composes each frame.',
' */',
' readonlyFields?: string[];',
' fields?: Record<string, FieldMeta>;',
'}',
'',
'export const COMPONENT_META: Record<string, ComponentMetaEntry> = {',
]
for comp in self.components:
if not comp.properties:
continue
asset_fields = self._get_asset_fields(comp)
skeletal = self._get_skeletal_descriptor(comp)
entity_fields = self._get_entity_fields(comp)
color_fields = self._get_color_fields(comp)
animatable = self._get_animatable_fields(comp)
lines.append(f' {comp.name}: {{')
lines.append(' defaults: {')
for prop in comp.properties:
if self.types.is_skip(prop.cpp_type) and prop.cpp_type not in self.types.VECTOR_TYPES:
continue
val = convert_default_ts(prop, self.types, self._enum_values)
lines.append(f' {prop.name}: {val},')
lines.append(' },')
editor_defaults = self._get_editor_defaults(comp)
if editor_defaults:
lines.append(' editorDefaults: {')
for fname, val in editor_defaults:
lines.append(f' {fname}: {val},')
lines.append(' },')
renderable_field = comp.annotations.get('renderable')
if renderable_field:
lines.append(f" renderableField: '{renderable_field}',")
if 'transient' in comp.annotations:
lines.append(' transient: true,')
if asset_fields:
parts = ', '.join(
f"{{ field: '{f['field']}', type: '{f['type']}' as AssetFieldType }}"
for f in asset_fields
)
lines.append(f' assetFields: [{parts}],')
else:
lines.append(' assetFields: [],')
if skeletal:
lines.append(
f" skeletal: {{ skeletonField: '{skeletal['skeletonField']}', "
f"atlasField: '{skeletal['atlasField']}', runtime: '{skeletal['runtime']}' }},"
)
if entity_fields:
parts = ', '.join(f"'{f}'" for f in entity_fields)
lines.append(f' entityFields: [{parts}],')
else:
lines.append(' entityFields: [],')
list_fields = [p.name for p in comp.properties
if self.types.is_struct_vector(p.cpp_type)
or self._is_number_list(p)
or self._is_entity_list(comp, p)]
if list_fields:
parts = ', '.join(f"'{f}'" for f in list_fields)
lines.append(f' listFields: [{parts}],')
number_lists = [p.name for p in comp.properties if self._is_number_list(p)]
if number_lists:
parts = ', '.join(f"'{f}'" for f in number_lists)
lines.append(f' numberListFields: [{parts}],')
if color_fields:
parts = ', '.join(f"'{f}'" for f in color_fields)
lines.append(f' colorFields: [{parts}],')
else:
lines.append(' colorFields: [],')
if animatable:
parts = ', '.join(f"'{f}'" for f in animatable)
lines.append(f' animatableFields: [{parts}],')
else:
lines.append(' animatableFields: [],')
replicated = self._get_replicated_fields(comp)
if replicated:
parts = ', '.join(f"'{f}'" for f in replicated)
lines.append(f' replicatedFields: [{parts}],')
skip_serialize = self._get_skip_serialize_fields(comp)
if skip_serialize:
parts = ', '.join(f"'{f}'" for f in skip_serialize)
lines.append(f' skipSerializeFields: [{parts}],')
readonly = self._get_readonly_fields(comp)
if readonly:
parts = ', '.join(f"'{f}'" for f in readonly)
lines.append(f' readonlyFields: [{parts}],')
field_meta = self._get_field_meta(comp)
if field_meta:
lines.append(' fields: {')
for fname, entries in field_meta:
parts = ', '.join(f'{k}: {v}' for k, v in entries)
lines.append(f' {fname}: {{ {parts} }},')
lines.append(' },')
lines.append(' },')
lines.append('};')
lines.append('')
lines.extend(iface_lines)
return '\n'.join(lines)