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.

7.7 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    AotDispatcher.hpp
 * @brief   A loaded module's systems, bound once and callable by index.
 *
 * @details `AotModule` says what a module is and `AotHost` says how one call
 *          goes; between them sits the thing a host actually holds for a frame —
 *          the open module, the arena its calls reuse, and each system resolved
 *          against this world once instead of per call.
 *
 *          Index, not name. The scheduler asks for the same system every frame
 *          and a name lookup there is a strcmp per system per frame on the path
 *          AOT exists to make cheap; a caller resolves the index at install.
 *
 *          The lookups are the CALLER's, because who can name a component
 *          differs by host: engine components come from the generated table,
 *          and a project's own live in the pool the scripting language owns.
 *
 *          Commands come back rather than being applied. A despawn invalidates
 *          the rows just handed over, so who applies them decides when — and
 *          this class does not know how to remove a component by name anyway.
 *
 *          One arena PER SYSTEM, not one shared: a shared one is overwritten by
 *          the next system and nothing can be kept across frames.
 */
#pragma once

#include <cstdint>
#include <optional>
#include <span>
#include <string>
#include <utility>
#include <vector>

#include "esengine/aot/AotHost.hpp"
#include "esengine/aot/AotModule.hpp"

namespace esengine::aot {

class Dispatcher {
public:
    /**
     * Open `path` and bind every system it declares.
     *
     * True when the module opened and agreed about the engine. A system this
     * host cannot name every component of is left UNBOUND, not refused — the
     * per-system fallback, one layer down; `boundAt` says which ones resolved.
     */
    bool install(const char* path, std::uint64_t expected,
                 const ComponentLookup& components, const ResourceLookup& resources,
                 std::string* why = nullptr, const CandidateLookup& candidates = {},
                 std::optional<std::uint64_t> expectedContract = std::nullopt) {
        // Prepare a complete replacement before touching the live module. The
        // staged owner closes its library on refusal or a lookup/allocation throw.
        Dispatcher next;
        if (!next.module_.open(path, expected, why)) return false;
        if (expectedContract && next.module_.contract() != 0 && next.module_.contract() != *expectedContract) {
            if (why) *why = "module and manifest are from different builds";
            return false;
        }
        next.components_ = components;
        next.resources_ = resources;
        next.candidates_ = candidates;
        for (const EsSystemDecl& decl : next.module_.systems()) {
            next.names_.push_back(decl.name != nullptr ? decl.name : "");
            next.bound_.push_back(::esengine::aot::bind(decl, next.components_, next.resources_, next.candidates_));
        }
        next.arenas_ = std::vector<CallArena>(next.bound_.size());
        // These swaps cannot throw; next now owns and retires the old runtime.
        std::swap(module_, next.module_);
        names_.swap(next.names_);
        bound_.swap(next.bound_);
        arenas_.swap(next.arenas_);
        components_.swap(next.components_);
        resources_.swap(next.resources_);
        candidates_.swap(next.candidates_);
        return true;
    }

    /** How many systems the module declared — bound or not. */
    std::size_t count() const { return bound_.size(); }

    /** Which BUILD the open module is, or 0 where it cannot say. The SDK holds
     *  the sidecar and is the half that can compare. */
    std::uint64_t contract() const { return module_.contract(); }

    /** The declared name at that index, or an empty string out of range. */
    const char* nameAt(std::size_t i) const { return i < names_.size() ? names_[i] : ""; }

    /** Whether the system at that index resolved. An unbound one runs nothing. */
    bool boundAt(std::size_t i) const { return i < bound_.size() && bound_[i].fn != nullptr; }

    /**
     * Whether every query of that system names its own candidates, and so
     * whether `run` may be given an EMPTY fallback.
     *
     * Asked per frame, not at install: a script pool exists only once an entity
     * has that component. False when unbound — ignoring it is slow, never wrong.
     */
    bool narrowsAt(std::size_t i) const {
        if (i >= bound_.size() || bound_[i].fn == nullptr) return false;
        return ::esengine::aot::narrows(bound_[i].queries);
    }

    /** The index of a declared name, or `npos`. Called at install, not per frame. */
    std::size_t indexOf(const char* name) const {
        for (std::size_t i = 0; i < names_.size(); ++i) {
            if (names_[i] != nullptr && name != nullptr && std::strcmp(names_[i], name) == 0) return i;
        }
        return npos;
    }

    /**
     * Run one system, and hand back what it wrote.
     *
     * `candidates` is the FALLBACK, walked only by a query that could not name
     * its own column — ask {@link narrowsAt} first. `world` decides whether last
     * frame's rows still stand; an unknown stamp repacks. Resources are resolved
     * per call because the contract promises an address for one call only.
     */
    std::span<const EsCmd> run(std::size_t i, std::span<const std::uint32_t> candidates,
                               const ResourceLookup& resources, WorldStamp world = {}) {
        if (i >= bound_.size()) return {};
        // Asked again where install could not name everything: a pool the
        // scripting language owns does not exist until an entity has that
        // component, so the answer is about the frame, not the module.
        if (bound_[i].fn == nullptr) {
            // Qualified: `std::bind` is visible through <functional> and takes anything.
            bound_[i] = ::esengine::aot::bind(module_.systems()[i], components_, resources_, candidates_);
        }
        if (bound_[i].fn == nullptr) return {};
        bool runnable = false;
        const auto commands = runBound(bound_[i], candidates, resources, arenas_[i], world, &runnable);
        if (!runnable) bound_[i].fn = nullptr;
        return commands;
    }

    /** Entities that system's last {@link run} covered. See CallArena. */
    std::uint32_t candidatesWalked(std::size_t i) const {
        return i < arenas_.size() ? arenas_[i].candidatesWalked() : 0u;
    }

    /** Rows that system's last {@link run} wrote — zero when it kept last
     *  frame's, which is the only way to see the saving happen. */
    std::uint32_t rowsPacked(std::size_t i) const {
        return i < arenas_.size() ? arenas_[i].rowsPacked() : 0u;
    }

    /** Close the module and forget the bindings — they point into it. */
    void reset() {
        bound_.clear();
        names_.clear();
        arenas_.clear();
        components_ = {};
        resources_ = {};
        candidates_ = {};
        module_.close();
    }

    static constexpr std::size_t npos = static_cast<std::size_t>(-1);

private:
    Module module_;
    std::vector<const char*> names_;
    std::vector<BoundSystem> bound_;
    /** Kept so a system that could not be named at install can be asked
     *  again — the answer changes as the world comes up. */
    ComponentLookup components_;
    ResourceLookup resources_;
    /** Optional, and absent on a host that cannot enumerate a column: then every
     *  query falls back to the candidates the caller passes. */
    CandidateLookup candidates_;
    /** One per system, so a row table can outlive the call that built it. */
    std::vector<CallArena> arenas_;
};

}  // namespace esengine::aot