Repository navigation
Description
Problem
An application bundles a lot of engine code and shader source it never uses, and tree-shaking can't remove it:
- Both shading languages ship together. A WebGL-only application still contains every WGSL shader chunk, and a WebGPU-only application every GLSL chunk. In a minimal lit scene (one cube, one light), shader source is about 38% of the bundle, roughly half of it in the unused language.
- Optional features always ship. The renderer always creates the shadow renderers, clustered lighting and the light atlas, and
AppBasealways creates systems like i18n and asset bundles. A scene that casts no shadows still contains about 20 KB of shadow code, plus its shader chunks in both languages.
Proposal
Group optional parts of the engine into features. A feature is an object that brings in everything one piece of functionality needs: its engine code, and its shader chunks if it has any. The application lists the features it uses, and the bundler drops everything else.
- Features with shader chunks or device-specific code exist once per device, with a
WebglorWebgpusuffix. - Features with neither have no suffix.
A WebGL application with shadows and localization:
import { App, featureLitWebgl, featureStandardWebgl, featureShadowsWebgl, featureI18n } from 'playcanvas';
options.features = [featureLitWebgl, featureStandardWebgl, featureShadowsWebgl, featureI18n];A WebGPU-only Gaussian splat viewer, with no lit materials at all:
import { App, featureGsplatWebgpu } from 'playcanvas';
options.features = [featureGsplatWebgpu];Everything, for an application that supports both devices (what Application gives you today):
import { App, featuresAllWebgl, featuresAllWebgpu, featuresAll } from 'playcanvas';
options.features = [...featuresAllWebgl, ...featuresAllWebgpu, ...featuresAll];This would also unify the options that already let an application choose parts of the engine (componentSystems, resourceHandlers, lightmapper, batchManager, xr) into one mechanism. In debug builds, using a feature that wasn't added, for example a light casting shadows without the shadows feature, reports a clear error.
Plan
- Engine v2: restructure the engine internals into features, with no change in behaviour. Every application still gets every feature, so nothing breaks.
- Engine v3: make features a public API on
App(Rename AppBase to App and deprecate Application #9502). This follows the removal of GLSL to WGSL transpilation on WebGPU, so each device feature contains a single shading language. The exact names and how finely features are split will be decided as the work progresses.
Related
- Rename AppBase to App and deprecate Application #9502: rename
AppBasetoAppand deprecateApplication. The aggregates above could answer its open question about an all-in setup without losing tree-shaking. - Area lights: bundle the LTC LUT data with the area lights feature #10075: bundle the area light LTC LUT data with the area lights feature.
- V3: make StandardMaterial an optional feature #10102: make
StandardMaterialan optional feature.
Activity
willeastcott commentedon Nov 16, 2026
The direction is right, and restructuring the internals in v2 with no change in behavior is a safe way to get there. My concern is the v3 public shape: I think the
Webgl/Webgpusuffix makes app setup more verbose, and easier to get wrong, than it needs to be.What worries me about the suffix
createGraphicsDeviceand again on every feature name, and the two can disagree.createGraphicsDevicealways appends WebGL2 as a fallback, so a list of...Webgpufeatures can end up running on a WebGL2 device.featureLitWebglwithfeatureShadowsWebgpu), which is a new kind of bug.Suggestion: one entry point per device, same feature names in each
playcanvaskeeps both languages.playcanvas/webglandplaycanvas/webgpuexport the same API with the features bound to one language.createGraphicsDevicebound to its own device class. Today that function imports all three device classes, so a WebGL-only app still ships the WebGPU device.Each device entry is
export * from './index.js'plus explicit exports of the features for that language (explicit exports take precedence over the star). We already publish unbundled ESM with"sideEffects": false, so the entries share module instances and every class is the same object whichever entry it came from. The typings are the same for all three.I checked the mechanism on a toy package with Rollup 4 and esbuild. Both give the same result:
/webgpu/webglfeaturesAllSmaller points
featureStandardbrings in lit, so an app lists only the features it would name.componentSystems,resourceHandlers,lightmapper,batchManagerandxrinto features. The gsplat and particle systems already register their own chunks, so the unit already exists there.featuresAllas a single name in its own module answers the all-in question in Rename AppBase to App and deprecate Application #9502: only apps that import it pay for it.featuresAllcould report the features that were never used, so trimming the list isn't trial and error.None of this changes the v2 plan. The internal unit (code plus chunks per language) is the same either way; it only affects how v3 exposes it.
feat: Move area lights behind the area lights feature (#10074)
feat: Move asset bundles behind the bundles feature (#10076)
feat: Register particle shader chunks through the particles feature (#…
mvaligursky commentedon Nov 18, 2026
v3:
app.i18nbecomes nullableLocalization is moving behind a device-independent i18n feature (PR to follow). In v2 the application installs it, so
app.i18nkeeps itsI18ntype and always exists once the application is initialized.In v3 an application that does not install the feature has no localization, and this is a breaking change:
app.i18nchanges fromI18ntoI18n | null, so code using it needs a null check (app.i18n?.locale) or has to install the feature.app.i18nis created when the application is initialized rather than when it is constructed (already the case in v2 after this change).ElementComponent#key) and localization assets in the application properties need the feature, and report it with a debug assert.feat: Move localization behind the i18n feature (#10078)
Move directional PCSS behind the directional PCSS feature (#10082)
mvaligursky commentedon Nov 19, 2026
Documentation request from #10090: once features are tree-shakable, document what can be removed and how much each feature costs, ideally as a map of tree-shakeable features and their sizes, so users can see what's worth excluding. This would extend the existing Bundle size page.
feat: Split the shadows feature into directional and local shadows (#…
perf: Keep feature names in debug builds only (#10099)
mvaligursky commentedon Nov 19, 2026
Making
StandardMaterial(and the lit shader code) an optional feature is tracked separately in #10102, as it needs larger changes: the default material, the UI and sprite materials, and the glTF and material asset loaders all createStandardMaterialtoday.mvaligursky commentedon Nov 19, 2026
Lighting feature hierarchy
Features are installed as a tree: installing a node installs all of its children, and a feature also installs the features it depends on. Most applications would install a node near the top, such as
featureLights, and size-sensitive ones pick leaves.featureLocalLightsNonClusteredand its children are exported fromplaycanvas/webglonly, and the installed local lights feature decides the lighting mode.