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 Canvas.hpp
* @brief Canvas component for 2D game resolution management
* @details Provides Canvas component for defining design resolution,
* pixels-per-unit, and screen scaling behavior.
*
* @author ESEngine Team
* @date 2026
*
* @copyright Copyright (c) 2026 ESEngine Team
* Licensed under the Apache License, Version 2.0.
*/
#pragma once
// =============================================================================
// Includes
// =============================================================================
#include "../../core/Types.hpp"
#include "../../core/Reflection.hpp"
#include "../../math/Math.hpp"
namespace esengine::ecs {
// =============================================================================
// Scale Mode
// =============================================================================
/**
* @brief Canvas scaling mode for different screen resolutions
*/
ES_ENUM()
enum class CanvasScaleMode : u8 {
FixedWidth,
FixedHeight,
Expand,
Shrink,
Match
};
// =============================================================================
// Canvas Component
// =============================================================================
/**
* @brief Canvas component for 2D game resolution management
*
* @details Defines the design resolution and scaling behavior for 2D games.
* The Canvas works with the Camera component to ensure consistent
* rendering across different screen resolutions.
*
* @code
* Entity canvas = registry.create();
* auto& c = registry.emplace<Canvas>(canvas);
* c.designResolution = {1920, 1080};
* c.pixelsPerUnit = 100.0f; // 100 pixels = 1 world unit
* c.scaleMode = CanvasScaleMode::FixedHeight;
* @endcode
*
* Workflow:
* 1. Artist creates assets at design resolution (e.g., 1920x1080)
* 2. World units are design pixels: a 100x200 texture spawns a 100x200 sprite,
* and the default scene camera shows designResolution.y world units of height
* (orthoSize = designResolution.y / 2)
* 3. pixelsPerUnit is the physics scale: world pixels per Box2D meter
* 4. At runtime, scaleMode fits the design resolution to the actual screen
*/
ES_COMPONENT()
struct Canvas {
/** @brief Design resolution in pixels */
ES_PROPERTY()
glm::uvec2 designResolution{1920, 1080};
/** @brief World pixels per physics meter (e.g., 100 means 100px = 1 Box2D meter) */
ES_PROPERTY(min=1, tooltip="World pixels per physics meter (Box2D + tile collider scale).")
f32 pixelsPerUnit{100.0f};
/** @brief Scaling mode for different screen resolutions */
ES_PROPERTY(tooltip="How the canvas adapts the design resolution to the screen.")
CanvasScaleMode scaleMode{CanvasScaleMode::FixedHeight};
/** @brief Match factor for Match scale mode (0 = width, 1 = height) */
ES_PROPERTY(min=0, max=1, slider, tooltip="0 matches width, 1 matches height (Match mode only).")
f32 matchWidthOrHeight{0.5f};
/** @brief Background color for letterbox/pillarbox areas */
ES_PROPERTY()
glm::vec4 backgroundColor{0.0f, 0.0f, 0.0f, 1.0f};
/** @brief Sorting layer this canvas' UI belongs to, for Camera.cullingMask.
* Membership only — UI draw order comes from the tree, not from this. */
ES_PROPERTY(step=1, enum_source=sortingLayers, tooltip="Sorting layer this UI belongs to — cameras cull by it.")
i32 layer{0};
Canvas() = default;
};
} // namespace esengine::ecs