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.

19.0 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    esjs_v8.cpp
 * @brief   esjs over V8 — the engine where a JIT is allowed (desktop, Android).
 * @details One isolate and one context for the process. What this file adds to
 *          the plain embedding is what the host's contract asks for and V8 does
 *          not assume:
 *
 *            * Microtasks run when the host pumps them, not whenever a call
 *              returns — app.tick() is async, and the frame loop decides when its
 *              systems run (QuickJS's job queue has the same shape).
 *            * The isolate is entered per host entry, under a Locker, because a
 *              platform may hand the next frame to a different thread (Android
 *              recreates its glue thread), and the stack limit follows the thread.
 *            * A read that throws (a getter, a valueOf) answers a default, as the
 *              QuickJS backend does: bindings read loosely-shaped SDK objects and
 *              must not leave an exception pending behind a normal return.
 *
 * @author  ESEngine Team
 * @date    2026
 *
 * @copyright Copyright (c) 2026 ESEngine Team
 *            Licensed under the Apache License, Version 2.0.
 */
#include "esjs.hpp"

#include <libplatform/libplatform.h>
#include <v8.h>

#include <cstdlib>
#include <cstring>
#include <memory>
#include <new>
#include <thread>

#if defined(ESJS_V8_ICU) && defined(_WIN32)
#define WIN32_LEAN_AND_MEAN
#define NOMINMAX
#include <windows.h>
#endif

namespace esjs {
namespace {

static_assert(sizeof(v8::Local<v8::Value>) == sizeof(void*), "a Local is one pointer");

std::unique_ptr<v8::Platform> g_platform;
v8::ArrayBuffer::Allocator* g_allocator = nullptr;
v8::Isolate* g_iso = nullptr;
v8::Global<v8::Context> g_context;
Logger g_log = nullptr;
bool g_alive = false;
std::thread::id g_thread;

// A Val's bits: the Local's pointer, and a flag for "an exception is pending".
constexpr size_t kThrewByte = 8;

inline v8::Local<v8::Value> raw(Val v) {
    v8::Local<v8::Value> l;
    std::memcpy(static_cast<void*>(&l), v.bits, sizeof(l));
    return l;
}

inline Val wrap(v8::Local<v8::Value> l) {
    Val v;
    std::memcpy(v.bits, static_cast<const void*>(&l), sizeof(l));
    return v;
}

inline Val threw() {
    Val v;
    v.bits[kThrewByte] = 1;
    return v;
}

inline bool isThrew(Val v) { return v.bits[kThrewByte] != 0; }

inline v8::Local<v8::Context> ctx() { return g_context.Get(g_iso); }

void say(bool error, const std::string& s) {
    if (g_log) g_log(error, s.c_str());
}

std::string utf8Of(v8::Local<v8::Value> v) {
    if (v.IsEmpty()) return {};
    v8::String::Utf8Value s(g_iso, v);
    return *s ? std::string(*s, static_cast<size_t>(s.length())) : std::string("?");
}

/** Report what a TryCatch caught, with its stack: a bare message ("Maximum call
 *  stack size exceeded") says nothing about which SDK path produced it. */
void report(v8::TryCatch& tc, const char* where) {
    if (!tc.HasCaught()) return;
    say(true, std::string("JS error in ") + where + ": " + utf8Of(tc.Exception()));
    v8::Local<v8::Value> stack;
    if (tc.StackTrace(ctx()).ToLocal(&stack) && stack->IsString()) {
        say(true, "  stack: " + utf8Of(stack));
    }
}

/** An exception nothing caught — a microtask's, a promise job's. */
void onMessage(v8::Local<v8::Message> message, v8::Local<v8::Value> error) {
    std::string where = utf8Of(message->GetScriptResourceName());
    const int line = message->GetLineNumber(ctx()).FromMaybe(0);
    say(true, "JS error in " + (where.empty() ? std::string("promise job") : where) + ":"
              + std::to_string(line) + ": " + utf8Of(error));
    v8::Local<v8::Value> stack;
    if (error->IsObject() &&
        error.As<v8::Object>()->Get(ctx(), v8::String::NewFromUtf8Literal(g_iso, "stack")).ToLocal(&stack) &&
        stack->IsString()) {
        say(true, "  stack: " + utf8Of(stack));
    }
}

v8::Local<v8::String> key(const char* k) {
    return v8::String::NewFromUtf8(g_iso, k, v8::NewStringType::kInternalized).ToLocalChecked();
}

void trampoline(const v8::FunctionCallbackInfo<v8::Value>& info) {
    const auto fn = reinterpret_cast<NativeFn>(info.Data().As<v8::External>()->Value());
    Args args;
    args.impl_ = &info;
    args.argc_ = info.Length();
    const Val r = fn(args);
    if (isThrew(r)) return;   // the exception is already scheduled
    const v8::Local<v8::Value> out = raw(r);
    if (!out.IsEmpty()) info.GetReturnValue().Set(out);
}

/** Bind the isolate's stack limit to the calling thread when it changes: V8 takes
 *  it from the thread that made the isolate, and a later thread's stack lies
 *  somewhere else entirely. The budget is what a platform thread reliably has
 *  below a host entry. */
void followThread() {
    const auto self = std::this_thread::get_id();
    if (self == g_thread) return;
    g_thread = self;
    constexpr uintptr_t kBudget = 768 * 1024;
    const uintptr_t here = reinterpret_cast<uintptr_t>(&self);
    if (here > kBudget) g_iso->SetStackLimit(here - kBudget);
}

struct EnterState {
    v8::Locker locker;
    v8::Isolate::Scope isolateScope;
    v8::HandleScope handles;
    v8::Context::Scope contextScope;
    explicit EnterState(v8::Isolate* iso)
        : locker(iso), isolateScope(iso), handles(iso), contextScope(g_context.Get(iso)) {}
};
static_assert(sizeof(EnterState) <= 160, "Enter storage");
static_assert(sizeof(v8::HandleScope) <= 64, "Scope storage");

}  // namespace

// =============================================================================
// Values
// =============================================================================

Val Args::operator[](int i) const {
    const auto& info = *static_cast<const v8::FunctionCallbackInfo<v8::Value>*>(impl_);
    return wrap(info[i]);   // undefined past Length()
}

Val undefined() { return wrap(v8::Undefined(g_iso)); }
Val null() { return wrap(v8::Null(g_iso)); }
Val boolean(bool v) { return wrap(v8::Boolean::New(g_iso, v)); }
Val number(double v) { return wrap(v8::Number::New(g_iso, v)); }
Val int32(int32_t v) { return wrap(v8::Integer::New(g_iso, v)); }
Val uint32(uint32_t v) { return wrap(v8::Integer::NewFromUnsigned(g_iso, v)); }
Val int64(int64_t v) { return wrap(v8::Number::New(g_iso, static_cast<double>(v))); }

Val string(std::string_view s) {
    v8::Local<v8::String> out;
    if (!v8::String::NewFromUtf8(g_iso, s.data(), v8::NewStringType::kNormal, static_cast<int>(s.size()))
             .ToLocal(&out)) {
        return undefined();   // longer than V8's string limit
    }
    return wrap(out);
}

Val object() { return wrap(v8::Object::New(g_iso)); }
Val array() { return wrap(v8::Array::New(g_iso)); }

Val arrayBufferCopy(const void* data, size_t size) {
    v8::Local<v8::ArrayBuffer> ab = v8::ArrayBuffer::New(g_iso, size);
    if (size) std::memcpy(ab->GetBackingStore()->Data(), data, size);
    return wrap(ab);
}

Val arrayBufferWrap(void* data, size_t size) {
    auto store = v8::ArrayBuffer::NewBackingStore(data, size, v8::BackingStore::EmptyDeleter, nullptr);
    return wrap(v8::ArrayBuffer::New(g_iso, std::move(store)));
}

Val throwTypeError(const char* message) {
    g_iso->ThrowException(v8::Exception::TypeError(key(message)));
    return threw();
}

Val throwError(const char* message) {
    g_iso->ThrowException(v8::Exception::Error(key(message)));
    return threw();
}

bool isUndefined(Val v) { return raw(v)->IsUndefined(); }
bool isNull(Val v) { return raw(v)->IsNull(); }
bool isBool(Val v) { return raw(v)->IsBoolean(); }
bool isNumber(Val v) { return raw(v)->IsNumber(); }
bool isString(Val v) { return raw(v)->IsString(); }
bool isFunction(Val v) { return raw(v)->IsFunction(); }
bool isObject(Val v) { return raw(v)->IsObject(); }
bool isArray(Val v) { return raw(v)->IsArray(); }

double toNumber(Val v) {
    const v8::Local<v8::Value> l = raw(v);
    if (l->IsNumber()) return l.As<v8::Number>()->Value();
    v8::TryCatch tc(g_iso);
    return l->NumberValue(ctx()).FromMaybe(0);
}

int32_t toInt32(Val v) {
    const v8::Local<v8::Value> l = raw(v);
    if (l->IsInt32()) return l.As<v8::Int32>()->Value();
    v8::TryCatch tc(g_iso);
    return l->Int32Value(ctx()).FromMaybe(0);
}

uint32_t toUint32(Val v) {
    const v8::Local<v8::Value> l = raw(v);
    if (l->IsUint32()) return l.As<v8::Uint32>()->Value();
    v8::TryCatch tc(g_iso);
    return l->Uint32Value(ctx()).FromMaybe(0);
}

int64_t toInt64(Val v) {
    const v8::Local<v8::Value> l = raw(v);
    if (l->IsInt32()) return l.As<v8::Int32>()->Value();
    v8::TryCatch tc(g_iso);
    return l->IntegerValue(ctx()).FromMaybe(0);
}

bool toBool(Val v) { return raw(v)->BooleanValue(g_iso); }

std::string toString(Val v) {
    Utf8 s(v);
    return std::string(s.view());
}

Utf8::Utf8(Val v) {
    v8::Local<v8::Value> l = raw(v);
    v8::Local<v8::String> s;
    if (l->IsString()) {
        s = l.As<v8::String>();
    } else {
        v8::TryCatch tc(g_iso);
        if (!l->ToString(ctx()).ToLocal(&s)) return;
    }
    own_.resize(static_cast<size_t>(s->Utf8Length(g_iso)));
    if (!own_.empty()) {
        s->WriteUtf8(g_iso, own_.data(), static_cast<int>(own_.size()), nullptr,
                     v8::String::NO_NULL_TERMINATION | v8::String::REPLACE_INVALID_UTF8);
    }
    data_ = own_.c_str();
    size_ = own_.size();
}

Utf8::~Utf8() = default;

bool bytesOf(Val v, Bytes* out) {
    const v8::Local<v8::Value> l = raw(v);
    if (l->IsArrayBuffer()) {
        auto store = l.As<v8::ArrayBuffer>()->GetBackingStore();
        out->data = static_cast<uint8_t*>(store->Data());
        out->size = store->ByteLength();
        return true;
    }
    if (l->IsArrayBufferView()) {
        const auto view = l.As<v8::ArrayBufferView>();
        auto store = view->Buffer()->GetBackingStore();
        const size_t offset = view->ByteOffset(), length = view->ByteLength();
        if (offset + length > store->ByteLength()) return false;
        out->data = static_cast<uint8_t*>(store->Data()) + offset;
        out->size = length;
        return true;
    }
    return false;
}

// =============================================================================
// Objects
// =============================================================================

Val global() { return wrap(ctx()->Global()); }

Val get(Val obj, const char* k) {
    const v8::Local<v8::Value> o = raw(obj);
    if (!o->IsObject()) return undefined();
    v8::TryCatch tc(g_iso);
    v8::Local<v8::Value> out;
    if (!o.As<v8::Object>()->Get(ctx(), key(k)).ToLocal(&out)) return undefined();
    return wrap(out);
}

void set(Val obj, const char* k, Val value) {
    const v8::Local<v8::Value> o = raw(obj);
    if (!o->IsObject()) return;
    v8::TryCatch tc(g_iso);
    (void)o.As<v8::Object>()->Set(ctx(), key(k), raw(value));
}

Val getAt(Val obj, uint32_t index) {
    const v8::Local<v8::Value> o = raw(obj);
    if (!o->IsObject()) return undefined();
    v8::TryCatch tc(g_iso);
    v8::Local<v8::Value> out;
    if (!o.As<v8::Object>()->Get(ctx(), index).ToLocal(&out)) return undefined();
    return wrap(out);
}

void setAt(Val obj, uint32_t index, Val value) {
    const v8::Local<v8::Value> o = raw(obj);
    if (!o->IsObject()) return;
    v8::TryCatch tc(g_iso);
    (void)o.As<v8::Object>()->Set(ctx(), index, raw(value));
}

uint32_t lengthOf(Val obj) {
    const v8::Local<v8::Value> o = raw(obj);
    if (o->IsArray()) return o.As<v8::Array>()->Length();
    const Val len = get(obj, "length");
    return isUndefined(len) ? 0 : toUint32(len);
}

std::vector<std::string> ownKeys(Val obj) {
    std::vector<std::string> keys;
    const v8::Local<v8::Value> o = raw(obj);
    if (!o->IsObject()) return keys;
    v8::TryCatch tc(g_iso);
    v8::Local<v8::Array> names;
    if (!o.As<v8::Object>()
             ->GetOwnPropertyNames(ctx(), static_cast<v8::PropertyFilter>(
                                              v8::ONLY_ENUMERABLE | v8::SKIP_SYMBOLS))
             .ToLocal(&names)) {
        return keys;
    }
    const uint32_t n = names->Length();
    keys.reserve(n);
    for (uint32_t i = 0; i < n; ++i) {
        v8::Local<v8::Value> name;
        if (names->Get(ctx(), i).ToLocal(&name)) keys.push_back(utf8Of(name));
    }
    return keys;
}

void setFunction(Val obj, const char* name, NativeFn fn, int argc) {
    const v8::Local<v8::Value> o = raw(obj);
    if (!o->IsObject()) return;
    auto tmpl = v8::FunctionTemplate::New(g_iso, trampoline,
                                          v8::External::New(g_iso, reinterpret_cast<void*>(fn)),
                                          v8::Local<v8::Signature>(), argc,
                                          v8::ConstructorBehavior::kThrow);
    v8::Local<v8::Function> f;
    if (!tmpl->GetFunction(ctx()).ToLocal(&f)) return;
    f->SetName(key(name));
    (void)o.As<v8::Object>()->Set(ctx(), key(name), f);
}

bool call(Val fn, Val self, int argc, const Val* argv, const char* where, Val* result) {
    if (result) *result = undefined();
    const v8::Local<v8::Value> f = raw(fn);
    if (!f->IsFunction()) return false;
    std::vector<v8::Local<v8::Value>> args(static_cast<size_t>(argc > 0 ? argc : 0));
    for (int i = 0; i < argc; ++i) args[static_cast<size_t>(i)] = raw(argv[i]);
    v8::TryCatch tc(g_iso);
    v8::Local<v8::Value> out;
    if (!f.As<v8::Function>()->Call(ctx(), raw(self), argc, args.data()).ToLocal(&out)) {
        report(tc, where);
        return false;
    }
    if (result) *result = wrap(out);
    return true;
}

// =============================================================================
// Lifetimes
// =============================================================================

Scope::Scope() { ::new (storage_) v8::HandleScope(g_iso); }   // :: — HandleScope hides operator new
Scope::~Scope() { reinterpret_cast<v8::HandleScope*>(storage_)->~HandleScope(); }

Ref::Ref(Val v) : handle_(new v8::Global<v8::Value>(g_iso, raw(v))) {}

Ref::~Ref() { reset(); }

Ref& Ref::operator=(Ref&& o) noexcept {
    if (this != &o) {
        reset();
        handle_ = o.handle_;
        o.handle_ = nullptr;
    }
    return *this;
}

Val Ref::get() const {
    if (!handle_) return undefined();
    return wrap(static_cast<v8::Global<v8::Value>*>(handle_)->Get(g_iso));
}

void Ref::reset() {
    if (!handle_) return;
    auto* g = static_cast<v8::Global<v8::Value>*>(handle_);
    if (g_alive) delete g;   // after exit the isolate is not ours to touch; the OS reclaims it
    handle_ = nullptr;
}

// =============================================================================
// The engine
// =============================================================================

std::vector<uint8_t> g_snapshot;           // must outlive the isolate
v8::StartupData g_snapshotData{nullptr, 0};

void setStartupSnapshot(const uint8_t* data, size_t size) {
    g_snapshot.assign(data, data + size);
    g_snapshotData = {reinterpret_cast<const char*>(g_snapshot.data()), static_cast<int>(g_snapshot.size())};
    v8::V8::SetSnapshotDataBlob(&g_snapshotData);
}

void init(Logger log, const char* exePath) {
    g_log = log;
#if defined(ESJS_V8_ICU)
    // A build with Intl reads its locale data from icudtl.dat beside the binary.
#if defined(_WIN32)
    char self[MAX_PATH] = {};
    if (!exePath && GetModuleFileNameA(nullptr, self, MAX_PATH)) exePath = self;
#endif
    if (!v8::V8::InitializeICUDefaultLocation(exePath ? exePath : "")) {
        say(true, "V8: icudtl.dat not found beside the executable — Intl will not work");
    }
#else
    (void)exePath;
#endif
    g_platform = v8::platform::NewDefaultPlatform();
    v8::V8::InitializePlatform(g_platform.get());
    v8::V8::Initialize();

    g_allocator = v8::ArrayBuffer::Allocator::NewDefaultAllocator();
    v8::Isolate::CreateParams params;
    params.array_buffer_allocator = g_allocator;
    g_iso = v8::Isolate::New(params);
    g_thread = std::this_thread::get_id();
    {
        v8::Locker locker(g_iso);
        v8::Isolate::Scope isolateScope(g_iso);
        v8::HandleScope handles(g_iso);
        g_iso->SetMicrotasksPolicy(v8::MicrotasksPolicy::kExplicit);
        g_iso->AddMessageListener(onMessage);
        g_context.Reset(g_iso, v8::Context::New(g_iso));
    }
    g_alive = true;
    // Process exit destroys the host's statics after this runs, and their Refs
    // must not reach an isolate whose platform the C library is tearing down.
    std::atexit([] { g_alive = false; });
}

bool alive() { return g_alive; }

std::string engineName() { return std::string("V8 ") + v8::V8::GetVersion(); }

bool hasJit() { return true; }

Enter::Enter() {
    ::new (storage_) EnterState(g_iso);
    followThread();
}

Enter::~Enter() { reinterpret_cast<EnterState*>(storage_)->~EnterState(); }

void pumpMicrotasks() { g_iso->PerformMicrotaskCheckpoint(); }

void pumpEngine() {
    while (v8::platform::PumpMessageLoop(g_platform.get(), g_iso)) {
    }
}

namespace {

bool compileAndRun(std::string_view source, const char* name, v8::ScriptCompiler::CachedData* cache,
                   CacheUse* use, std::vector<uint8_t>* fresh) {
    v8::TryCatch tc(g_iso);
    v8::Local<v8::String> code;
    if (!v8::String::NewFromUtf8(g_iso, source.data(), v8::NewStringType::kNormal,
                                 static_cast<int>(source.size()))
             .ToLocal(&code)) {
        say(true, std::string("JS error in ") + name + ": source too large");
        return false;
    }
    v8::ScriptOrigin origin(g_iso, key(name));
    v8::ScriptCompiler::Source src(code, origin, cache);   // takes the cache
    const auto options = cache ? v8::ScriptCompiler::kConsumeCodeCache : v8::ScriptCompiler::kNoCompileOptions;
    v8::Local<v8::Script> script;
    if (!v8::ScriptCompiler::Compile(ctx(), &src, options).ToLocal(&script)) {
        report(tc, name);
        return false;
    }
    if (cache && use) *use = src.GetCachedData()->rejected ? CacheUse::Rejected : CacheUse::Used;
    v8::Local<v8::Value> result;
    if (!script->Run(ctx()).ToLocal(&result)) {
        report(tc, name);
        return false;
    }
    // After the run, so the functions the top level compiled are in the blob too.
    if (fresh && (!use || *use != CacheUse::Used)) {
        std::unique_ptr<v8::ScriptCompiler::CachedData> out(
            v8::ScriptCompiler::CreateCodeCache(script->GetUnboundScript()));
        if (out) fresh->assign(out->data, out->data + out->length);
    }
    return true;
}

}  // namespace

bool run(std::string_view source, const char* name) {
    return compileAndRun(source, name, nullptr, nullptr, nullptr);
}

bool runCached(std::string_view source, const char* name, const uint8_t* cache, size_t cacheSize,
               CacheUse* use, std::string* why, std::vector<uint8_t>* fresh) {
    if (use) *use = CacheUse::None;
    v8::ScriptCompiler::CachedData* data = nullptr;
    if (cache && cacheSize) {
        data = new v8::ScriptCompiler::CachedData(cache, static_cast<int>(cacheSize),
                                                  v8::ScriptCompiler::CachedData::BufferNotOwned);
    }
    const bool ok = compileAndRun(source, name, data, use, fresh);
    if (use && *use == CacheUse::Rejected && why) {
        *why = "built by a different V8 build, flag set or source";
    }
    return ok;
}

const char* cacheTag() { return "v8cache"; }

}  // namespace esjs