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.8 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    AotHost.hpp
 * @brief   The host half of the Estella ABI.
 *
 * @details A compiled system calls the engine ZERO times, which means everything
 *          it reads has to be in memory before the call. This puts it there:
 *          pack the rows, resolve the resource addresses, zero the count, fill
 *          the SysCtx, call, and hand back what the system wrote.
 *
 *          It does not know about Registry. A component is reached through a
 *          resolver the caller supplies, because the caller is where the
 *          component's TYPE is known — and that is also what lets this be tested
 *          without linking the engine.
 *
 *          The arena is reused across calls and rebuilt in each one, because
 *          a row array has a one-call lifetime. Nothing here allocates per row
 *          after the first frame at a given size.
 *
 *          A row table is a function of two things: which entities match, and
 *          where their components are. {@link narrowest} answers the first;
 *          {@link WorldStamp} answers the second, and when neither moved last
 *          frame's rows are this frame's. Same model as the web road
 *          (sdk/src/ecs/aot/AotDispatch.ts), reached through different doors.
 */
#pragma once

#include <cstddef>
#include <cstdint>
#include <functional>
#include <optional>
#include <span>
#include <utility>
#include <vector>

#include "estella_abi.h"

namespace esengine::aot {

/** What a compiled system is: one exported symbol, taking the ctx. */
using SystemFn = void (*)(es_addr_t);

/**
 * Where one component's bytes are for an entity, or `nullptr` if it has none.
 * Supplied per component by the layer that knows its type — a generated binding,
 * or a test.
 */
using ComponentAt = std::function<void*(std::uint32_t)>;

/**
 * Which entities a component's storage says it holds, as raw ids.
 *
 * Empty means nobody has it and the query matches nothing; `nullopt` means this
 * host cannot enumerate that column and the caller must WIDEN, not narrow.
 * Reading the second as the first drops every row.
 */
using Candidates = std::optional<std::span<const std::uint32_t>>;

/** A column's members, asked per call because a pool grows between them. */
using CandidatesOf = std::function<Candidates()>;

/**
 * Whether any stored component MOVED — one number over every pool's version.
 *
 * `known` false means nobody could say, and then a held address must be
 * re-resolved: trusting one because nothing could tell us it moved is how a
 * compiled system reads somebody else's bytes.
 */
struct WorldStamp {
    double at = 0.0;
    bool known = false;

    /** Same world, and both sides sure of it. Unknown never equals anything. */
    bool operator==(const WorldStamp& o) const { return known && o.known && at == o.at; }
};

/** One declared `Query`: its components, in the order the query names them. */
struct QuerySpec {
    std::vector<ComponentAt> comps;
    /**
     * Where each of those components says its members are, in the same order.
     * Empty, or an entry that answers nullopt, simply does not narrow — a
     * resolver is required to run a query and this is not.
     */
    std::vector<CandidatesOf> sources;
};

/**
 * The shortest column this query names, or nullopt when none of them could say.
 *
 * An entity missing any one component cannot match, so any column bounds the
 * answer and the shortest bounds it best — {@link ecs::View}'s strategy, reached
 * through names. `run` still filters; this only decides what it is paid over.
 */
inline Candidates narrowest(const QuerySpec& spec) {
    Candidates best;
    for (const CandidatesOf& source : spec.sources) {
        if (!source) continue;
        const Candidates got = source();
        if (!got) continue;
        if (!best || got->size() < best->size()) best = got;
    }
    return best;
}

/**
 * Whether every one of these queries can narrow itself — that is, whether the
 * caller can skip enumerating the world. Asked before it does. No queries at all
 * answers true: nothing would walk the list.
 */
inline bool narrows(std::span<const QuerySpec> queries) {
    for (const QuerySpec& q : queries) {
        if (!narrowest(q)) return false;
    }
    return true;
}

struct BoundSystem;
using ResourceLookup = std::function<void*(const char*)>;

/**
 * The scratch a call needs. Held by the caller so the vectors keep their
 * capacity between frames; every `run` overwrites it and nothing survives.
 */
class CallArena {
public:
    explicit CallArena(std::uint32_t cmdCap = 256) : cmds_(cmdCap) {}

    /** How many command records the system may write before it must stop. */
    std::uint32_t commandCapacity() const { return static_cast<std::uint32_t>(cmds_.size()); }

