Method addComponent

packages/core/src/ECS/Entity.ts:454–499

* @zh 添加组件到实体 * @en Add component to entity * * @param component - @zh 要添加的组件实例 @en Component instance to add * @returns @zh 添加的组件实例 @en Added component instance * @throws @zh 如果实体已存在该类型的组件 @en If entity already has this component type * * @example * ```typesc

(component: T)

     * ```
     */
    public addComponent<T extends Component>(component: T): T {
        const componentType = component.constructor as ComponentType<T>;

        if (!this.scene) {
            throw new Error(
                'Entity must be added to Scene before adding components. Use scene.createEntity() instead of new Entity()'
            );
        }

        if (!this.scene.componentStorageManager) {
            throw new Error('Scene does not have componentStorageManager');
        }

        if (this.hasComponent(componentType)) {
            throw new Error(`Entity ${this.name} already has component ${getComponentTypeName(componentType)}`);
        }

        this.addComponentInternal(component);

        this.scene.componentStorageManager.addComponent(this.id, component);

        component.entityId = this.id;
        this.scene.referenceTracker?.registerEntityScene(this.id, this.scene);

        if (this.scene.isEditorMode) {
            this.scene.queueDeferredComponentCallback(() => component.onAddedToEntity());
        } else {
            component.onAddedToEntity();
        }

        if (this.scene.eventSystem) {
            this.scene.eventSystem.emitSync('component:added', {
                timestamp: Date.now(),
                source: 'Entity',
                entityId: this.id,
                entityName: this.name,
                entityTag: this.tag?.toString(),
                componentType: getComponentTypeName(componentType),
                component: component
            });
        }

        this.notifyQuerySystems(componentType);

        return component;
    }

    /**
     * @zh 获取指定类型的组件