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.

12.1 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    MeshRenderer.hpp
 * @brief   Arbitrary-geometry 2D mesh renderable (deformed sprites, polygons, water
 *          surfaces, procedural shapes).
 * @details Vertices live in component-local space and stream through the unified
 *          Batch face each frame (CPU-transformed like every 2D renderable), so a
 *          mesh participates in sorting, clipping, and multi-texture merging exactly
 *          like a sprite. Geometry is set via meshRenderer_setGeometry (bulk upload with
 *          index validation), not per-field reflection.
 *
 * @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"

#include <vector>

namespace esengine::ecs {

/** @brief One local-space mesh vertex: position, texture coordinate, RGBA8 color. */
struct MeshVertex2D {
    glm::vec2 position{0.0f, 0.0f};
    glm::vec2 uv{0.0f, 0.0f};
    u32 color = 0xFFFFFFFFu;

    bool operator==(const MeshVertex2D&) const = default;
};

// =============================================================================
// MeshRenderer Component
// =============================================================================

ES_COMPONENT(renderable=enabled)
struct MeshRenderer {
    /** @brief Texture sampled by the mesh UVs (invalid = untextured, vertex colors only) */
    ES_PROPERTY(asset = texture)
    resource::TextureHandle texture;

    /** @brief Tangent-space normal map, applied on top of the geometry's own normals.
     *         Needs a mesh that HAS normals; its tangent frame is derived per pixel,
     *         so the geometry carries no tangent channel. */
    ES_PROPERTY(asset = texture, tooltip="Normal map (tangent space). Needs a mesh with normals.")
    resource::TextureHandle normalMap;

    /** @brief Color tint multiplied with per-vertex colors (white = unchanged) */
    ES_PROPERTY(animatable, tooltip="Tint multiplied into the vertex colors (white = unchanged).")
    glm::vec4 color{1.0f, 1.0f, 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 renderables.")
    i32 layer{0};

    /** @brief Drawn as an opaque surface: no blending, and it takes part in depth —
     *         which is what lets one mesh hide another wherever it is nearer, rather
     *         than whichever was submitted last. A glTF's OPAQUE alpha mode. */
    ES_PROPERTY(tooltip="Opaque: no blending; writes and tests depth, so meshes occlude each other.")
    bool opaque{false};

    /** @brief Skip triangles facing away from the camera — a closed model's inside.
     *         A glTF says this with `doubleSided: false`, which is its default. */
    ES_PROPERTY(tooltip="Cull back faces: triangles facing away from the camera are skipped.")
    bool cullBackfaces{false};

    /** @brief Lit by the scene's 2D lights (Light). A custom material overrides this. */
    ES_PROPERTY(tooltip="Receive 2D lights: Light entities light this mesh (flat normal). A custom material overrides this.")
    bool lit{false};

    /** @brief Whether it stands in the light's way: drawn into the shadow maps (and what shelters from rain). A surface light
     *         passes through, like water, says no. */
    ES_PROPERTY(tooltip="Cast shadows: whether this mesh blocks the light. Water and other surfaces light passes through say no.")
    bool castShadows{true};

    /** @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 mesh 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 Geometry from an .esmesh, drawn INSTEAD of the inline vertices.
     * @details The difference is where the vertices live: the inline payload is
     *          rewritten into every frame, which is a re-upload of anything that
     *          does not change every frame.
     */
    ES_PROPERTY(asset = mesh)
    resource::MeshHandle mesh;

    // -------------------------------------------------------------------------
    // Geometry payload — set via meshRenderer_setGeometry, streamed by MeshPlugin.
    // Deliberately un-annotated: variable-size data has no fixed ABI offset, so it
    // stays out of the EHT reflection/pointer layout (all annotated fields above
    // keep their asserted offsets because these members come last).
    // -------------------------------------------------------------------------

    /** @brief Local-space vertices (triangle list, indexed). */
    std::vector<MeshVertex2D> vertices;

    /** @brief Triangle-list indices into @ref vertices (validated on upload). */
    std::vector<u32> indices;

    /** @brief Local-space AABB of @ref vertices, recomputed on upload — cull source. */
    glm::vec2 localMin{0.0f, 0.0f};
    glm::vec2 localMax{0.0f, 0.0f};

    MeshRenderer() = default;

    /// Compared member by member: what the change audit checks a write of this component against (Registry::auditChanges).
    bool operator==(const MeshRenderer&) const = default;
};

// =============================================================================
// MeshSkin Component
// =============================================================================

/**
 * @brief What deforms a @ref MeshRenderer: the entities its Joints channel indexes.
 *
 * @details Its own component because MeshRenderer says WHAT is drawn and this says
 *          what moves it; entry i drives joint i of the mesh's own bind
 *          matrices. A skinned mesh's own transform is ignored (glTF requires
 *          it) — the joints are placed in the world, so the vertices are too.
 */
ES_COMPONENT()
struct MeshSkin {
    /** @brief Joint entities, in the order the mesh's bind matrices are stored. */
    ES_PROPERTY(entity_ref, tooltip="Joint entities, in the order the mesh's bind matrices are in.")
    std::vector<Entity> joints;

