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
perf(physics): solve across worker threads on a device
esengineb53db87df664
diff --git a/CMakeLists.txt b/CMakeLists.txtindex cbb90ce24..ec2873e06 100644--- a/CMakeLists.txt+++ b/CMakeLists.txt@@ -495,6 +495,7 @@ html,body{width:100%;height:100%;overflow:hidden;background:#1a1a1a}src/esengine/bindings/PhysicsShapes.cppsrc/esengine/bindings/PhysicsJoints.cppsrc/esengine/bindings/PhysicsQueries.cpp+ src/esengine/bindings/PhysicsTaskPool.cpp)if(ES_PHYSICS_ESM)# ESM variant (EXPORT_ES6=1) for the web editor's estella:// ESM host —@@ -552,6 +553,7 @@ html,body{width:100%;height:100%;overflow:hidden;background:#1a1a1a}src/esengine/bindings/PhysicsShapes.cppsrc/esengine/bindings/PhysicsJoints.cppsrc/esengine/bindings/PhysicsQueries.cpp+ src/esengine/bindings/PhysicsTaskPool.cpp)target_link_libraries(physics_side_module PRIVATE box2d)target_include_directories(physics_side_module PRIVATEdiff --git a/native/CMakeLists.txt b/native/CMakeLists.txtindex 8b10f74c4..b34f5ce41 100644--- a/native/CMakeLists.txt+++ b/native/CMakeLists.txt@@ -107,7 +107,8 @@ set(ESTELLA_PHYSICS_SOURCES"${SRC}/esengine/bindings/PhysicsShapes.cpp""${SRC}/esengine/bindings/PhysicsJoints.cpp""${SRC}/esengine/bindings/PhysicsQueries.cpp"- "${SRC}/esengine/bindings/PhysicsReadback.cpp")+ "${SRC}/esengine/bindings/PhysicsReadback.cpp"+ "${SRC}/esengine/bindings/PhysicsTaskPool.cpp")add_library(estella_physics STATIC ${ESTELLA_PHYSICS_SOURCES})target_include_directories(estella_physics PUBLIC "${SRC}" "${TP}/box2d/include")target_link_libraries(estella_physics PUBLIC box2d)diff --git a/src/esengine/bindings/PhysicsModuleEntry.cpp b/src/esengine/bindings/PhysicsModuleEntry.cppindex 2f3e4cc8b..5209b244e 100644--- a/src/esengine/bindings/PhysicsModuleEntry.cpp+++ b/src/esengine/bindings/PhysicsModuleEntry.cpp@@ -1,10 +1,22 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team#include "PhysicsContext.hpp"+#include "PhysicsTaskPool.hpp"#include <algorithm>#include <cmath>+#ifndef __EMSCRIPTEN__+namespace {+/// The pool the world solves across, built with the first world and torn down at+/// exit. A wasm side module has no threads, so this exists only off the web.+esengine::physics::TaskPool& taskPool() {+ static esengine::physics::TaskPool pool;+ return pool;+}+} // namespace+#endif+// How closely the contact normal must align with a platform's solid normal for the// contact to survive (matches Box2D's own one-sided-platform sample).static constexpr float ONE_WAY_ALIGN_THRESHOLD = 0.95f;@@ -49,6 +61,12 @@ void physics_init(float gx, float gy, float timestep, int substeps,worldDef.contactHertz = contactHertz;worldDef.contactDampingRatio = contactDampingRatio;worldDef.contactSpeed = contactSpeed;+#ifndef __EMSCRIPTEN__+ // Solve across the cores a device has and the web build does not. The result+ // is the same either way — Box2D is deterministic under multithreading — so+ // this changes only how long a step takes, never what it produces.+ taskPool().configure(worldDef);+#endifg_ctx.worldId = b2CreateWorld(&worldDef);b2World_SetPreSolveCallback(g_ctx.worldId, preSolveOneWayPlatform, nullptr);diff --git a/src/esengine/bindings/PhysicsTaskPool.cpp b/src/esengine/bindings/PhysicsTaskPool.cppnew file mode 100644index 000000000..c0eb1bd20--- /dev/null+++ b/src/esengine/bindings/PhysicsTaskPool.cpp@@ -0,0 +1,158 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+#include "PhysicsTaskPool.hpp"++#ifndef __EMSCRIPTEN__++#include <algorithm>++namespace esengine::physics {+namespace {++/// Leave headroom for the threads the frame already owns (the game/render thread+/// this is called from, and the OS). Solving is not the only thing running.+constexpr int kReservedCores = 2;+/// Past a handful of workers the sync bits cost more than the split saves, and a+/// phone's remaining cores are the small ones.+constexpr int kMaxWorkers = 4;++} // namespace++TaskPool::TaskPool() {+ const int cores = static_cast<int>(std::thread::hardware_concurrency());+ workerCount_ = std::clamp(cores - kReservedCores, 0, kMaxWorkers);+ if (workerCount_ < 2) {+ // One worker is the serial solver with extra bookkeeping; take the+ // serial path instead and report no workers.+ workerCount_ = 0;+ return;+ }++ // Worker 0 is whoever steps the world — it helps from finishTask — so the+ // pool owns the rest. One thread per index, and only one: Box2D indexes its+ // per-worker scratch by these, and two threads on one index corrupt a step.+ threads_.reserve(static_cast<size_t>(workerCount_ - 1));+ for (int i = 1; i < workerCount_; i++) {+ threads_.emplace_back([this, i] { workerLoop(static_cast<uint32_t>(i)); });+ }+}++TaskPool::~TaskPool() {+ {+ std::lock_guard<std::mutex> lock(mutex_);+ stopping_ = true;+ }+ queued_.notify_all();+ for (auto& thread : threads_) {+ if (thread.joinable()) thread.join();+ }+}++void TaskPool::configure(b2WorldDef& def) {+ if (workerCount_ == 0) return; // serial world; leave Box2D's defaults+ def.workerCount = workerCount_;+ def.enqueueTask = &TaskPool::enqueueTask;+ def.finishTask = &TaskPool::finishTask;+ def.userTaskContext = this;+}++TaskPool::Group* TaskPool::acquireGroup() {+ for (auto& group : groups_) {+ if (group.free) {+ group.free = false;+ group.pending.store(0, std::memory_order_relaxed);+ return &group;+ }+ }+ // deque keeps existing elements addressable, which matters because a Group+ // is held by pointer while its jobs run.+ groups_.emplace_back();+ groups_.back().free = false;+ return &groups_.back();+}++void* TaskPool::submit(b2TaskCallback* task, int itemCount, int minRange, void* taskContext) {+ if (itemCount <= 0) return nullptr;++ // Honour minRange: below it the split costs more than it saves, and Box2D+ // states the range each worker gets should not be smaller.+ const int maxSlices = std::max(1, itemCount / std::max(1, minRange));+ const int slices = std::clamp(maxSlices, 1, workerCount_);++ Group* group = nullptr;+ {+ std::lock_guard<std::mutex> lock(mutex_);+ group = acquireGroup();+ group->pending.store(slices, std::memory_order_relaxed);++ const int base = itemCount / slices;+ const int remainder = itemCount % slices;+ int start = 0;+ for (int i = 0; i < slices; i++) {+ const int size = base + (i < remainder ? 1 : 0);+ queue_.push_back(Job{task, start, start + size, taskContext, group});+ start += size;+ }+ }+ if (slices == 1) queued_.notify_one();+ else queued_.notify_all();+ return group;+}++void TaskPool::wait(Group* group) {+ // The calling thread is worker 0, so it works rather than blocks. Box2D+ // enqueues the island split alongside the whole worker set; a thread that+ // only waited could leave a solver worker queued behind it, and its peers+ // spin on a barrier that worker never reaches.+ while (group->pending.load(std::memory_order_acquire) != 0) {+ Job job;+ {+ std::lock_guard<std::mutex> lock(mutex_);+ if (!queue_.empty()) {+ job = queue_.front();+ queue_.pop_front();+ }+ }+ if (!job.fn) {+ // Nothing queued: the remaining slices are already running on pool+ // threads, so give up the core rather than spinning on them.+ std::this_thread::yield();+ continue;+ }+ job.fn(job.startIndex, job.endIndex, 0u, job.taskContext);+ job.group->pending.fetch_sub(1, std::memory_order_acq_rel);+ }+ std::lock_guard<std::mutex> lock(mutex_);+ group->free = true;+}++void TaskPool::workerLoop(uint32_t workerIndex) {+ while (true) {+ Job job;+ {+ std::unique_lock<std::mutex> lock(mutex_);+ queued_.wait(lock, [this] { return stopping_ || !queue_.empty(); });+ if (stopping_ && queue_.empty()) return;+ job = queue_.front();+ queue_.pop_front();+ }+ // This thread owns this index for the pool's lifetime, which is the+ // guarantee Box2D asks for.+ job.fn(job.startIndex, job.endIndex, workerIndex, job.taskContext);+ job.group->pending.fetch_sub(1, std::memory_order_acq_rel);+ }+}++void* TaskPool::enqueueTask(b2TaskCallback* task, int itemCount, int minRange,+ void* taskContext, void* userContext) {+ return static_cast<TaskPool*>(userContext)->submit(task, itemCount, minRange, taskContext);+}++void TaskPool::finishTask(void* userTask, void* userContext) {+ if (!userTask) return;+ static_cast<TaskPool*>(userContext)->wait(static_cast<Group*>(userTask));+}++} // namespace esengine::physics++#endif // __EMSCRIPTEN__diff --git a/src/esengine/bindings/PhysicsTaskPool.hpp b/src/esengine/bindings/PhysicsTaskPool.hppnew file mode 100644index 000000000..a96e03302--- /dev/null+++ b/src/esengine/bindings/PhysicsTaskPool.hpp@@ -0,0 +1,106 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file PhysicsTaskPool.hpp+ * @brief The worker pool Box2D solves across on a device.+ *+ * @details Box2D partitions a step into tasks and asks a host-supplied pool to+ * run them; given none it solves on the calling thread, which is what+ * the web build does and must keep doing (a wasm side module has no+ * threads to hand it). A device has cores sitting idle, so the same+ * module builds this pool there instead. The simulation is unchanged+ * either way: Box2D is deterministic under multithreading, and two+ * threads give the same result as eight.+ *+ * Two properties of Box2D's solver dictate the shape:+ *+ * - Enqueue must not run the task. Worker 0 drives the stage sync bits+ * and every other worker spins on them, so a task executed inline+ * would spin against a worker that has not started.+ * - The calling thread IS worker 0, and finishing drains the queue+ * rather than blocking. Box2D enqueues the island split alongside the+ * whole worker set, so a pool that only waits can leave a solver+ * worker queued behind it, never reaching the barrier its peers spin+ * on. Helping also keeps each worker index on exactly one thread at a+ * time, which Box2D requires — indices are its per-worker scratch,+ * and two threads sharing one corrupts the step.+ */+#pragma once++#ifndef __EMSCRIPTEN__++#include <box2d/types.h>++#include <atomic>+#include <condition_variable>+#include <cstdint>+#include <deque>+#include <mutex>+#include <thread>+#include <vector>++namespace esengine::physics {++/**+ * A fixed pool of worker threads Box2D enqueues onto. Not general purpose: it+ * exists to satisfy `b2EnqueueTaskCallback` / `b2FinishTaskCallback`, and its+ * lifetime is the physics world's.+ */+class TaskPool {+public:+ /** Builds a pool sized from the hardware, or an empty one when there is only+ * a single core to schedule on (in which case Box2D solves inline). */+ TaskPool();+ ~TaskPool();++ TaskPool(const TaskPool&) = delete;+ TaskPool& operator=(const TaskPool&) = delete;++ /** How many workers Box2D should split a step across, counting the calling+ * thread; 0 when the pool is inactive and the world stays single-threaded. */+ int workerCount() const { return workerCount_; }++ /** Wire this pool into a world definition. A pool with no workers leaves the+ * definition alone, so the world stays on the calling thread. */+ void configure(b2WorldDef& def);++private:+ /** The handle a caller waits on: the slices of one enqueued task. */+ struct Group {+ std::atomic<int> pending{0};+ /** Groups are pooled and reused; this marks one as available again. */+ bool free = true;+ };++ /** One contiguous slice of a parallel-for, tagged with the group it completes. */+ struct Job {+ b2TaskCallback* fn = nullptr;+ int startIndex = 0;+ int endIndex = 0;+ void* taskContext = nullptr;+ Group* group = nullptr;+ };++ static void* enqueueTask(b2TaskCallback* task, int itemCount, int minRange,+ void* taskContext, void* userContext);+ static void finishTask(void* userTask, void* userContext);++ void* submit(b2TaskCallback* task, int itemCount, int minRange, void* taskContext);+ void wait(Group* group);+ void workerLoop(uint32_t workerIndex);+ Group* acquireGroup();++ int workerCount_ = 0;+ std::vector<std::thread> threads_;+ std::deque<Job> queue_;+ // Groups are pooled rather than allocated per task: a step enqueues on the+ // order of a dozen, every frame, forever.+ std::deque<Group> groups_;+ std::mutex mutex_;+ std::condition_variable queued_;+ bool stopping_ = false;+};++} // namespace esengine::physics++#endif // __EMSCRIPTEN__