Skip to content

Tree-shakable engine features #10055

Open

Description

@mvaligursky

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 AppBase always 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 Webgl or Webgpu suffix.
  • 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

Activity

  1. willeastcott commented on Nov 16, 2026

    @willeastcott
    Contributor

    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 / Webgpu suffix makes app setup more verbose, and easier to get wrong, than it needs to be.

    What worries me about the suffix

    • The device is chosen twice, once in createGraphicsDevice and again on every feature name, and the two can disagree. createGraphicsDevice always appends WebGL2 as a fallback, so a list of ...Webgpu features can end up running on a WebGL2 device.
    • A mixed list is possible (featureLitWebgl with featureShadowsWebgpu), which is a new kind of bug.
    • An app that supports both devices names every feature twice, and the "everything" case, which is the most common one, is the longest line.

    Suggestion: one entry point per device, same feature names in each

    playcanvas keeps both languages. playcanvas/webgl and playcanvas/webgpu export the same API with the features bound to one language.

    // WebGL application with shadows and localization
    import { App, featureStandard, featureShadows, featureI18n } from 'playcanvas/webgl';
    options.features = [featureStandard, featureShadows, featureI18n];
    
    // WebGPU-only Gaussian splat viewer
    import { App, featureGsplat } from 'playcanvas/webgpu';
    options.features = [featureGsplat];
    
    // Everything, both devices
    import { App, featuresAll } from 'playcanvas';
    options.features = featuresAll;
    • The device is chosen once, in the import path, so a mismatched list can't be written.
    • The same source builds for either device by changing (or aliasing) one specifier.
    • Each device entry can also export a createGraphicsDevice bound 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:

    App Entry Bundle contains
    splat viewer /webgpu gsplat code, gsplat WGSL
    standard + shadows + i18n /webgl that code, lit/standard/shadows GLSL
    shadows only root shadows code, shadows GLSL and WGSL
    featuresAll root everything

    Smaller points

    • Let features declare what they require. featureStandard brings in lit, so an app lists only the features it would name.
    • One list rather than six. +1 to folding componentSystems, resourceHandlers, lightmapper, batchManager and xr into features. The gsplat and particle systems already register their own chunks, so the unit already exists there.
    • featuresAll as 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.
    • Help with choosing the list. A missing feature only reports in debug builds, so a release build just renders wrong. It would help if a debug build running with featuresAll could report the features that were never used, so trimming the list isn't trial and error.
    • Keep the number of features small. Each one is permanent API and a new way for an app to fail. I'd only split out pieces that carry shader chunks or a meaningful amount of code.

    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.

  2. mvaligursky commented on Nov 18, 2026

    @mvaligursky
    ContributorAuthor

    v3: app.i18n becomes nullable

    Localization is moving behind a device-independent i18n feature (PR to follow). In v2 the application installs it, so app.i18n keeps its I18n type 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.i18n changes from I18n to I18n | null, so code using it needs a null check (app.i18n?.locale) or has to install the feature.
    • app.i18n is created when the application is initialized rather than when it is constructed (already the case in v2 after this change).
    • Text elements and localized assets keep working without the feature, using the default locale. Localized text (ElementComponent#key) and localization assets in the application properties need the feature, and report it with a debug assert.
  3. mvaligursky commented on Nov 19, 2026

    @mvaligursky
    ContributorAuthor

    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.

  4. mvaligursky commented on Nov 19, 2026

    @mvaligursky
    ContributorAuthor

    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 create StandardMaterial today.

  5. mvaligursky commented on Nov 19, 2026

    @mvaligursky
    ContributorAuthor

    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.

    featureLighting
    ├─ featureLights
    │  ├─ featureDirectionalLights
    │  │  └─ featureDirectionalShadows       (PCF included)
    │  │     ├─ featureDirectionalPcss
    │  │     └─ featureDirectionalVsm
    │  ├─ featureLocalLights                 clustered, WebGL and WebGPU      ┐ one of these
    │  │  ├─ featureLocalShadows             PCF                              │
    │  │  └─ featureCookies                                                   │
    │  ├─ featureLocalLightsNonClustered     WebGL only                       ┘
    │  │  └─ featureLocalShadowsNonClustered PCF, PCSS, VSM (spot)
    │  └─ featureAreaLights
    ├─ featureEnvLightingGeneration          runtime prefiltering of environment lighting
    └─ featureLightmapper
    
    • Directional lights work without any local lights feature, so an application with only directional lights does not include the code and shaders of omni and spot lights.
    • Local lights are either clustered or non-clustered, and an application includes one of them. WebGPU supports clustered lighting only, so featureLocalLightsNonClustered and its children are exported from playcanvas/webgl only, and the installed local lights feature decides the lighting mode.
    • PCSS and VSM shadows of directional lights are optional leaves; PCF is part of the shadows feature itself. Clustered local shadows support PCF only, so PCSS and VSM of local lights belong to the non-clustered branch.
    • Shared code, such as the shadow rendering used by both directional and local shadows, is an internal feature the leaves depend on, and is not part of the public tree.
    • Each node has the same public name on both device entry points; internally a node with shader chunks has a variant per device, so an application only includes the shaders of its device.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    V3Work for V3 engine

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions