feat: initial DX12 foundation framework

2026-03-19 18:27:49 +08:00
commit 60f73b525d
70 changed files with 8993 additions and 0 deletions
--- a/Engine/Components/Script.cpp
+++ b/Engine/Components/Script.cpp
@@ -0,0 +1,367 @@
+/**
+ * @file Script.cpp
+ * @brief 脚本组件存储、脚本注册表与逐帧更新实现。
+ * @details
+ * 该文件负责脚本系统运行时核心流程：
+ * - 维护脚本实例数组与 script_id 到实例下标映射；
+ * - 维护脚本工厂注册表，支持按哈希查询创建函数；
+ * - 在脚本回调中缓存变换修改，并在帧末批量提交到 Transform 系统。
+ */
+#include "Script.h"
+#include "Entity.h"
+#include "Transform.h"
+
+#define USE_TRANSFORM_CACHE_MAP 1
+
+
+namespace XEngine::script {
+namespace {
+/**
+ * @brief 活跃脚本实例数组。
+ */
+utl::vector<detail::script_ptr>					entity_scripts;
+/**
+ * @brief script_id 索引到实例数组下标的映射。
+ */
+utl::vector<id::id_type>						id_mapping;
+
+/**
+ * @brief script_id 代数数组。
+ */
+utl::vector<id::generation_type>				generations;
+/**
+ * @brief 可复用 script_id 队列。
+ */
+utl::deque<script_id>							free_ids;
+
+/**
+ * @brief 脚本对 Transform 的延迟修改缓存。
+ */
+utl::vector<transform::component_cache>			transform_cache;
+
+#if USE_TRANSFORM_CACHE_MAP
+std::unordered_map<id::id_type, u32>			cache_map;
+#endif
+
+
+using script_registry = std::unordered_map<size_t, detail::script_creator>;
+
+
+/**
+ * @brief 获取全局脚本工厂注册表。
+ * @return 注册表引用。
+ */
+script_registry&
+registery()
+{
+	static script_registry reg;
+	return reg;
+}
+#ifdef USE_WITH_EDITOR
+/**
+ * @brief 获取编辑器脚本名集合。
+ * @return 脚本名数组引用。
+ */
+utl::vector<std::string>&
+script_names()
+{
+	static utl::vector<std::string> names;
+	return names;
+}
+
+#endif
+
+/**
+ * @brief 判断脚本组件是否存在且有效。
+ * @param id 脚本组件 ID。
+ * @return 存在返回 true。
+ */
+bool
+exists(script_id id)
+{
+	assert(id::is_valid(id));
+	const id::id_type index{ id::index(id) };
+	assert(index < generations.size() && id_mapping[index] < entity_scripts.size());
+	assert(generations[index] == id::generation(id));
+	return (generations[index] == id::generation(id) &&
+		entity_scripts[id_mapping[index]] &&
+		entity_scripts[id_mapping[index]]->is_valid());
+}
+
+#if USE_TRANSFORM_CACHE_MAP
+/**
+ * @brief 获取实体对应的 Transform 缓存项。
+ * @param entity 目标实体。
+ * @return 缓存项指针。
+ */
+transform::component_cache *const
+get_cache_ptr(const game_entity::entity *const entity)
+{
+	assert(game_entity::is_alive((*entity).get_id()));
+	const transform::transform_id id{ (*entity).transform().get_id() };
+
+	u32 index{ u32_invalid_id };
+	auto pair = cache_map.try_emplace(id, id::invalid_id);
+
+	if (pair.second)
+	{
+		index = (u32)transform_cache.size();
+		transform_cache.emplace_back();
+		transform_cache.back().id = id;
+		cache_map[id] = index;
+	}
+	else
+	{
+		index = cache_map[id];
+	}
+
+	assert(index < transform_cache.size());
+	return &transform_cache[index];
+}
+#else
+/**
+ * @brief 线性查找方式获取 Transform 缓存项。
+ * @param entity 目标实体。
+ * @return 缓存项指针。
+ */
+transform::component_cache *const
+get_cache_ptr(const game_entity::entity *const entity)
+{
+	assert(game_entity::is_alive((*entity).get_id()));
+	const  transform::transform_id id{ (*entity).transform().get_id() };
+
+	for (auto& cache : transform_cache)
+	{
+		if (cache.id == id)
+		{
+			return &cache;
+		}
+	}
+
+	transform_cache.emplace_back();
+	transform_cache.back().id = id;
+
+	return &transform_cache.back();
+}
+#endif
+}// namespace
+
+
+namespace detail {
+
+/**
+ * @brief 注册脚本工厂函数。
+ * @param tag 脚本名哈希。
+ * @param func 工厂函数。
+ * @return 注册成功返回 1。
+ */
+u8
+register_script(size_t tag, script_creator func)
+{
+	bool result{ registery().insert(script_registry::value_type{tag, func}).second };
+	assert(result);
+	return result;
+}
+
+/**
+ * @brief 按哈希获取脚本工厂函数。
+ * @param tag 脚本名哈希。
+ * @return 脚本工厂函数。
+ */
+script_creator
+get_script_creator(size_t tag)
+{
+	auto script = XEngine::script::registery().find(tag);
+	assert(script != XEngine::script::registery().end() && script->first == tag);
+	return script->second;
+}
+
+#ifdef USE_WITH_EDITOR
+/**
+ * @brief 记录脚本名称供编辑器使用。
+ * @param name 脚本类名。
+ * @return 写入成功返回 1。
+ */
+u8
+add_script_name(const char* name)
+{
+	script_names().emplace_back(name);
+	return true;
+}
+
+#endif
+
+}// namespace detail
+
+
+/**
+ * @brief 创建脚本组件并实例化脚本对象。
+ * @param info 脚本初始化参数。
+ * @param entity 绑定实体。
+ * @return 脚本组件句柄。
+ */
+component
+create(init_info info, game_entity::entity entity)
+{
+	assert(entity.is_valid());
+	assert(info.script_creator);
+
+	script_id id{};
+	if (free_ids.size() > id::min_deleted_elements)
+	{
+		id = free_ids.front();
+		assert(!exists(id));
+		free_ids.pop_front();
+		id = script_id{ id::new_generation(id) };
+		++generations[id::index(id)];
+
+	}
+	else
+	{
+		id = script_id{ (id::id_type)id_mapping.size() };
+		id_mapping.emplace_back();
+		generations.push_back(0);
+	}
+	assert(id::is_valid(id));
+	const id::id_type index{ (id::id_type)entity_scripts.size() };
+	entity_scripts.emplace_back(info.script_creator(entity));
+	assert(entity_scripts.back()->get_id() == entity.get_id());
+	id_mapping[id::index(id)] = index;
+
+	return component{ id };
+}
+
+
+/**
+ * @brief 删除脚本组件并更新映射关系。
+ * @param c 脚本组件句柄。
+ */
+void
+remove(component c)
+{
+	assert(c.is_valid() && exists(c.get_id()));
+	const script_id id{ c.get_id() };
+	const id::id_type index{ id::index(id) };
+	const script_id last_id{ entity_scripts.back()->script().get_id() };
+	utl::erase_unordered(entity_scripts, index);
+	id_mapping[id::index(last_id)] = index;
+	id_mapping[id::index(id)] = id::invalid_id;
+}
+
+/**
+ * @brief 执行脚本逐帧更新并提交变换缓存。
+ * @param dt 帧时间步长。
+ */
+void
+update(float dt) {
+	for (auto& ptr : entity_scripts)
+	{
+		ptr->update(dt);
+	}
+
+	if (transform_cache.size())
+	{
+		transform::update(transform_cache.data(), (u32)transform_cache.size());
+		transform_cache.clear();
+
+#if USE_TRANSFORM_CACHE_MAP
+		cache_map.clear();
+#endif
+	}
+}
+
+/**
+ * @brief 缓存脚本写入的旋转变更。
+ * @param entity 目标实体。
+ * @param rotation_quaternion 旋转四元数。
+ */
+void
+entity_script::set_rotation(const game_entity::entity *const entity, math::v4 rotation_quaternion)
+{
+	transform::component_cache& cache{ *get_cache_ptr(entity) };
+	cache.flags |= transform::component_flags::rotation;
+	cache.rotation = rotation_quaternion;
+}
+/**
+ * @brief 缓存脚本写入的朝向变更。
+ * @param entity 目标实体。
+ * @param orientation_vector 朝向向量。
+ */
+void
+entity_script::set_orientation(const game_entity::entity *const entity, math::v3 orientation_vector)
+{
+	transform::component_cache& cache{ *get_cache_ptr(entity) };
+	cache.flags |= transform::component_flags::orientation;
+	cache.orientation = orientation_vector;
+}
+/**
+ * @brief 缓存脚本写入的位置变更。
+ * @param entity 目标实体。
+ * @param position 位置向量。
+ */
+void
+entity_script::set_position(const game_entity::entity *const entity, math::v3 position)
+{
+	transform::component_cache& cache{ *get_cache_ptr(entity) };
+	cache.flags |= transform::component_flags::position;
+	cache.position = position;
+}
+/**
+ * @brief 缓存脚本写入的缩放变更。
+ * @param entity 目标实体。
+ * @param scale 缩放向量。
+ */
+void
+entity_script::set_scale(const game_entity::entity *const entity, math::v3 scale)
+{
+	transform::component_cache& cache{ *get_cache_ptr(entity) };
+	cache.flags |= transform::component_flags::scale;
+	cache.scale = scale;
+}
+
+} // namespace script
+
+#ifdef USE_WITH_EDITOR 
+
+/**
+ * @brief ATL 的 SAFEARRAY 封装头。
+ * @details
+ * 该头文件提供 CComSafeArray，用于在编辑器导出路径中构造 COM 安全数组，
+ * 以便把脚本名列表跨 DLL 边界返回给外部调用方。
+ */
+#include <atlsafe.h>
+
+/**
+ * @brief 导出脚本名列表给编辑器端。
+ * @details
+ * 返回值为 LPSAFEARRAY（SAFEARRAY*），元素类型为 BSTR。
+ * 内部流程：
+ * - 从 script_names() 读取脚本名数量；
+ * - 为空时返回 nullptr；
+ * - 使用 CComSafeArray<BSTR> 分配数组；
+ * - 逐项把 std::string 转成 BSTR 填入数组；
+ * - 通过 Detach 转移 SAFEARRAY 所有权给调用方。
+ * 调用方在不再使用后应负责释放 SAFEARRAY。
+ */
+extern "C" __declspec(dllexport)
+LPSAFEARRAY
+get_script_names()
+{
+	// 读取当前已注册脚本名数量。
+	const u32 size{ (u32)XEngine::script::script_names().size() };
+
+	// 没有脚本时返回空指针，避免创建空 SAFEARRAY。
+	if (!size) return nullptr;
+
+	// 创建固定长度的 BSTR 安全数组。
+	CComSafeArray<BSTR> names(size);
+
+	// 将脚本名逐项转换为 BSTR 并写入数组。
+	for (u32 i{ 0 }; i < size; ++i)
+	{
+		names.SetAt(i, A2BSTR_EX(XEngine::script::script_names()[i].c_str()), false);
+	}
+	// 释放 CComSafeArray 对底层 SAFEARRAY 的管理并返回给调用方。
+	return names.Detach();
+}
+#endif