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 Sprite.hpp
* @brief 2D sprite rendering component
* @details Provides Sprite component for 2D rendering with texture handles.
*
* @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"
#include "../../resource/Handle.hpp"
namespace esengine::ecs {
// =============================================================================
// Sprite Component
// =============================================================================
/**
* @brief How a Sprite fills its box.
*
* @details Auto infers it: tileSize decides tiling, the texture's slice border
* decides 9-slice. The other three are the author overriding that, and
* an override cannot invent data — Tiled with no tileSize and NineSlice
* with no border both draw the plain quad.
*/
/* Public because a public component names it: `Sprite.drawMode` is @public, and a
frozen field whose TYPE can still change is a promise with a hole in it. The
set may still grow — api-surface counts a union gaining a member as a note. */
ES_ENUM(stability=public)
enum class SpriteDrawMode : u8 {
Auto,
Simple,
Tiled,
NineSlice
};
/**
* @brief 2D sprite component for rendering
*
* @details Contains all data needed to render a 2D sprite including
* texture handle, color tint, size, UV coordinates, and
* sorting layer.
*
* @code
* Entity e = registry.create();
* auto& sprite = registry.emplace<Sprite>(e);
* sprite.texture = resourceManager.loadTexture("player.png");
* sprite.color = glm::vec4(1.0f, 0.5f, 0.5f, 1.0f); // Red tint
* sprite.layer = 10; // Render on top
* @endcode
*/
/**
* @brief What a `SpriteMask` reaching this sprite does to it.
* @details Opt-in per sprite: a mask cuts only what asks to be cut, so adding a mask to a
* scene cannot make unrelated sprites vanish.
*/
ES_ENUM(stability=public)
enum class SpriteMaskInteraction : i32 {
None = 0, ///< Masks reaching this sprite are ignored.
VisibleInside = 1, ///< Drawn only where the mask is — a window.
VisibleOutside = 2, ///< Drawn only where the mask is NOT — a hole.
};
ES_COMPONENT(renderable=enabled, stability=public)
struct Sprite {
/** @brief Texture resource handle (type-safe) */
ES_PROPERTY(asset = texture)
resource::TextureHandle texture;
/** @brief Color tint (RGBA, 0-1 range) */
ES_PROPERTY(animatable, tooltip="Tint multiplied into the texture (white = unchanged).")
glm::vec4 color{1.0f, 1.0f, 1.0f, 1.0f};
/** @brief Sprite size in world units ({1,1} at runtime; authored at 100px) */
ES_PROPERTY(animatable, editor_default={100, 100})
glm::vec2 size{1.0f, 1.0f};
/** @brief Pivot point (0,0 = bottom-left, 0.5,0.5 = center, 1,1 = top-right) */
ES_PROPERTY(normalized_of=size, tooltip="Anchor point the sprite rotates and scales about, as a fraction of its size (0.5,0.5 = centre). Values outside 0–1 sit off the sprite.")
glm::vec2 pivot{0.5f, 0.5f};
/** @brief UV coordinate offset for sprite sheets */
ES_PROPERTY(advanced)
glm::vec2 uvOffset{0.0f, 0.0f};
/** @brief UV coordinate scale for sprite sheets */
ES_PROPERTY(advanced)
glm::vec2 uvScale{1.0f, 1.0f};
/** @brief Sorting layer (higher = rendered on top) */
ES_PROPERTY(step=1, enum_source=sortingLayers, tooltip="Sorting layer — controls draw order across sprites.")
i32 layer{0};
/** @brief Order WITHIN the sorting layer; higher draws on top. The explicit answer
* that overrides whatever the layer infers — Y-sort, or depth from z — and
* the only one a Y-sorted layer has. Range -128..127 (clamped). */
ES_PROPERTY(step=1, min=-128, max=127, optional, tooltip="Draw order inside the sorting layer — higher draws on top. Overrides the layer's Y-sort or depth ordering; leave 0 to keep it.")
i32 order{0};
/** @brief What a SpriteMask drawn before this sprite does to it. Opt-in, so a mask
* added to a scene cannot make an unrelated sprite disappear. */
ES_PROPERTY(enum=SpriteMaskInteraction, optional,
tooltip="Whether a SpriteMask drawn before this sprite clips it, and which side survives.")
i32 maskInteraction{0};
/** @brief Lit by the scene's 2D lights (Light), no material needed. Off = unlit. */
ES_PROPERTY(tooltip="Receive 2D lights: Light entities light this sprite (flat normal). A custom material overrides this.")
bool lit{false};
/** @brief Flip sprite horizontally */
ES_PROPERTY()
bool flipX{false};
/** @brief Flip sprite vertically */
ES_PROPERTY()
bool flipY{false};
/** @brief How this sprite fills its box; Auto infers it from tileSize and the
* texture's slice border. */
ES_PROPERTY(optional,
tooltip="Draw mode: Auto infers from tile size and the texture's 9-slice border; the others override it.")
SpriteDrawMode drawMode{SpriteDrawMode::Auto};
/** @brief Tile size in world units for tiling mode ({0,0} = no tiling) */
ES_PROPERTY(advanced)
glm::vec2 tileSize{0.0f, 0.0f};
/** @brief Spacing between tiles in world units ({0,0} = seamless) */
ES_PROPERTY(advanced)
glm::vec2 tileSpacing{0.0f, 0.0f};
/** @brief Parallax scroll factor per axis. 1 = moves with the world (default, no
* parallax); <1 = scrolls slower than the camera (appears farther, e.g. a
* background); 0 = locked to the camera (e.g. a sky). The renderer offsets
* the sprite by camera_center * (1 - factor). */
ES_PROPERTY(advanced, tooltip="Parallax scroll factor (1 = with world, <1 = slower, 0 = locked to camera).")
glm::vec2 parallax{1.0f, 1.0f};
/** @brief Custom material ID (0 = use default batch shader) */
ES_PROPERTY(asset = material, advanced)
u32 material{0};
ES_PROPERTY()
bool enabled{true};
/** @brief Default constructor (white, no texture) */
Sprite() = default;
/**
* @brief Constructs sprite with texture handle
* @param tex Texture resource handle
*/
explicit Sprite(resource::TextureHandle tex) : texture(tex) {}
/**
* @brief Constructs sprite with texture and color tint
* @param tex Texture resource handle
* @param col Color tint
*/
Sprite(resource::TextureHandle tex, const glm::vec4& col)
: texture(tex), color(col) {}
};
} // namespace esengine::ecs