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 UISystem.hpp
* @brief UI subsystem owning layout tree and hit-test state
* @details Consolidates UITree and UIHitTestResult into a single service
* registered on EstellaContext. Replaces the previous file-level
* static globals (s_ui_tree, s_hit_test_result).
*
* @author ESEngine Team
* @date 2026
*/
#pragma once
#include "../core/Types.hpp"
#include "../ecs/Entity.hpp"
#include "../ecs/Registry.hpp"
#include "./UITree.hpp"
#include "./UIHitTestSystem.hpp"
#include <memory>
#include <unordered_set>
#include <unordered_map>
#include <vector>
namespace esengine::resource { class ResourceManager; }
namespace esengine::ecs {
// Retained Yoga node cache — persists YGNodes across frames so a stable UI tree
// is not reallocated every solve. Defined in UILayoutSystem.cpp (holds Yoga
// types, kept out of this header).
struct LayoutCache;
/**
* @brief Result of the most recent hit-test pass
*/
struct UIHitTestResult {
Entity hit_entity{INVALID_ENTITY};
Entity prev_hit_entity{INVALID_ENTITY};
};
/**
* @brief UI subsystem: owns layout tree + hit-test state
*
* @details Registered as a service on EstellaContext. All UI layout and
* hit-test state lives on this instance; no file-level globals.
*
* @code
* auto& ui = ctx.require<ecs::UISystem>();
* ui.layoutUpdate(registry, -960, -540, 960, 540);
* ui.hitTestUpdate(registry, PickRay{cameraPos, pointerDir}, &resources);
* auto hitEntity = ui.getHitEntity();
* @endcode
*/
class UISystem {
public:
UISystem();
~UISystem(); // out-of-line: layoutCache_ holds an incomplete LayoutCache here.
UISystem(const UISystem&) = delete;
UISystem& operator=(const UISystem&) = delete;
// ---- State (public by design: thin wrapper over data) ----
UITree tree;
UIHitTestResult hitResult;
std::unique_ptr<LayoutCache> layoutCache_;
// ---- Layout pass (defined in UILayoutSystem.cpp) ----
/** @brief Rebuild layout tree and apply layout to all dirty nodes.
* The four bounds are the world-space box UI is laid out within: its size is
* what Yoga solves against, its center is where screen roots are placed.
* @param tsPropertyDirty Set by the TS driver when any UINode/FlexContainer
* changed since the last pass (via change-tracking). Combined with the
* C++-detected structure/box/animation signals to skip the whole
* rebuild+solve on a fully static frame. */
void layoutUpdate(Registry& registry,
f32 boxLeft, f32 boxBottom, f32 boxRight, f32 boxTop,
bool tsPropertyDirty);
// ---- Hit test pass (defined in UISystem.cpp) ----
/**
* @brief Run ray-vs-content hit-test, updating hitResult. A query: what a
* press or a hover MEANS is the interaction system's, and it is in TS.
* @details UI wins any overlap, topmost first; below it world content ranks
* by distance along the ray, sorting layer breaking a flat scene's
* tie. Without @p resources only inline mesh geometry can be hit.
*/
void hitTestUpdate(Registry& registry, const PickRay& ray,
const resource::ResourceManager* resources = nullptr);
/**
* @brief The same, with a ray per DOMAIN.
*
* @details A pixel is in no domain until it is projected into one, so screen
* UI answers @p screenRay and world content @p worldRay — each
* entity through the projection it is DRAWN with. One ray for both
* draws the HUD where it should be and clicks somewhere else.
*/
void hitTestUpdate(Registry& registry, const PickRay& worldRay, const PickRay& screenRay,
const resource::ResourceManager* resources);
/** @brief Editor pick: the most specific UI entity under the point. Unlike
* hitTestUpdate it ignores Interactable and mutates no state. */
u32 pick(Registry& registry, f32 worldX, f32 worldY);
/** @brief All UI entities under the point, most specific first. Returns the
* count; read entries via pickResult. */
u32 pickAll(Registry& registry, f32 worldX, f32 worldY);
/** @brief Entry `index` of the last pickAll (or INVALID_ENTITY). */
u32 pickResult(u32 index) const {
return index < pickResults_.size() ? pickResults_[index].id() : INVALID_ENTITY.id();
}
/** @brief Entity hit by the most recent hitTestUpdate (or INVALID_ENTITY) */
u32 getHitEntity() const { return hitResult.hit_entity.id(); }
/** @brief Entity hit by the previous frame's hitTestUpdate */
u32 getPrevHitEntity() const { return hitResult.prev_hit_entity.id(); }
/**
* @brief Every entity that belongs to the SCREEN, as opposed to the world.
*
* @details Resolved once at a subtree's root and inherited by all of it: a
* Canvas with no Transform parent IS the screen. The whole Transform
* subtree, not just the laid-out nodes — what decides the domain is
* where a transform composes FROM. Rebuilt by every layout pass.
*/
const std::unordered_set<u32>& screenDomain() const { return screen_domain_; }
bool isScreenDomain(const Registry& registry, u32 entity) const {
// Resolved entries belong to the registry that last completed layout.
return lastRegistryId_ == registry.instanceId()
&& registry.valid(Entity::fromRaw(entity))
&& screen_domain_.count(entity) != 0;
}
private:
struct InheritedState {
bool hidden = false;
f32 alpha = 1.0f;
bool blocked = false;
};
struct InheritedMemo {
u64 stamp = 0;
bool resolving = false;
InheritedState state;
};
std::unordered_map<Entity, InheritedMemo> inherited_cache_;
std::vector<Entity> inherited_path_;
u64 inherited_stamp_ = 0;
void propagateDetachedUIState(Registry& registry);
/** @brief World-space pick for entities outside the layout tree (see .cpp) */
void hitWorldContent(Registry& registry, const PickRay& ray,
const resource::ResourceManager* resources);
std::vector<Entity> pickResults_;
// ---- Layout skip-when-clean gate (see layoutUpdate) ----
// Snapshot of the last solved frame; a pass whose inputs match all of these
// (and no tween activity) reuses the retained YGNodes and computed output.
u64 lastSig_{0};
// Size and center are tracked apart: a resized box needs a new solve, a moved
// box needs only the screen roots replaced (see layoutUpdate).
f32 lastBoxW_{0}, lastBoxH_{0}, lastBoxCX_{0}, lastBoxCY_{0};
bool lastAnimActive_{false};
bool layoutPrimed_{false}; // force a solve on the very first pass
// Which registry the retained Yoga nodes belong to — entity ids restart with
// each one, so they mean nothing across registries (Registry::instanceId).
u64 lastRegistryId_{0};
std::unordered_set<u32> screen_domain_;
};
} // namespace esengine::ecs