feat: add EnumDefineBuilder to support enum define

engsr6982 · engsr6982 · commit b8f423cbd6e3 · 2025-04-17T09:44:23.000+08:00
diff --git a/ApiDesign.md b/ApiDesign.md
@@ -0,0 +1,219 @@
+# JsEngine Api design
+
+**JsEngine Api** 设计，除了 `endstone` 本身提供的 `Api`，借助 **ast-dumper** 的能力，可以往 `JsEngine` 添加一些标识类型的 `Api`，方便调试。
+
+所有引擎提供的 Api 都以 `$` 开头，避免和 `endstone` 的 `Api` 冲突。
+
+## enum
+
+由于 **js** 没有枚举，所以借助 `class` 的能力来模拟枚举，所有 `endstone` 中的枚举都定义为 `static property`，并且添加一些 **engine helper api** 辅助调试。
+
+`nickName` 是 **engine** 侧的枚举名，`c_type` 是 C++ 侧的枚举名。
+引入 `nickName` 是为了避免枚举冲突。
+
+### C++ 侧:
+
+```cpp
+enum class TestEnum {
+  value1,
+  value2,
+  value3,
+};
+```
+
+### Js 侧:
+
+```js
+// T -> enum
+class T {
+  static get value1() {
+    /* native code */
+  }
+
+  //! engine helper api
+  /**
+   * 枚举的所有值
+   */
+  static get $values() {
+    /* native code */
+  }
+
+  /**
+   * 枚举的所有键名
+   */
+  static get $keys() {
+    /* native code */
+  }
+
+  /**
+   * 枚举值对应的键名
+   */
+  static $enum_name(T) {
+    /* native code */
+  }
+
+  /**
+   * C++ 侧的原始枚举名
+   */
+  static get $c_type() {
+    /* native code */
+  }
+
+  /**
+   * 注册到 engine 的枚举名
+   */
+  static get $nick_name() {
+    /* native code */
+  }
+}
+```
+
+## class
+
+这个和 C++ 侧的 `class` 是一样的，只是多了一些 **engine helper api**。
+不过由于 js 不支持多继承，所以 C++ 侧的 `class` 是采用全量绑定，在 js 侧就是一个个完全独立的 `class。`
+
+### C++ 侧:
+
+```cpp
+
+namespace endstone {
+
+  class Actor {
+    public:
+      virtual void move() = 0;
+  };
+
+  class Mob : public Actor {
+    public:
+      virtual void attack() = 0;
+  };
+
+  class Player : public Mob {
+    public:
+      virtual void jump() = 0;
+  };
+
+} // namespace endstone
+
+
+namespace jse {
+
+class ActorWrapper : public ScriptClass {
+  endstone::Actor* actor;
+
+  public:
+  Local<Value> move(Arguments const& args) {
+    actor->move();
+  }
+};
+
+class MobWrapper : public ScriptClass {
+  endstone::Mob* mob;
+
+  public:
+  Local<Value> attack(Arguments const& args) {
+    mob->attack();
+  }
+};
+
+class PlayerWrapper : public ScriptClass {
+  endstone::Player* player;
+
+  public:
+  Local<Value> jump(Arguments const& args) {
+    player->jump();
+  }
+};
+
+ClassDefine<ActorWrapper> ActorBuilder = defineClass("Actor")
+  .constructor(nullptr)
+  .instanceFunction("move", &ActorWrapper::move)
+  .build();
+
+ClassDefine<MobWrapper> MobBuilder = defineClass("Mob")
+  .constructor(nullptr)
+  .instanceFunction("attack", &MobWrapper::attack)
+  // Actor
+  .instanceFunction("move", &ActorWrapper::move)
+  .build();
+
+ClassDefine<PlayerWrapper> PlayerBuilder = defineClass("Player")
+  .constructor(nullptr)
+  // Actor
+  .instanceFunction("move", &ActorWrapper::move)
+  // Mob
+  .instanceFunction("attack", &MobWrapper::attack)
+  // Player
+  .instanceFunction("jump", &PlayerWrapper::jump)
+  .build();
+
+} // namespace jse
+
+```
+
+### Js 侧:
+
+```js
+class Actor {
+  // C++ 侧没有注册 constructor，所以这里没有 constructor
+
+  move() {
+    /* native code */
+  }
+
+  //! engine helper api
+  static get $c_type() {
+    /* native code */
+  }
+
+  static get $nick_name() {
+    /* native code */
+  }
+
+  /**
+   * 引用类型
+   * C++ 侧分为原始指针、独占指针、共享指针，通过此方法得知当前的 native 资源持有方式
+   */
+  get $ref_type() {
+    /* native code */
+  }
+
+  /**
+   * 引用计数
+   * 只有当 $ref_type 为 shared_ptr 时才有效
+   */
+  get $ref_count() {
+    /* native code */
+  }
+
+  /**
+   * 对两个对象进行相等性比较
+   * 由于 js 侧的比较无法准确判断两个对象是否相等，所以引擎提供了此方法，此方法会调用 C++ 侧的 operator==
+   */
+  static $equals(a, b) {
+    /* native code */
+  }
+}
+
+class Mob {
+  move() {
+    /* native code */
+  }
+
+  attack() {
+    /* native code */
+  }
+
+  //引擎API同Actor
+}
+
+// Player 同理
+```
+
+## function
+
+这里没啥好说的，除了 js function 不支持重载，其它都一样。
+
+对于多重载方法，C++ 侧只注册一个方法，通过参数类型决定调用哪个方法。
+如果参数类型不匹配，则抛出 `Wrong argument type, please check the documentation` 异常。
diff --git a/src/helper/EnumHelper.h b/src/helper/EnumHelper.h
@@ -0,0 +1,124 @@
+#pragma once
+#include "helper/Using.h"
+#include "magic_enum/magic_enum.hpp"
+#include <exception>
+#include <map>
+#include <string>
+#include <string_view>
+#include <unordered_map>
+
+
+namespace jse {
+
+
+// range: [-128, 128)
+template <typename T>
+struct EnumDefineBuilder {
+    std::string mNickName;
+    std::string mOriginName;
+
+    // 补充的枚举值(处理超出 magic_enum 范围的枚举)
+    std::unordered_map<std::string, int> mSupplementEnumKV;
+    std::unordered_map<int, std::string> mSupplementEnumVK;
+    inline EnumDefineBuilder<T>&         supplementEnum(std::string_view name, T val) {
+        mSupplementEnumKV[std::string(name)]     = static_cast<int>(val);
+        mSupplementEnumVK[static_cast<int>(val)] = name;
+        return *this;
+    }
+
+    explicit EnumDefineBuilder<T>(std::string originName, std::string nickName = "") {
+        mOriginName = std::move(originName);
+        mNickName   = nickName.empty() ? originName : std::move(nickName);
+    }
+
+    inline void registerHelperFunc(script::ClassDefineBuilder<void>& builder) {
+        builder.property("$c_type", [=]() -> Local<Value> {
+            try {
+                return String::newString(mOriginName);
+            } catch (script::Exception const& e) {
+            } catch (std::exception const& e) {}
+        });
+
+        builder.property("$nick_name", [=]() -> Local<Value> {
+            try {
+                return String::newString(mNickName);
+            } catch (script::Exception const& e) {
+            } catch (std::exception const& e) {}
+        });
+
+        builder.property("$keys", [=]() -> Local<Value> {
+            try {
+                auto keys  = magic_enum::enum_names<T>();
+                auto array = Array::newArray(keys.size());
+                for (size_t i = 0; i < keys.size(); ++i) {
+                    array.set(i, String::newString(std::string(keys[i])));
+                }
+                if (!mSupplementEnumKV.empty()) {
+                    for (const auto& [name, value] : mSupplementEnumKV) {
+                        array.add(String::newString(name));
+                    }
+                }
+                return array;
+            } catch (script::Exception const& e) {
+            } catch (std::exception const& e) {}
+        });
+
+        builder.property("$values", [=]() -> Local<Value> {
+            try {
+                auto values = magic_enum::enum_values<T>();
+                auto array  = Array::newArray(values.size());
+                for (size_t i = 0; i < values.size(); ++i) {
+                    array.set(i, Number::newNumber(static_cast<int>(values[i])));
+                }
+                if (!mSupplementEnumKV.empty()) {
+                    for (const auto& [name, value] : mSupplementEnumKV) {
+                        array.add(Number::newNumber(value));
+                    }
+                }
+                return array;
+            } catch (script::Exception const& e) {
+            } catch (std::exception const& e) {}
+        });
+
+        builder.function("$enum_name", [=](Arguments const& args) -> Local<Value> {
+            try {
+                if (args.size() != 1 || !args[0].isNumber()) {
+                    return {};
+                }
+                auto val = args[0].asNumber().toInt32();
+                if (val < -128 || val > 128) {
+                    if (mSupplementEnumVK.find(val) != mSupplementEnumVK.end()) {
+                        return String::newString(mSupplementEnumVK[val]);
+                    }
+                }
+                return String::newString(magic_enum::enum_name(static_cast<T>(val)));
+            } catch (script::Exception const& e) {
+            } catch (std::exception const& e) {}
+        });
+    }
+
+    [[nodiscard]] inline ClassDefine<void> build(std::string nickName) {
+        script::ClassDefineBuilder<void> builder = defineClass(std::move(nickName));
+
+        // 注册枚举
+        for (auto& [val, name] : magic_enum::enum_entries<T>()) {
+            auto _val = val;
+            builder.property(std::string(name), [=]() -> Local<Value> {
+                try {
+                    return Number::newNumber(static_cast<int>(_val));
+                } catch (script::Exception const& e) {
+                } catch (std::exception const& e) {}
+            });
+        }
+        for (const auto& [name, value] : mSupplementEnumKV) {
+            builder.property(name, [=]() -> Local<Value> { return Number::newNumber(value); });
+        }
+
+        registerHelperFunc(builder);
+
+        return builder.build();
+    }
+};
+
+
+} // namespace jse
