Skip to content

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.

6.8 KB
Raw Blame
// 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