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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file PhysXWorld.hpp
* @brief The one 3D world the PhysX backend steps.
* @details The second implementation of Physics3DBindings.hpp, beside the Jolt
* one. The SDK cannot tell them apart by their entry points; what
* differs is the solver, which here is set up the way Unity sets up
* the same PhysX: projected Gauss-Seidel, patch friction, Average
* combine, a 0.01 m contact offset, a 2 m/s bounce threshold, a 0.005
* sleep energy, six position and one velocity iterations, and a
* maximum angular velocity of 50 rad/s. A scene authored against
* Unity's defaults lands on the same numbers.
*
* Bodies are named by small integers the module hands out, the way
* Jolt's BodyIDs are; a PhysX actor pointer never crosses to the SDK.
*
* @author ESEngine Team
* @date 2026
*
* @copyright Copyright (c) 2026 ESEngine Team
* Licensed under the Apache License, Version 2.0.
*/
#pragma once
#include <PxPhysicsAPI.h>
#include <cstdint>
#include <memory>
#include <unordered_map>
#include <vector>
#ifdef __EMSCRIPTEN__
#include <emscripten/emscripten.h>
#else
#define EMSCRIPTEN_KEEPALIVE
#endif
namespace esengine::physics3d_physx {
/// Sixteen layers, the same number the Jolt backend and the 2D world name.
constexpr uint32_t LAYER_COUNT = 16;
/// Filter data words. word0 holds the layer INDEX rather than its bit, so the
/// shader reads the live matrix, the same matrix Jolt consults per pair.
enum FilterWord : uint32_t { kLayerWord = 0, kKindWord = 1 };
/// kKindWord bits.
constexpr uint32_t KIND_CHARACTER = 1u;
/// What the module knows about a body beyond what PhysX holds.
struct Body {
uint32_t id = 0;
uint32_t entity = 0;
uint32_t layer = 0;
physx::PxRigidActor* actor = nullptr;
bool sensor = false;
bool character = false;
/// PhysX has no per-body gravity factor, only on or off. A body whose scale
/// is not 1 has gravity off and is given `g * scale` as an acceleration
/// before every substep, which is the same integral.
float gravityScale = 1.0f;
/// A kinematic body moves by the velocity it was given, the way a Jolt one
/// does; PhysX moves a kinematic body only to a target, set every substep.
physx::PxVec3 kinematicVelocity{0.0f};
bool hasKinematicVelocity = false;
};
struct Character {
physx::PxController* controller = nullptr;
uint32_t entity = 0;
uint32_t layer = 0;
/// The vertical speed between moves; a controller does not fall on its own.
float verticalSpeed = 0.0f;
bool grounded = false;
physx::PxVec3 groundNormal{0.0f, 1.0f, 0.0f};
float pushForce = 0.0f;
float mass = 70.0f;
/** The actors it touched after its last move, so a meeting is told once, not every move it lasts. */
std::vector<const physx::PxRigidActor*> touching;
std::unique_ptr<Body> body; // the kinematic actor's record, so hits name the entity
};
/// Which PxJoint an entity's component made, so a motor or a reading knows what
/// it is holding without RTTI.
enum class JointKind : uint8_t { Point, Hinge, Slider, Distance, Fixed, SwingTwist, SixDOF };
struct Joint {
physx::PxJoint* joint = nullptr;
JointKind kind = JointKind::Fixed;
/// A slider's motor force, kept so turning the motor back on restores it.
float maxForce = 0.0f;
};
struct World {
physx::PxScene* scene = nullptr;
physx::PxDefaultCpuDispatcher* dispatcher = nullptr;
physx::PxControllerManager* controllers = nullptr;
uint32_t masks[LAYER_COUNT];
std::unordered_map<uint32_t, std::unique_ptr<Body>> bodies;
uint32_t nextBodyId = 1;
std::unordered_map<uint32_t, std::unique_ptr<Character>> characters;
uint32_t nextCharacterId = 1;
std::unordered_map<uint32_t, Joint> joints;
/// Materials keyed by (friction, restitution): a scene of a thousand crates
/// shares one, as a Unity scene shares its default material.
std::unordered_map<uint64_t, physx::PxMaterial*> materials;
std::vector<float> transformBuffer;
std::vector<float> queryBuffer;
std::vector<float> contactEnterBuffer;
/** One closing speed for each contact in contactEnterBuffer. */
std::vector<float> contactEnterSpeedBuffer;
/** One meeting mass, in kilograms, for each contact in contactEnterBuffer. */
std::vector<float> contactEnterMassBuffer;
/** What characters ran into, ten floats a meeting; read after the step, emptied by the next step's first move. */
std::vector<float> characterHitBuffer;
bool characterHitsStale = false;
std::vector<float> contactExitBuffer;
std::vector<float> sensorEnterBuffer;
std::vector<float> sensorExitBuffer;
World() { for (uint32_t& m : masks) m = 0xFFFFFFFFu; }
bool isValid() const { return scene != nullptr; }
bool collide(uint32_t a, uint32_t b) const {
if (a >= LAYER_COUNT || b >= LAYER_COUNT) return false;
return (masks[a] & (1u << b)) != 0 && (masks[b] & (1u << a)) != 0;
}
Body* body(uint32_t id) {
auto found = bodies.find(id);
return found == bodies.end() ? nullptr : found->second.get();
}
};
World& world();
physx::PxPhysics& physics();
/// Friction 0.6, no bounce: Unity's default physics material.
physx::PxMaterial* defaultMaterial();
/// The entity an actor speaks for, or 0.
inline uint32_t entityOf(const physx::PxActor* actor) {
if (actor == nullptr || actor->userData == nullptr) return 0;
return static_cast<const Body*>(actor->userData)->entity;
}
} // namespace esengine::physics3d_physx