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
import type { App } from '../app/app';
import type { Entity } from '../types';
import type { EngineApi } from '../ecs/bridge/engineApi';
import type { CppRegistry } from '../wasm';
import type { Physics2DAPI } from '../physics/Physics2D';
import type { Physics3DQueries } from '../physics3d/Physics3DQueries';
import type { ParticleCollisionBudget, ParticleCollisionEventPayload, ParticleCollisionStats } from './collision';
interface Query { mode: number; mask: number; x: number; y: number; z: number; dx: number; dy: number; dz: number }
interface Hit { body: Entity; x: number; y: number; z: number; nx: number; ny: number; nz: number }
/** null is a miss; undefined means unavailable and explicitly invokes the authored fallback. @internal */
export type ParticleQueryResolver = (query: Query) => Hit | null | undefined;
/** No hard dependency on either optional physics plugin. Their existing APIs own unit conversion. @internal */
export function particleQueryResolver(app: App): ParticleQueryResolver {
return q => {
if (q.mask === 0) return null;
if (q.mode === 1) {
const physics = app.getResourceByName('Physics2D') as Physics2DAPI | null;
if (!physics) return undefined;
const length = Math.hypot(q.dx,q.dy);
if (!length) return null;
const hits = physics.raycast({x:q.x,y:q.y},{x:q.dx/length,y:q.dy/length},length,q.mask);
const hit = hits.find(h=>Number.isFinite(h.fraction) && h.fraction>=0 && h.fraction<=1);
return hit ? {body:hit.entity,x:hit.point.x,y:hit.point.y,z:q.z,nx:hit.normal.x,ny:hit.normal.y,nz:0} : null;
}
if (q.mode === 2) {
const physics = app.getResourceByName('Physics3D') as Physics3DQueries | null;
if (!physics) return undefined;
const hit = physics.raycast({x:q.x,y:q.y,z:q.z},{x:q.dx,y:q.dy,z:q.dz},q.mask);
return hit ? {body:hit.entity,x:hit.x,y:hit.y,z:hit.z,nx:hit.normalX,ny:hit.normalY,nz:hit.normalZ} : null;
}
return undefined;
};
}
/** Same-frame bulk exchange with either a WASM or native core. @internal */
export class ParticleCollisionBridge {
events: ParticleCollisionEventPayload[] = [];
contacts: ParticleCollisionEventPayload[] = [];
debug = false;
stats: ParticleCollisionStats[] = [];
error: string | null = null;
budget: ParticleCollisionBudget = {queries:4096,events:1024};
private updating_ = false;
constructor(private readonly engine_: NonNullable<EngineApi>, private readonly registry_: CppRegistry,
private readonly resolve_?: ParticleQueryResolver) {}
private read_(count: number, words: number, getter: (()=>number) | undefined, max: number): ArrayBuffer | undefined {
if (!Number.isInteger(count) || count < 0 || count > max || !getter) return undefined;
const ptr = getter(), heap = this.engine_.HEAPU8;
if (!heap || !Number.isSafeInteger(ptr) || ptr % 4 !== 0 || (count>0 && ptr===0) || ptr<0 || ptr + count*words*4 > heap.byteLength) return undefined;
return heap.slice(ptr,ptr+count*words*4).buffer;
}
update(dt: number): void {
if (this.updating_) throw new Error('Particle.update cannot re-enter during collision queries');
this.updating_=true;this.events=[];this.contacts=[];this.stats=[];this.error=null;
const e=this.engine_;
try {
e.particle_collisionSetBudget?.(this.budget.queries,this.budget.events,this.debug);
e.particle_update?.(this.registry_,dt);
const count=e.particle_collisionQueryCount?.() ?? 0;
if (count>0 && e.particle_collisionResolve) {
const queries=this.read_(count,10,e.particle_collisionQueries?.bind(e),65536);
let ptr=0;
try {
if (queries && e._malloc && e._free && e.HEAPU8) ptr=e._malloc(count*32);
if (ptr && queries) {
const inputU=new Uint32Array(queries), inputF=new Float32Array(queries);
const replyBuffer=new ArrayBuffer(count*32), replyU=new Uint32Array(replyBuffer), replyF=new Float32Array(replyBuffer);
for(let i=0;i<count;i++) {
const q=i*10,r=i*8;
let hit:Hit|null|undefined;
try {hit=this.resolve_?.({mode:inputU[q+2],mask:inputU[q+3],x:inputF[q+4],y:inputF[q+5],z:inputF[q+6],dx:inputF[q+7],dy:inputF[q+8],dz:inputF[q+9]});}
catch(error){this.error=String(error);hit=undefined;}
replyU[r]=hit===undefined?2:hit===null?0:1;
if(hit){replyU[r+1]=hit.body;replyF.set([hit.x,hit.y,hit.z,hit.nx,hit.ny,hit.nz],r+2);}
}
// A query provider may grow the engine heap. Acquire the current view only AFTER it returns.
e.HEAPU8!.set(new Uint8Array(replyBuffer),ptr);
e.particle_collisionResolve(this.registry_,ptr,count);
} else e.particle_collisionResolve(this.registry_,0,0);
} finally {if(ptr)e._free?.(ptr);}
}
const eventCount=e.particle_collisionEventCount?.() ?? 0;
const events=this.read_(eventCount,14,e.particle_collisionEvents?.bind(e),16384);
if(events){const u=new Uint32Array(events),f=new Float32Array(events);for(let i=0;i<eventCount;i++){const b=i*14;const event={emitter:u[b] as Entity,particle:u[b+1],body:u[b+2] as Entity,mode:u[b+3],x:f[b+4],y:f[b+5],z:f[b+6],normalX:f[b+7],normalY:f[b+8],normalZ:f[b+9],velocityX:f[b+10],velocityY:f[b+11],velocityZ:f[b+12]};this.contacts.push(event);if(u[b+13])this.events.push(event);}}
const statCount=e.particle_collisionStatsCount?.() ?? 0;
const stats=this.read_(statCount,10,e.particle_collisionStats?.bind(e),1000000);
if(stats){const u=new Uint32Array(stats);for(let i=0;i<statCount;i++){const b=i*10;this.stats.push({emitter:u[b] as Entity,queries:u[b+1],hits:u[b+2],budgetSkipped:u[b+3],distanceSkipped:u[b+4],unavailable:u[b+5],events:u[b+6],eventDropped:u[b+7],fallbacks:u[b+8],mode:u[b+9]});}}
} finally {this.updating_=false;}
}
}