@eigong/three-effekseer

@eigong/three-effekseer is a WebGPU add-on that integrates Effekseer into a patched Three.js WebGPU renderer.

Install

npm install three@npm:@eigong/[email protected] @eigong/three-effekseer

Version Baseline

This add-on is currently based on Effekseer 1.80 b2. The required Three.js baseline is @eigong/[email protected].

Requirements

• The local Three.js fork must expose the external render pass hook implemented in:
  • WebGPURenderer.js
  • WebGPUBackend.js
• The Effekseer WebGPU runtime must already be loaded in the page.

Canonical Example

The canonical consumer of the add-on is the vanilla example:

• HTML entry: vanilla/index.html
• Integration: vanilla-main.ts

The React example in ThreeEffekseerCanvas.tsx consumes the same add-on, but it is not the reference integration.

Public API

import { EffekseerRenderPass } from '@eigong/three-effekseer'

const pass = new EffekseerRenderPass(
  renderer,
  scene,
  camera,
  ctx,
  { mode: 'composite', colorBufferMode: 'ldr', idleOptimization: true }
)

const capabilities = pass.getCapabilities()

This mirrors the WebGL-side integration format by exposing a dedicated EffekseerRenderPass on the Three side while keeping the Effekseer context external.

mode defaults to 'basic'. In mode: 'composite', colorBufferMode defaults to 'ldr'. idleOptimization defaults to true.

When idleOptimization is enabled, the add-on skips Effekseer work when no active effects are detected and falls back to rendering the Three scene only.

Modes

| Mode | Distortion | Depth Occlusion | Soft Particles | LOD | Collisions | Notes | | --- | --- | --- | --- | --- | --- | --- | | basic | No | Yes | No | No | No | Effekseer is injected into the primary scene render pass. Lowest-overhead path, but it inherits the parent pass format. | | composite | Yes | Yes | Yes | No | No | Uses scene capture for background refraction, converts scene depth into an intermediate float texture for soft particles, renders the scene again into a composite target, then presents through RenderPipeline. |

Color Buffer Mode

• auto
  • Uses the renderer output buffer type for the composite target.
• ldr
  • Composite mode only.
  • Forces the Effekseer composite target to RGBAFormat + UnsignedByteType, matching an explicit LDR color path.
  • This is the WebGPU-side equivalent of running Effekseer against an LDR color target instead of inheriting the renderer HDR type.

If colorBufferMode is omitted in mode: 'composite', the add-on now uses the ldr path by default.

colorBufferMode does not apply to basic. In basic, Effekseer renders directly inside the parent Three render pass, so the effective color/depth/sample format is whatever that parent pass already uses. That means:

• if the parent pass is LDR, Effekseer also runs in LDR
• if the parent pass is HDR or 16-bit, Effekseer also runs in that HDR/16-bit pass

So basic is still the lowest-overhead integration path, but it is not guaranteed to be cheaper than composite with ldr in cases where the parent Three pass is using a more expensive format.

Idle Optimization

With idleOptimization: true:

• basic keeps renderer.render(scene, camera) active, but skips effekseer.update(...), the external render pass hook, and drawExternal(...) while idle.
• composite falls back to renderer.render(scene, camera) while idle and skips effekseer.update(...), sceneCaptureTrigger.render(), softParticleDepthCaptureTrigger.render(), compositePresenter.render(...), and the final presenter pass.

The tracker watches handles returned by ctx.playEffect(...) and ctx.play(...) when available, and falls back to runtime metrics such as getTotalParticleCount() when the runtime exposes them.

Unsupported Features

• Soft particles in basic: not supported. The external render pass hook in the current Three fork does not expose a sampleable scene depth texture for the primary scene pass.
• LOD: not supported. The add-on does not currently provide a Three-side feature contract for effect level-of-detail selection.
• Collisions: not supported. The add-on does not currently bridge Three scene collision data or collision callbacks into Effekseer.

Soft Particles

composite mode does not forward Three's raw DepthTexture directly to Effekseer. Instead, it renders the scene pass depth into an intermediate sampleable float color texture and then forwards that texture to Effekseer through depthTextureView.

If the scene pass does not expose a depth texture, or if the intermediate float depth capture cannot be produced for the current backend/format, the add-on silently falls back to rendering Effekseer without soft particles for that frame.