    /**
     * Entities the last `run` covered, summed across its queries.
     *
     * The query's BREADTH, counted whether or not the rows were repacked — it is
     * what a system would be paid over, and a ceiling on it is what says the
     * dispatcher is not scanning the world (bench/aot-native/frame-bench.mjs).
     */
    std::uint32_t candidatesWalked() const { return walked_; }

    /** Rows the last `run` actually wrote. Zero when it reused last frame's,
     *  which is the whole saving and the only way to see it happen. */
    std::uint32_t rowsPacked() const { return packed_; }

private:
    friend std::span<const EsCmd> run(SystemFn, std::span<const std::uint32_t>,
                                      std::span<const QuerySpec>, std::span<void* const>,
                                      CallArena&, WorldStamp);
    friend std::span<const EsCmd> runBound(const BoundSystem&, std::span<const std::uint32_t>,
                                         const ResourceLookup&, CallArena&, WorldStamp, bool*);
    std::vector<es_addr_t> rows_;
    std::vector<EsQueryRows> queries_;
    std::vector<es_addr_t> resources_;
    std::vector<void*> resourcePointers_;
    std::vector<std::size_t> starts_;
    std::vector<std::uint32_t> counts_;
    std::vector<EsCmd> cmds_;
    std::uint32_t count_ = 0;
    std::uint32_t walked_ = 0;
    std::uint32_t packed_ = 0;
    /** The world the rows were packed against, and EVERY column they were packed
     *  from, by identity — a query matches on all of them, and an engine pool can
     *  gain a member without moving an address, so without moving the stamp. */
    WorldStamp packedAt_;
    std::vector<std::span<const std::uint32_t>> from_;
    /** Per-call scratch, kept so a steady frame allocates nothing. */
    std::vector<std::span<const std::uint32_t>> lists_;
    std::vector<std::span<const std::uint32_t>> columns_;
    EsSysCtx ctx_{};
};

/**
 * Materialise, call, and return the commands the system produced. A row is kept
 * only when every component resolves — an absent one is the filter.
 *
 * `fallback` is walked only by a query that cannot narrow itself; ask
 * {@link narrows} first, since building it is O(world). Applying the commands is
 * the CALLER's job: a despawn here invalidates the rows just handed over.
 */
inline std::span<const EsCmd> run(SystemFn fn,
                                  std::span<const std::uint32_t> fallback,
                                  std::span<const QuerySpec> queries,
                                  std::span<void* const> resources,
                                  CallArena& arena,
                                  WorldStamp world = {}) {
    // Its own column where a query has one, everybody where it has none. A freed
    // slot in a script column reads as an entity nothing resolves for, so the
    // completeness check below drops it like any other miss.
    arena.walked_ = 0;
    arena.lists_.assign(queries.size(), {});
    arena.columns_.clear();
    // A query that cannot say who it matches cannot say whether that changed, so
    // falling back to the caller's list also gives up the row table.
    bool narrowedEvery = !queries.empty();
    for (std::size_t q = 0; q < queries.size(); ++q) {
        Candidates best;
        for (const CandidatesOf& source : queries[q].sources) {
            if (!source) continue;
            const Candidates got = source();
            if (!got) continue;
            arena.columns_.push_back(*got);
            if (!best || got->size() < best->size()) best = got;
        }
        if (!best) narrowedEvery = false;
        arena.lists_[q] = best ? *best : fallback;
        arena.walked_ += static_cast<std::uint32_t>(arena.lists_[q].size());
    }

    bool reuse = narrowedEvery && (world == arena.packedAt_)
        && arena.from_.size() == arena.columns_.size();
    for (std::size_t c = 0; reuse && c < arena.columns_.size(); ++c) {
        if (arena.columns_[c].data() != arena.from_[c].data()
            || arena.columns_[c].size() != arena.from_[c].size()) {
            reuse = false;
        }
    }

    arena.packed_ = 0;
    if (!reuse) {
        arena.rows_.clear();
        arena.queries_.assign(queries.size(), EsQueryRows{});
        // Offsets first, addresses after: one vector holding every query's rows
        // moves under the first query's pointer as the second grows, and the ctx
        // has to point at something that will still be there during the call.
        auto& starts = arena.starts_;
        auto& counts = arena.counts_;
        starts.resize(queries.size());
        counts.assign(queries.size(), 0);
        for (std::size_t q = 0; q < queries.size(); ++q) {
            starts[q] = arena.rows_.size();
            const auto& comps = queries[q].comps;
            for (std::uint32_t e : arena.lists_[q]) {
                const std::size_t mark = arena.rows_.size();
                arena.rows_.push_back(static_cast<es_addr_t>(e));
                bool complete = true;
                for (const auto& at : comps) {
                    void* p = at(e);
                    if (p == nullptr) { complete = false; break; }
                    arena.rows_.push_back(reinterpret_cast<es_addr_t>(p));
                }
                if (complete) ++counts[q];
                else arena.rows_.resize(mark);
            }
            arena.packed_ += counts[q];
        }
        for (std::size_t q = 0; q < queries.size(); ++q) {
            arena.queries_[q].rows = reinterpret_cast<es_addr_t>(arena.rows_.data() + starts[q]);
            arena.queries_[q].count = counts[q];
        }
        // Only a table that narrowed EVERY query can be offered again; an
        // unknown stamp is recorded as unknown and never matches.
        arena.packedAt_ = narrowedEvery ? world : WorldStamp{};
        arena.from_ = arena.columns_;
    }

    arena.resources_.assign(resources.size(), es_addr_t{});
    for (std::size_t r = 0; r < resources.size(); ++r) {
        arena.resources_[r] = reinterpret_cast<es_addr_t>(resources[r]);
    }

    arena.count_ = 0;
    arena.ctx_.queries = reinterpret_cast<es_addr_t>(arena.queries_.data());
    arena.ctx_.resources = reinterpret_cast<es_addr_t>(arena.resources_.data());
    arena.ctx_.cmdBuf = reinterpret_cast<es_addr_t>(arena.cmds_.data());
    arena.ctx_.cmdCap = arena.commandCapacity();
    arena.ctx_.cmdCount = reinterpret_cast<es_addr_t>(&arena.count_);
    arena.ctx_.events = 0;

    fn(reinterpret_cast<es_addr_t>(&arena.ctx_));

    return std::span<const EsCmd>(arena.cmds_.data(), arena.count_);
}

/**
 * A component handed over as MEMORY rather than as a callback: rows at a stride,
 * and a sparse table of `slot + 1` by entity index. What `ScriptPool::span`
 * gives — a script component's entity-to-slot map lives in the scripting
 * language, and asking it per entity per frame is what AOT exists to delete.
 */
struct RowSpan {
    const std::uint32_t* sparse = nullptr;
    std::uint32_t sparseCount = 0;
    unsigned char* rows = nullptr;
    std::uint32_t stride = 0;
    /** Entity::Layout::INDEX_MASK, passed rather than included so this header
     *  stays free of the engine and the harness needs no link. */
    std::uint32_t indexMask = 0;
    /**
     * Slot -> the raw entity holding it, so this column can be asked WHO is in
     * it. The sparse table above answers the other direction only.
     *
     * Null where the owner reported none — the one reason a script component
     * fails to narrow.
     */
    const std::uint32_t* owners = nullptr;
    /** Slots ever claimed. A pool reuses slots rather than compacting, so this
     *  is a high-water mark and the array has holes — see {@link NO_OWNER}. */
    std::uint32_t ownerCount = 0;
};

/** A slot nobody holds. `Entity::INVALID_RAW`: the one raw value the engine
 *  never hands out, so a hole resolves to no row and the filter drops it. */
inline constexpr std::uint32_t NO_OWNER = 0xFFFFFFFFu;

/** One row out of a span. Absent is zero in the table, as it is in a sparse set. */
inline void* rowAt(const RowSpan& span, std::uint32_t entity) {
    const std::uint32_t at = entity & span.indexMask;
    if (at >= span.sparseCount) return nullptr;
    const std::uint32_t slot = span.sparse[at];
    if (slot == 0u) return nullptr;
    return span.rows + static_cast<std::size_t>(slot - 1u) * span.stride;
}

/** `span` as a resolver, for rows that will not move while it is held. */
inline ComponentAt fromRows(const RowSpan& span) {
    return [span](std::uint32_t entity) -> void* { return rowAt(span, entity); };
}

/**
 * The same, for rows that MOVE.
 *
 * A pool reallocates as it grows, and a resolver holding the span by value then
 * reads memory nobody owns; this reads it through a slot the owner overwrites.
 * The slot must outlive the resolver; a null one is simply absent.
 */
inline ComponentAt fromMovingRows(const RowSpan* slot) {
    return [slot](std::uint32_t entity) -> void* {
        return slot == nullptr ? nullptr : rowAt(*slot, entity);
    };
}

/**
 * Who is in that column, read through the same slot for the same reason.
 * nullopt rather than empty when no owner array was reported: "did not say" is
 * not "is empty", and confusing them runs every system over nothing.
 */
inline CandidatesOf fromMovingOwners(const RowSpan* slot) {
    return [slot]() -> Candidates {
        if (slot == nullptr || slot->owners == nullptr) return std::nullopt;
        return std::span<const std::uint32_t>(slot->owners, slot->ownerCount);
    };
}

/**
 * How a host answers the two questions a declaration asks: where one component
 * is for an entity, and where one resource is. Both by NAME, because names are
 * what the artifact carries — it cannot know this host's type ids.
 */
using ComponentLookup = std::function<ComponentAt(const char*)>;

/**
 * The third question, and the only optional one: who holds that component.
 * Separate from `ComponentLookup` because a host with no answer must still bind
 * and run — narrowing is an optimisation and cannot be allowed to change which
 * rows a system sees.
 */
using CandidateLookup = std::function<CandidatesOf(const char*)>;

/**
 * A declared system with its resolvers found once. Resources are looked up per
 * call rather than kept, because a host is free to move one between frames and
 * the contract only promises the address for the length of a call.
 */
struct BoundSystem {
    SystemFn fn = nullptr;
    std::vector<QuerySpec> queries;
    std::vector<const char*> resourceNames;
};

/**
 * Resolve `decl` against this host. A component or resource the host cannot
 * name leaves `fn` null: the system is simply not run, which is the interpreter
 * fallback arriving one layer down rather than a crash at the first row.
 */
inline BoundSystem bind(const EsSystemDecl& decl,
                        const ComponentLookup& components,
                        const ResourceLookup& resources,
                        const CandidateLookup& candidates = {}) {
    BoundSystem out;
    out.queries.resize(decl.queryCount);
    for (std::uint32_t q = 0; q < decl.queryCount; ++q) {
        const EsQueryDecl& qd = decl.queries[q];
        for (std::uint32_t c = 0; c < qd.count; ++c) {
            ComponentAt at = components(qd.comps[c]);
            if (!at) return {};
            out.queries[q].comps.push_back(std::move(at));
            // A column that cannot say leaves a falsy entry rather than none, so
            // `sources` stays index-for-index with `comps` and a reader of one
            // is a reader of the other.
            out.queries[q].sources.push_back(candidates ? candidates(qd.comps[c]) : CandidatesOf{});
        }
    }
    for (std::uint32_t r = 0; r < decl.resourceCount; ++r) {
        if (resources(decl.resources[r]) == nullptr) return {};
        out.resourceNames.push_back(decl.resources[r]);
    }
    out.fn = decl.fn;
    return out;
}

/** Run a bound system, resolving its resources for this call. `fallback` is for
 *  the queries that cannot narrow themselves; see {@link run}. */
inline std::span<const EsCmd> runBound(const BoundSystem& bound,
                                       std::span<const std::uint32_t> fallback,
                                       const ResourceLookup& resources,
                                       CallArena& arena,
                                       WorldStamp world = {}, bool* runnable = nullptr) {
    if (runnable) *runnable = false;
    if (bound.fn == nullptr) return {};
    auto& addresses = arena.resourcePointers_;
    addresses.clear();
    addresses.reserve(bound.resourceNames.size());
    for (const char* name : bound.resourceNames) {
        void* address = resources(name);
        if (address == nullptr) return {};
        addresses.push_back(address);
    }
    if (runnable) *runnable = true;
    return run(bound.fn, fallback, bound.queries, addresses, arena, world);
}

/**
 * The constant a compiled artifact exports, as this host computes it. The
 * contract half comes from the artifact; the width is ours, and mixing it here
 * is what stops a 32-bit artifact loading into a 64-bit host.
 */
inline std::uint64_t abiHash(std::uint64_t contract) {
    return contract ^ (0x9e3779b97f4a7c15ULL * sizeof(es_addr_t));
}

}  // namespace esengine::aot