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.

17.4 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
#ifdef ES_ENABLE_TILEMAP

#include "TilemapBindings.hpp"

#include "ActiveContext.hpp"
#include "BoundarySpan.hpp"
#include "../tilemap/TilemapSystem.hpp"
#include "../tilemap/ChunkBlob.hpp"
#include "../renderer/frame/RenderContext.hpp"
#include "../renderer/frame/RenderFrame.hpp"
#include "../renderer/draw/ImmediateDraw.hpp"
#include "../renderer/draw/CustomGeometry.hpp"
#include "../renderer/frame/PostProcessPipeline.hpp"
#include "../resource/ResourceManager.hpp"
#include "../ecs/TransformSystem.hpp"

#include <cstring>
#include <string>
#include <utility>
#include <vector>

namespace esengine {

static EstellaContext& ctx() { return activeCtx(); }

static tilemap::TilemapSystem& getTilemapSystem() {
    return ctx().require<tilemap::TilemapSystem>();
}

void tilemap_initLayer(u32 entity, u32 width, u32 height,
                       f32 tileWidth, f32 tileHeight) {
    auto e = Entity::fromRaw(entity);
    if (e == INVALID_ENTITY) return;
    getTilemapSystem().initLayer(e, width, height, tileWidth, tileHeight);
}

void tilemap_initInfinite(u32 entity, f32 tileWidth, f32 tileHeight) {
    auto e = Entity::fromRaw(entity);
    if (e == INVALID_ENTITY) return;
    // Idempotent for the chunk store, but always reconcile the tile size: the scene
    // loader's importChunks auto-creates the layer with a placeholder size before the
    // sync knows the component's cellSize, and the renderer derives UVs from tile_width.
    if (auto* layer = getTilemapSystem().getLayerDataMut(e)) {
        layer->tile_width = tileWidth;
        layer->tile_height = tileHeight;
        layer->infinite = true;
        return;
    }
    getTilemapSystem().initInfiniteLayer(e, tileWidth, tileHeight);
}

void tilemap_destroyLayer(u32 entity) {
    auto e = Entity::fromRaw(entity);
    if (e == INVALID_ENTITY) return;
    getTilemapSystem().destroyLayer(e);
}

void tilemap_setTile(u32 entity, i32 x, i32 y, u32 tileId) {
    auto e = Entity::fromRaw(entity);
    if (e == INVALID_ENTITY || !getTilemapSystem().hasLayer(e)) return;
    getTilemapSystem().setTile(e, x, y, static_cast<u16>(tileId));
}

u32 tilemap_getTile(u32 entity, i32 x, i32 y) {
    auto e = Entity::fromRaw(entity);
    if (e == INVALID_ENTITY || !getTilemapSystem().hasLayer(e)) return 0;
    return getTilemapSystem().getTile(e, x, y);
}

void tilemap_fillRect(u32 entity, i32 x, i32 y,
                      u32 w, u32 h, u32 tileId) {
    auto e = Entity::fromRaw(entity);
    if (e == INVALID_ENTITY || !getTilemapSystem().hasLayer(e)) return;
    getTilemapSystem().fillRect(e, x, y, w, h, static_cast<u16>(tileId));
}

void tilemap_setTiles(u32 entity, uintptr_t tilesPtr, u32 count) {
    auto e = Entity::fromRaw(entity);
    if (e == INVALID_ENTITY || !getTilemapSystem().hasLayer(e)) return;
    const auto* tiles = boundarySpan<u16>(tilesPtr, count, "tilemap_setTiles");
    if (!tiles) return;
    getTilemapSystem().setTiles(e, tiles, count);
}

// Multi-tileset table: `count` slots, each SLOT_STRIDE packed u32
// [first_id, textureHandle, columns, margin, spacing, extrude].
// Empty table reverts the layer to its single tileset.
void tilemap_setTilesets(u32 entity, uintptr_t dataPtr, u32 count) {
    // The SDK's TILESET_SLOT_STRIDE. No generator spans this boundary, so the
    // field list above is the contract and this number is the other half of it.
    constexpr u32 SLOT_STRIDE = 6;
    auto e = Entity::fromRaw(entity);
    if (e == INVALID_ENTITY || !getTilemapSystem().hasLayer(e)) return;
    const auto* d = count
        ? boundarySpan<u32>(dataPtr, static_cast<u64>(count) * SLOT_STRIDE, "tilemap_setTilesets")
        : nullptr;
    if (count && !d) return;
    std::vector<tilemap::TilesetSlot> slots;
    slots.reserve(count);
    for (u32 i = 0; i < count; ++i) {
        tilemap::TilesetSlot slot;
        slot.first_id = static_cast<u16>(d[i * SLOT_STRIDE + 0]);
        slot.texture_handle = d[i * SLOT_STRIDE + 1];
        slot.columns = d[i * SLOT_STRIDE + 2];
        slot.margin = d[i * SLOT_STRIDE + 3];
        slot.spacing = d[i * SLOT_STRIDE + 4];
        slot.extrude = d[i * SLOT_STRIDE + 5];
        slots.push_back(slot);
    }
    getTilemapSystem().setTilesets(e, std::move(slots));
}

bool tilemap_hasLayer(u32 entity) {
    return getTilemapSystem().hasLayer(Entity::fromRaw(entity));
}

u32 tilemap_getEditRevision(u32 entity) {
    const auto* layer = getTilemapSystem().getLayerData(Entity::fromRaw(entity));
    return layer ? layer->edit_revision : 0;
}

u32 tilemap_getGeneration(u32 entity) {
    const auto* layer = getTilemapSystem().getLayerData(Entity::fromRaw(entity));
    return layer ? layer->generation : 0;
}

u32 tilemap_readChunkIndex(u32 entity, uintptr_t rowsPtr, u32 capacity) {
    const auto* layer = getTilemapSystem().getLayerData(Entity::fromRaw(entity));
    const u32 count = layer ? static_cast<u32>(layer->chunks.size()) : 0;
    if (count == 0 || capacity < count) return count;
    auto* out = boundarySpanMut<u8>(rowsPtr, static_cast<u64>(count) * 3 * sizeof(u32), "tilemap_readChunkIndex");
    if (!out) return 0;
    for (const auto& [coord, chunk] : layer->chunks) {
        std::memcpy(out, &coord.x, sizeof(i32));
        std::memcpy(out + sizeof(u32), &coord.y, sizeof(i32));
        std::memcpy(out + 2 * sizeof(u32), &chunk.revision, sizeof(u32));
        out += 3 * sizeof(u32);
    }
    return count;
}

bool tilemap_readChunkTiles(u32 entity, i32 chunkX, i32 chunkY, uintptr_t tilesPtr, u32 capacity) {
    constexpr u32 cells = tilemap::CHUNK_SIZE * tilemap::CHUNK_SIZE;
    if (capacity < cells) return false;
    const auto* layer = getTilemapSystem().getLayerData(Entity::fromRaw(entity));
    if (!layer) return false;
    const auto found = layer->chunks.find({chunkX, chunkY});
    if (found == layer->chunks.end()) return false;
    auto* out = boundarySpanMut<u8>(tilesPtr, cells * sizeof(u16), "tilemap_readChunkTiles");
    if (!out) return false;
    std::memcpy(out, found->second.tiles, cells * sizeof(u16));
    return true;
}

void tilemap_setRenderProps(u32 entity, u32 textureHandle, u32 tilesetColumns,
                            f32 uvTileW, f32 uvTileH,
                            i32 sortLayer, f32 depth,
                            f32 parallaxX, f32 parallaxY) {
    getTilemapSystem().setRenderProps(Entity::fromRaw(entity),
        textureHandle, tilesetColumns, uvTileW, uvTileH,
        sortLayer, depth, parallaxX, parallaxY);
}

void tilemap_setTint(u32 entity, f32 r, f32 g, f32 b, f32 a, f32 opacity) {
    getTilemapSystem().setTint(Entity::fromRaw(entity), r, g, b, a, opacity);
}

void tilemap_setVisible(u32 entity, bool visible) {
    getTilemapSystem().setVisible(Entity::fromRaw(entity), visible);
}

void tilemap_setOriginEntity(u32 layerKey, u32 originEntity) {
    getTilemapSystem().setOriginEntity(Entity::fromRaw(layerKey),
                                    Entity::fromRaw(originEntity));
}

// --- Chunk serialization ---

namespace {

// Base64 encoding uses the URL-safe alphabet (`-` / `_` instead of `+` / `/`)
// so the output embeds cleanly in JSON scene files without escaping and can
// also survive a ?query= parameter if anyone ever serves scenes over HTTP.
constexpr const char* kB64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";

void base64Encode(const u8* data, usize len, std::string& out) {
    out.reserve(out.size() + ((len + 2) / 3) * 4);
    usize i = 0;
    while (i + 3 <= len) {
        const u32 v = (u32(data[i]) << 16) | (u32(data[i + 1]) << 8) | u32(data[i + 2]);
        out.push_back(kB64[(v >> 18) & 0x3F]);
        out.push_back(kB64[(v >> 12) & 0x3F]);
        out.push_back(kB64[(v >> 6) & 0x3F]);
        out.push_back(kB64[v & 0x3F]);
        i += 3;
    }
    if (i < len) {
        const u32 v = (u32(data[i]) << 16) | (i + 1 < len ? (u32(data[i + 1]) << 8) : 0);
        out.push_back(kB64[(v >> 18) & 0x3F]);
        out.push_back(kB64[(v >> 12) & 0x3F]);
        if (i + 1 < len) {
            out.push_back(kB64[(v >> 6) & 0x3F]);
        } else {
            out.push_back('=');
        }
        out.push_back('=');
    }
}

i32 b64Value(char c) {
    if (c >= 'A' && c <= 'Z') return c - 'A';
    if (c >= 'a' && c <= 'z') return c - 'a' + 26;
    if (c >= '0' && c <= '9') return c - '0' + 52;
    if (c == '-' || c == '+') return 62;
    if (c == '_' || c == '/') return 63;
    return -1;
}

bool base64Decode(const std::string& in, std::vector<u8>& out) {
    out.clear();
    out.reserve(in.size() * 3 / 4);
    i32 buf = 0;
    i32 bits = 0;
    for (char c : in) {
        if (c == '=' || c == '\n' || c == '\r' || c == ' ') continue;
        const i32 v = b64Value(c);
        if (v < 0) return false;
        buf = (buf << 6) | v;
        bits += 6;
        if (bits >= 8) {
            bits -= 8;
            out.push_back(static_cast<u8>((buf >> bits) & 0xFF));
        }
    }
    return true;
}

}  // namespace

// Exports every non-empty chunk of `entity` as a single base64-encoded
// blob. Layout (all little-endian):
//   u32 magic = 'TMAP'
//   u16 chunkSize, idMask, flipH, flipV, flipD, reserved(0)
//   u32 chunkCount
//   repeated for each chunk:
//     i32 chunkX, i32 chunkY
//     u16 tiles[chunkSize * chunkSize]
// Empty chunks are skipped to keep the payload compact for sparse maps.
std::string tilemap_exportChunks(u32 entity) {
    auto e = Entity::fromRaw(entity);
    const auto* layer = getTilemapSystem().getLayerData(e);
    if (!layer) return {};

    std::vector<std::pair<tilemap::ChunkCoord, const tilemap::ChunkData*>> nonEmpty;
    nonEmpty.reserve(layer->chunks.size());
    for (const auto& [coord, chunk] : layer->chunks) {
        bool anyTile = false;
        for (u32 i = 0; i < tilemap::CHUNK_SIZE * tilemap::CHUNK_SIZE; ++i) {
            if (chunk.tiles[i] != tilemap::EMPTY_TILE) { anyTile = true; break; }
        }
        if (anyTile) nonEmpty.emplace_back(coord, &chunk);
    }

    const u32 count = static_cast<u32>(nonEmpty.size());
    const usize perChunk = sizeof(i32) * 2
        + tilemap::CHUNK_SIZE * tilemap::CHUNK_SIZE * sizeof(u16);
    std::vector<u8> raw;
    raw.reserve(tilemap::BLOB_HEADER_V2_BYTES + count * perChunk);

    auto append = [&](const void* p, usize n) {
        const u8* b = static_cast<const u8*>(p);
        raw.insert(raw.end(), b, b + n);
    };
    tilemap::appendBlobHeader(raw, count);
    for (const auto& [coord, chunk] : nonEmpty) {
        append(&coord.x, sizeof(coord.x));
        append(&coord.y, sizeof(coord.y));
        append(chunk->tiles, sizeof(chunk->tiles));
    }

    std::string out;
    base64Encode(raw.data(), raw.size(), out);
    return out;
}

bool tilemap_importChunks(u32 entity, const std::string& encoded) {
    auto e = Entity::fromRaw(entity);
    // Auto-init as infinite if the caller didn't pre-create a layer — the
    // scene loader path inserts the TilemapLayer component first and then
    // expects the chunks to land, so we can't require a separate init call.
    if (!getTilemapSystem().hasLayer(e)) {
        getTilemapSystem().initInfiniteLayer(e, 32.0f, 32.0f);
    }
    auto* layer = getTilemapSystem().getLayerDataMut(e);
    if (!layer) return false;

    std::vector<u8> raw;
    if (!base64Decode(encoded, raw)) return false;

    tilemap::BlobHeader header{};
    if (!tilemap::parseBlobHeader(raw.data(), raw.size(), header)) return false;

    // One path, migrating or not: a map written under this engine's own
    // encoding takes the same walk as one written under an older one, so the
    // case that runs every day is the case the migration is tested on.
    const tilemap::CellEncoding running = tilemap::runningEncoding();
    const i32 side = static_cast<i32>(tilemap::CHUNK_SIZE);
    tilemap::ChunkData* into = nullptr;
    tilemap::ChunkCoord at{ 0, 0 };
    bool first = true;
    bool lost = false;

    if (!layer->chunks.empty()) ++layer->edit_revision;
    layer->chunks.clear();
    const bool walked = tilemap::walkBlobCells(raw.data(), raw.size(), header,
        [&](i32 x, i32 y, u16 word) {
            u16 cell = 0;
            // A narrowed id mask cannot carry the tile, and putting SOME other
            // tile there is the failure this whole header exists to stop.
            if (!tilemap::recodeCell(word, header.wrote, running, cell)) { lost = true; return; }
            const tilemap::ChunkCoord coord{ tilemap::floorDiv(x, side), tilemap::floorDiv(y, side) };
            // Cells arrive along a row, so the chunk they land in changes rarely.
            if (first || coord.x != at.x || coord.y != at.y) {
                auto& chunk = layer->chunks[coord];
                chunk.revision = ++layer->edit_revision;
                into = &chunk;
                at = coord;
                first = false;
            }
            into->tiles[static_cast<usize>(tilemap::floorMod(y, side)) * tilemap::CHUNK_SIZE
                + static_cast<usize>(tilemap::floorMod(x, side))] = cell;
        });
    if (!walked || lost) {
        layer->chunks.clear();
        return false;
    }
    return true;
}

void tilemap_initInfiniteLayer(u32 entity, f32 tileWidth, f32 tileHeight) {
    auto e = Entity::fromRaw(entity);
    if (e == INVALID_ENTITY) return;
    getTilemapSystem().initInfiniteLayer(e, tileWidth, tileHeight);
}

void tilemap_setChunkTiles(u32 entity, i32 chunkX, i32 chunkY,
                            uintptr_t tilesPtr, u32 width, u32 height) {
    auto e = Entity::fromRaw(entity);
    if (e == INVALID_ENTITY || !getTilemapSystem().hasLayer(e)) return;
    const auto* tiles = boundarySpan<u16>(tilesPtr, static_cast<u64>(width) * height, "tilemap_setChunkTiles");
    if (!tiles) return;
    getTilemapSystem().setChunkTiles(e, chunkX, chunkY, tiles, width, height);
}

void tilemap_removeChunk(u32 entity, i32 chunkX, i32 chunkY) {
    auto e = Entity::fromRaw(entity);
    if (e == INVALID_ENTITY || !getTilemapSystem().hasLayer(e)) return;
    getTilemapSystem().removeChunk(e, chunkX, chunkY);
}

void tilemap_setTileAnimation(u32 entity, u32 tileId,
                               uintptr_t framesPtr, u32 frameCount) {
    auto e = Entity::fromRaw(entity);
    if (e == INVALID_ENTITY || !getTilemapSystem().hasLayer(e)) return;
    const auto* data = boundarySpan<u32>(framesPtr, static_cast<u64>(frameCount) * 2, "tilemap_setTileAnimation");
    if (!data) return;
    std::vector<tilemap::AnimFrame> frames(frameCount);
    for (u32 i = 0; i < frameCount; i++) {
        frames[i].tile_id = static_cast<u16>(data[i * 2]);
        frames[i].duration_ms = static_cast<u16>(data[i * 2 + 1]);
    }
    getTilemapSystem().setTileAnimation(e, static_cast<u16>(tileId),
                                     frames.data(), frameCount);
}

void tilemap_clearTileAnimations(u32 entity) {
    auto e = Entity::fromRaw(entity);
    if (e == INVALID_ENTITY || !getTilemapSystem().hasLayer(e)) return;
    getTilemapSystem().clearTileAnimations(e);
}

void tilemap_advanceAnimations(u32 entity, f32 dtMs) {
    auto e = Entity::fromRaw(entity);
    if (e == INVALID_ENTITY) return;
    getTilemapSystem().advanceAnimations(e, dtMs);
}

void tilemap_setTileProperty(u32 entity, u32 tileId,
                              const std::string& key, const std::string& value) {
    auto e = Entity::fromRaw(entity);
    if (e == INVALID_ENTITY || !getTilemapSystem().hasLayer(e)) return;
    getTilemapSystem().setTileProperty(e, static_cast<u16>(tileId), key, value);
}

std::string tilemap_getTileProperty(u32 entity, i32 x, i32 y,
                                     const std::string& key) {
    auto e = Entity::fromRaw(entity);
    if (e == INVALID_ENTITY || !getTilemapSystem().hasLayer(e)) return "";
    u16 raw = getTilemapSystem().getTile(e, x, y);
    u16 tileId = raw & tilemap::TILE_ID_MASK;
    if (tileId == tilemap::EMPTY_TILE) return "";
    return getTilemapSystem().getTileProperty(e, tileId, key);
}

void tilemap_flipTile(u32 entity, i32 x, i32 y,
                       bool flipH, bool flipV, bool flipD) {
    auto e = Entity::fromRaw(entity);
    if (e == INVALID_ENTITY) return;
    getTilemapSystem().flipTile(e, x, y, flipH, flipV, flipD);
}

void tilemap_rotateTile(u32 entity, i32 x, i32 y, i32 degrees) {
    auto e = Entity::fromRaw(entity);
    if (e == INVALID_ENTITY) return;
    getTilemapSystem().rotateTile(e, x, y, degrees);
}

void tilemap_setGridType(u32 entity, u32 type) {
    auto e = Entity::fromRaw(entity);
    if (e == INVALID_ENTITY) return;
    getTilemapSystem().setGridType(e, static_cast<tilemap::GridType>(type));
}

void tilemap_setHexParams(u32 entity, f32 sideLength, u32 staggerAxisX, u32 staggerIndexEven) {
    auto e = Entity::fromRaw(entity);
    if (e == INVALID_ENTITY) return;
    getTilemapSystem().setHexParams(e, sideLength, staggerAxisX != 0, staggerIndexEven != 0);
}

static f32 s_coordBuffer[2] = {};

uintptr_t tilemap_tileToWorld(u32 entity, i32 tx, i32 ty,
                               f32 originX, f32 originY) {
    auto e = Entity::fromRaw(entity);
    getTilemapSystem().tileToWorld(e, tx, ty, originX, originY,
                                s_coordBuffer[0], s_coordBuffer[1]);
    return reinterpret_cast<uintptr_t>(s_coordBuffer);
}

uintptr_t tilemap_worldToTile(u32 entity, f32 wx, f32 wy,
                               f32 originX, f32 originY) {
    auto e = Entity::fromRaw(entity);
    i32 tx, ty;
    getTilemapSystem().worldToTile(e, wx, wy, originX, originY, tx, ty);
    s_coordBuffer[0] = static_cast<f32>(tx);
    s_coordBuffer[1] = static_cast<f32>(ty);
    return reinterpret_cast<uintptr_t>(s_coordBuffer);
}

}  // namespace esengine

#endif  // ES_ENABLE_TILEMAP