Rename AppBase to App and deprecate Application

[willeastcott]

Summary

Rename AppBase to App and deprecate both AppBase and Application, so users migrate once, from either old name straight to App.

Motivation

Application has a limitation that can't be fixed. Its constructor is synchronous, so it cannot create a WebGPU device, which requires awaiting createGraphicsDevice. Its JSDoc already tells new code to prefer AppBase and says the class is expected to be deprecated.

First-party code has already moved off it. web-components, supersplat, supersplat-viewer, model-viewer, the Editor and the engine examples (~280 files) all use AppBase. Nothing in the engine repo constructs Application apart from its own definition.

AppBase is the wrong public name. The Base suffix suggests an abstract class meant for subclassing, but it's the class we tell everyone to create an instance of. App is short and easy to guess, and it matches the app variable used everywhere (this.app, pc.app).

Deprecating Application alone would mean migrating twice. Users would move from Application to AppBase now and then again later. The rename and the deprecation should ship in the same release.

Proposal

Next minor release

• Add App as the real class (today's AppBase).
• Keep AppBase as an alias of the same class object, not a subclass, so static methods such as AppBase.getApplication() and instanceof checks keep working.
• Deprecate AppBase and Application with Debug.deprecated warnings.
• Do not add a convenience factory on App itself. A static such as App.create() would make App import every component system and resource handler, so no app could tree-shake them. Whether to offer an all-in helper at all is an open question below.
• Update the JSDoc (~85 {@link AppBase} references), examples and first-party repos to App.

V3

• Remove AppBase and Application. App is the permanent name.
• Don't reuse the name Application. Giving an old name a new constructor would silently break existing new Application(canvas, { mouse }) code. Whether V3 keeps a stub that throws a message pointing to App can be decided when V3 is closer.

Out of scope

• Collapsing the constructor-then-init() pattern into a single step. It's worth discussing, but it's a separate change.

Open questions

• Do Editor-published builds (the published start script and the launcher) still construct pc.Application? This needs checking before we commit to removing it in V3.
• Do we want an all-in async helper at all? If so, it must be a standalone export in its own module (e.g. createApp(canvas, options)), so that only apps that call it pay for the full engine. That is the same trade Application makes today, but WebGPU-capable. The alternative is no helper: the docs and examples show the explicit App setup, which is ~30 lines today (device, AppOptions with systems and handlers, SoundManager, Lightmapper, BatchManager, XrManager).

Related

• Complete deprecated API refactoring and remove deprecated.js #9086 (complete deprecated API refactoring and remove deprecated.js)

[mvaligursky]

Add a short async setup path, e.g. App.create(canvas, options), that creates the device (WebGPU-capable) and registers all component systems and resource handlers by default

that would mean we'd import everything to it, and get no tree-shaking!

[willeastcott]

Good catch, you're right. A static on App would pull every component system and resource handler into every app, which defeats the point of moving off Application. I've taken it out of the proposal.

The one version that keeps tree-shaking is a standalone export in its own module, e.g. createApp(canvas, options). With "sideEffects": false, only apps that import it pay for the full engine. That's the same trade Application makes today, but async, so it could create a WebGPU device. Whether it's worth adding at all, or whether docs and examples showing the explicit setup are enough, is now an open question in the description. The rename and deprecation don't depend on it.