From 63b8bc5722f33d82c68ceed582d228e89c1bf45d Mon Sep 17 00:00:00 2001
From: Will Eastcott <will@playcanvas.com>
Date: Sat, 30 May 2026 17:57:20 +0100
Subject: [PATCH] docs: elevate the Entity class reference to peak quality

First page in a page-by-page effort to bring flagship API reference pages up to
the standard already set by the best pages (e.g. GSplatComponent, Vec3).

- Rewrites the Entity class overview into an authored introduction: the mental
  model (a scene-graph node plus a set of components), the two facets it combines
  (transform from GraphNode + components), and the typical workflow
  (addComponent / accessor / removeComponent / enabled / destroy), with tight
  cross-links to Component, GraphNode, AppBase#root and the common components.
- Adds two canonical, runnable class-level `@example`s (create a camera entity
  and add it to the scene; parent/child transform inheritance).
- Fixes an accuracy bug: `findComponent()` was typed `{Component}` but actually
  returns `null` when nothing is found (via `GraphNode#findOne`) - now
  `{Component|null}`.

The 21 component accessors are intentionally left terse, and the other methods
were already at the bar.

Verified: lint clean, docs build with 0 errors and no new warnings, build:types
and test:types pass (`findComponent(type: string): Component | null`).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 src/framework/entity.js | 46 +++++++++++++++++++++++++++++++----------
 1 file changed, 35 insertions(+), 11 deletions(-)

diff --git a/src/framework/entity.js b/src/framework/entity.js
index 544cc250d58..6e84ab5dc56 100644
--- a/src/framework/entity.js
+++ b/src/framework/entity.js
@@ -67,16 +67,40 @@ const releaseTempArray = (a) => {
 };
 
 /**
- * The Entity is a core primitive of a PlayCanvas application. Generally speaking, any object in
- * your application will be represented by an Entity, along with a set of {@link Component}s. Each
- * component enables a particular capability. For example, the {@link RenderComponent} enables an
- * entity to render a 3D model, and the {@link ScriptComponent} enables an entity to run code that
- * implements custom behavior.
+ * An Entity is the core primitive of a PlayCanvas application. Every object in a scene (a camera, a
+ * light, a 3D model, a sound source, a piece of UI, or your own gameplay object) is represented by
+ * an Entity. On its own, an Entity is simply a named node in the scene graph; it gains behavior
+ * from the {@link Component}s attached to it.
  *
- * Entity is a subclass of {@link GraphNode} which allows entities to form a tree-like hierarchy
- * (based on parent/child relationships). The root of the entity hierarchy can be queried with
- * {@link AppBase#root}. Entities inherit a 3D transform from {@link GraphNode} which allows them
- * to be positioned, rotated and scaled.
+ * An Entity therefore brings together two things:
+ *
+ * - A transform: Entity extends {@link GraphNode}, so it has a position, rotation and scale, and
+ * can be parented to other entities to form a hierarchy. The root of that hierarchy is
+ * {@link AppBase#root}, and child entities inherit the transforms of their ancestors.
+ * - A set of components: each {@link Component} adds a single capability. For example, a
+ * {@link CameraComponent} renders the scene, a {@link LightComponent} lights it, a
+ * {@link RenderComponent} draws a 3D mesh, and a {@link ScriptComponent} runs your own code.
+ *
+ * Add a capability with {@link Entity#addComponent}, access it later through the matching property
+ * (such as {@link Entity#camera} or {@link Entity#render}), and remove it with
+ * {@link Entity#removeComponent}. An entity, together with all of its descendants and their
+ * components, can be enabled or disabled as a group via {@link GraphNode#enabled}, and removed from
+ * the scene with {@link Entity#destroy}.
+ *
+ * @example
+ * // Create an entity, give it a camera component, position it, and add it to the scene
+ * const camera = new pc.Entity('camera');
+ * camera.addComponent('camera', {
+ *     clearColor: new pc.Color(0.1, 0.1, 0.1)
+ * });
+ * camera.setPosition(0, 0, 10);
+ * app.root.addChild(camera);
+ * @example
+ * // Entities form a hierarchy: a child inherits its parent's transform
+ * const parent = new pc.Entity('parent');
+ * const child = new pc.Entity('child');
+ * parent.addChild(child);
+ * parent.setLocalPosition(5, 0, 0); // moves both parent and child
  */
 class Entity extends GraphNode {
     /**
@@ -417,8 +441,8 @@ class Entity extends GraphNode {
      * Search the entity and all of its descendants for the first component of specified type.
      *
      * @param {string} type - The name of the component type to retrieve.
-     * @returns {Component} A component of specified type, if the entity or any of its descendants
-     * has one. Returns undefined otherwise.
+     * @returns {Component|null} A component of specified type, if the entity or any of its
+     * descendants has one. Returns null otherwise.
      * @example
      * // Get the first found light component in the hierarchy tree that starts with this entity
      * const light = entity.findComponent("light");