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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file Reflection.hpp
* @brief Reflection and metadata system for automatic binding generation
* @details Provides macros for marking components and properties that should
* be automatically exposed to scripting languages. Uses a declarative
* macro-based approach for code generation.
*
* @author ESEngine Team
* @date 2026
*
* @copyright Copyright (c) 2026 ESEngine Team
* Licensed under the Apache License, Version 2.0.
*/
#pragma once
// =============================================================================
// Reflection Macros
// =============================================================================
/**
* @brief Mark a struct/class as a component that should be exposed to scripts
*
* @details This macro generates metadata that the binding generator tool uses
* to automatically create JavaScript/TypeScript bindings. Place this
* macro immediately before the struct/class definition.
*
* `ES_COMPONENT(renderable=<field>, transient)` states what is true of
* the COMPONENT, as ES_PROPERTY does for a field; both realms read it out
* of the generated `COMPONENT_META`. `renderable` names the bool gating
* this component's drawing — a hard EHT error unless that bool exists.
*
* `stability=public|beta|experimental` is the SDK tier of the generated
* `<Name>Data` interface, declared here because the generated file is
* not editable and an untagged symbol is experimental by default.
*
* @code
* ES_COMPONENT(renderable=enabled)
* struct Sprite {
* ES_PROPERTY()
* bool enabled{true};
* };
* @endcode
*/
#define ES_COMPONENT(...)
/**
* @brief Mark a field as a property that should be exposed to scripts
*
* @details Properties marked with this macro will be accessible from
* JavaScript/TypeScript with automatic getter/setter generation.
* Only works inside ES_COMPONENT() marked types.
*
* This is the single authoring site for a field's editor/serialization
* metadata (RC9-1): the value lives in the struct, the presentation policy
* lives in the annotation, and EHT generates both the TS metadata and the
* C++ editor schema from it. Vocabulary parsed/validated by EHT:
*
* Semantics (flags):
* - asset=<type> : asset reference (texture, material, font, audio, spine_skeleton, spine_atlas)
* - animatable : keyframeable via the Sequencer/timeline
* - anim_override : field may be tween-driven; layout must not clobber it
* - anim_flag=<flag> : animation side-effect flag (e.g. ANIM_POS_X on UINode)
* - entity_ref : entity reference (remapped on scene load / instancing)
* - readonly : not editable in the inspector
*
* Editor presentation:
* - min=<n> / max=<n> / step=<n> : numeric range and scrub granularity
* - slider : render as a slider (requires both min= and max=)
* - unit=<s> : unit suffix shown after the value (e.g. °, px, %)
* - label=<s> / tooltip=<s> : human label / hover text
* - category=<s> : inspector group header
* - advanced : tuck behind an "advanced" fold
* - enum_source=<name> / bitmask_source=<name> : editor-resolved option/label source
* - normalized_of=<field> : this value is a fraction of that sibling (same
* type), so the editor can offer a pixel view of it
*
* Serialization / runtime policy:
* - invalidates=<field> : after an editor set, flip <field> so the owning
* system re-runs its load path next tick
* - skip_serialize : omit from scene serialization (runtime-only state)
* - replicated : eligible for network replication (RC11; reserved)
*
* Malformed *known* metadata (a non-numeric min=, slider without a range,
* invalidates=/normalized_of= naming no field) is a hard EHT error, not a
* silent drop.
*
* Examples:
* ES_PROPERTY(asset=texture)
* ES_PROPERTY(animatable, anim_flag=ANIM_POS_X)
* ES_PROPERTY(min=0, max=180, unit="°", advanced, category="Spot")
* ES_PROPERTY(invalidates=needsReload)
*/
#define ES_PROPERTY(...)
/**
* @brief Mark a method that should be exposed to scripts
*
* @details Methods marked with this macro will be callable from
* JavaScript/TypeScript. Works for both member functions
* and static functions.
*
* @param ... Optional attributes (e.g., "const", "static")
*/
#define ES_METHOD(...)
/**
* @brief Mark an enum that should be exposed to scripts
*
* @details Enums marked with this macro will be available as
* TypeScript enums with proper type checking.
*
* `stability=public|beta|experimental` is the SDK tier of the generated
* enum. A component's fields are made of these, so an enum weaker than
* the component naming it is a promise with a hole where its vocabulary
* should be. Untagged means `experimental`, as everywhere else.
*/
#define ES_ENUM(...)
/**
* @brief Mark a constant that CROSSES the boundary, so EHT emits its TS twin
*
* @details Hand-copied, such a constant does not fail when it drifts — a wrong
* mask decodes a stored cell into a different tile. Marked, it has one
* author and joins the ABI layout hash. `ts=<Name>` renames the
* generated symbol; `hex` emits the value as hex, for a mask.
*/
#define ES_CONST(...)
/**
* @brief Mark an enum value for explicit naming in bindings
*
* @details Use this to provide custom names for enum values in scripts,
* or to document their meaning for the binding generator.
*
* @param name Optional custom name for the enum value
*/
#define ES_ENUM_VALUE(name)
// =============================================================================
// Metadata Extraction Markers
// =============================================================================
/**
* @brief Begin a reflection block for the binding generator
*
* @details The binding generator tool scans for blocks between
* ES_REFLECT_BEGIN and ES_REFLECT_END to find types that
* need bindings. This is used in header files.
*/
#define ES_REFLECT_BEGIN
/**
* @brief End a reflection block for the binding generator
*/
#define ES_REFLECT_END
// =============================================================================
// Type Traits for Reflection
// =============================================================================
namespace esengine {
/**
* @brief Type trait to detect if a type is a reflected component
*
* @details This is used by the binding system to verify types at compile time.
* Specialized by the binding generator for each ES_COMPONENT type.
*
* @tparam T Type to check
*/
template<typename T>
struct is_component : std::false_type {};
/**
* @brief Helper variable template for is_component
*/
template<typename T>
inline constexpr bool is_component_v = is_component<T>::value;
/**
* @brief Get the script name for a component type
*
* @details Returns the name used in JavaScript/TypeScript bindings.
* Specialized by the binding generator for each ES_COMPONENT type.
*
* @tparam T Component type
* @return Script name as string literal
*/
template<typename T>
inline constexpr const char* component_name() {
return "UnknownComponent";
}
} // namespace esengine
// =============================================================================
// Usage Examples
// =============================================================================
/**
* @example Basic Component
*
* @code
* ES_COMPONENT()
* struct Position {
* ES_PROPERTY()
* f32 x = 0.0f;
*
* ES_PROPERTY()
* f32 y = 0.0f;
* };
* @endcode
*
* @example Component with Methods
*
* @code
* ES_COMPONENT()
* struct Health {
* ES_PROPERTY()
* f32 current = 100.0f;
*
* ES_PROPERTY()
* f32 maximum = 100.0f;
*
* ES_METHOD()
* void heal(f32 amount) {
* current = std::min(current + amount, maximum);
* }
*
* ES_METHOD(const)
* bool isDead() const {
* return current <= 0.0f;
* }
* };
* @endcode
*
* @example Enum Binding
*
* @code
* ES_ENUM()
* enum class DamageType : u8 {
* ES_ENUM_VALUE("Physical")
* Physical,
*
* ES_ENUM_VALUE("Magical")
* Magical,
*
* ES_ENUM_VALUE("True")
* True
* };
* @endcode
*/