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 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