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.

perf(physics): solve across worker threads on a device

esengineb53db87df664
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 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.cpp
src/esengine/bindings/PhysicsJoints.cpp
src/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.cpp
src/esengine/bindings/PhysicsJoints.cpp
src/esengine/bindings/PhysicsQueries.cpp
+ src/esengine/bindings/PhysicsTaskPool.cpp
)
target_link_libraries(physics_side_module PRIVATE box2d)
target_include_directories(physics_side_module PRIVATE
diff --git a/native/CMakeLists.txt b/native/CMakeLists.txt
index 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.cpp
index 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);
+#endif
g_ctx.worldId = b2CreateWorld(&worldDef);
b2World_SetPreSolveCallback(g_ctx.worldId, preSolveOneWayPlatform, nullptr);
diff --git a/src/esengine/bindings/PhysicsTaskPool.cpp b/src/esengine/bindings/PhysicsTaskPool.cpp
new file mode 100644
index 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.hpp
new file mode 100644
index 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__