playcanvas / playcanvas/engine
Complete deprecated API refactoring and remove deprecated.js
Open
@willeastcott is already working on this.
Since Aug 29, 2026.
- Dominant language
- JavaScript
- Stars
- 16.8k
- Forks
- 2k
- Avg merge
- 4h 32m
- Merged PRs (30d)
- 222
Description
Goal
Remove src/deprecated/deprecated.js and its side-effect import model while preserving compatibility that is still within its deprecation period.
This follows the pattern established by #6900 and continued by #9083, #9084, and #9085: functional compatibility members belong with their owning implementation, remain undocumented, and emit Debug.deprecated. Shims whose original functionality has already been removed should be reviewed by age and usage and deleted once they no longer justify a compatibility presence.
Remaining work
Exported aliases and constants
- Review and relocate or remove the legacy pixel-format and blend-mode aliases.
- Review the
CHUNKAPI_*version constants. - Review the
Key,Node, andLitOptionsaliases. - Review the legacy input event constants.
- Review the legacy rigid-body constants.
Standalone compatibility helpers
- Review the primitive mesh helpers (
createSphere,createPlane,createBox,createTorus,createCapsule,createCone, andcreateCylinder). - Review
createMesh. - Review
drawFullscreenQuad.
Class-owned compatibility members
- Move or remove the remaining material compatibility members on
Material,StandardMaterial, andStandardMaterialOptions. - Move or remove
AssetRegistry#getAssetById. - Move or remove the
XrInputSourcealiases (ray,position, androtation). - Move or remove the
ElementInput#wheelandMouseEvent#wheelaliases. - Move or remove the remaining
AppBasefullscreen and scene-loading helpers. - Move or remove
ModelComponent#setVisible. - Move or remove the remaining
RigidBodyComponentandRigidBodyComponentSystemaliases.
Cases requiring a specific decision
- Decide how to handle the global
shaderChunksproxy, which relies on the current application and cannot simply become an owner-class member. - Decide whether to retain or remove
ForwardRenderer#renderComposition; moving its current implementation intoForwardRendererwould introduce a forbidden scene-to-framework dependency. - Coordinate removal or migration of
Material#blend, which is still used by the Editor. - Review the dynamically generated
StandardMaterialOptionsproxies and replace them with owner-local compatibility without adding runtime reflection or unnecessary generated code. - Audit the already-removed
Material#shaderand StandardMaterial tint shims against removal date and Engine/Examples/Editor usage. - Decide whether silent aliases such as
StandardMaterial#shininessandStandardMaterial#useGammaTonemapshould gain diagnostics, remain temporarily silent, or be removed.
Final cleanup
- Confirm remaining aliases are not used by Engine, Examples, Editor, or supported downstream tooling before removal.
- Remove
export * from ./deprecated/deprecated.jsfromsrc/index.js. - Remove the deprecated module entry from
package.json#sideEffects. - Delete
src/deprecated/deprecated.jsand the directory if empty. - Verify ESM tree-shaking no longer retains compatibility code through side effects.
- Run lint, type generation/tests, documentation generation, and relevant unit tests.
Compatibility policy
- Keep deprecated functionality for the required compatibility window.
- Put functional deprecated members on their owning classes without JSDoc so they do not reappear in the API reference.
- Use
Debug.deprecatedonly for shims that still perform their original function. - Delete sufficiently old no-op or
Debug.removedshims after checking Engine, Examples, and Editor usage. - Avoid new cross-layer dependencies while relocating compatibility code.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.