    MeshSkin() = default;

    /// Compared member by member: what the change audit checks a write of this component against (Registry::auditChanges).
    bool operator==(const MeshSkin&) const = default;
};

// =============================================================================
// MeshMorph Component
// =============================================================================

/**
 * @brief What SHAPE a @ref MeshRenderer is in: how far it is blended towards each
 *        of the shapes its mesh carries.
 *
 * @details The third of the trio, for the reason the second exists: MeshRenderer
 *          says what is drawn and MeshSkin what moves it. Entry i weights target
 *          i — positional, because a name lives with the geometry.
 */
ES_COMPONENT()
struct MeshMorph {
    /** @brief Weight per target, 0 leaving the mesh as authored. Not clamped: a
     *         negative weight and one past 1 are both shapes an author may want,
     *         and glTF states neither bound. */
    ES_PROPERTY(animatable, label_source=meshMorphTargets,
                tooltip="Weight per morph target of the mesh, in the order the mesh carries them.")
    std::vector<f32> weights;

    MeshMorph() = default;
};

// =============================================================================
// MeshInstances Component
// =============================================================================

/**
 * @brief Many placements of the one mesh a @ref MeshRenderer draws, as ONE renderable.
 *
 * @details The mesh stays one and resident; this holds where each copy stands. The collect culls each copy against the view, picks its mesh by
 *          its distance from the eye and writes the survivors as the instances of one draw per mesh. The entity's Transform places the whole
 *          set: an instance is relative to it.
 */
ES_COMPONENT()
struct MeshInstances {
    /** @brief The cheaper mesh that stands in past @ref lodDistance; invalid = the mesh itself at every distance. It
     *         must carry the same channels as the entity's mesh, or it is not used. */
    ES_PROPERTY(asset = mesh, tooltip="The cheaper mesh used past the LOD distance. Needs the same channels as the mesh.")
    resource::MeshHandle lod1Mesh;

    /** @brief Metres from the eye past which @ref lod1Mesh is drawn; 0 = never. */
    ES_PROPERTY(tooltip="Distance (metres) past which the cheaper mesh is used. 0 = never.")
    f32 lodDistance{0.0f};

    /** @brief Metres from the eye BEFORE which an instance is not drawn; 0 = from the eye outward. A far version of a plant is a set
     *         with this at the distance the near one ends, so the two hand over per instance without anything choosing between them. */
    ES_PROPERTY(tooltip="Distance (metres) nearer than which an instance is not drawn. 0 = from the eye.")
    f32 minDistance{0.0f};

    /** @brief Metres from the eye past which an instance is not drawn; 0 = at any distance. A shadow map is cut by the
     *         distance from the CAMERA, not from the light, so a caster too far to be seen does not cast. */
    ES_PROPERTY(tooltip="Distance (metres) past which an instance is not drawn. 0 = unlimited.")
    f32 drawDistance{0.0f};

    /** @brief Metres from the eye past which an instance casts no shadow; 0 = as far as it is drawn. A tree far off still draws, but the
     *         shadow it casts is too small to be worth drawing it again into every shadow map. */
    ES_PROPERTY(tooltip="Distance (metres) past which an instance casts no shadow. 0 = as far as it is drawn.")
    f32 shadowDistance{0.0f};

    /** @brief Sixteen floats an instance: the model's three rows (translation in .w) then its tint RGBA, which is
     *         multiplied into the renderer's colour. Set by meshInstances_set, not by reflection. */
    std::vector<f32> transforms;

    /** @brief The corners of the instances' ORIGINS and the greatest scale among them: with the mesh's own reach, what
     *         bounds the set. Recomputed on upload. */
    glm::vec3 originMin{0.0f};
    glm::vec3 originMax{0.0f};
    f32 maxScale{1.0f};

    MeshInstances() = default;
};

// =============================================================================
// MeshLightmap Component
// =============================================================================

/**
 * @brief Where a @ref MeshRenderer's BAKED light comes from: the atlas, and the
 *        rectangle of it this object occupies.
 *
 * @details Per ENTITY and not part of the mesh because of the rectangle: one mesh
 *          placed twice is lit twice, in two patches of one atlas. Needs a mesh
 *          carrying TexCoord1 — one without draws as before.
 */
ES_COMPONENT()
struct MeshLightmap {
    /** @brief The baked atlas. Invalid = this object has no bake, which is not
     *         the same as a black one: it keeps the light it gets in real time. */
    ES_PROPERTY(asset = texture, tooltip="Baked lightmap atlas. Needs a mesh with a second UV set.")
    resource::TextureHandle lightmap;

    /** @brief Where in the atlas: xy scales the mesh's second UV, zw offsets it.
     *         (1,1,0,0) reads the whole texture, which is what a bake of a single
     *         object produces. */
    ES_PROPERTY(advanced, tooltip="Atlas rectangle: xy scales the second UV set, zw offsets it.")
    glm::vec4 scaleOffset{1.0f, 1.0f, 0.0f, 0.0f};

    MeshLightmap() = default;
};

}  // namespace esengine::ecs