<commit_before>---
title: Entity
section_title: Core API
type: core
layout: docs
parent_section: docs
order: 1
section_order: 3
source_code: src/core/a-entity.js
---

[ecs]: ../introduction/entity-component-system.md

A-Frame represents an entity via the `<a-entity>` element. As defined in the
[entity-component-system pattern][ecs], entities are placeholder objects to
which we plug in components to provide them appearance, behavior, and
functionality.

[position]: ../components/position.md
[rotation]: ../components/rotation.md
[scale]: ../components/scale.md

In A-Frame, entities are inherently attached with the [position][position],
[rotation][rotation], and [scale][scale] components.

<!--toc-->

## Example

Consider the entity below. By itself, it has no appearance, behavior, or
functionality. It does nothing:

```html
<a-entity>
```

[geometry]: ../components/geometry.md
[material]: ../components/material.md

We can attach components to it to make it render something or do something. To
give it shape and appearance, we can attach the [geometry][geometry] and
[material][material] components:

```html
<a-entity geometry="primitive: box" material="color: red">
```

[light]: ../components/light.md

Or to make it emit light, we can further attach the [light][light] component:

```html
<a-entity geometry="primitive: box" material="color: red"
          light="type: point; intensity: 2.0">
```

## Retrieving an Entity

We can simply retrieve an entity using DOM APIs.

```html
<a-entity id="mario"></a-entity>
```

```js
var el = document.querySelector('#mario');
```

Once we have an entity, we have access to its properties and methods detailed
below.

## Properties

### `components`

`<a-entity>.components` is an object of components attached to the entity. This
gives us access to the entity's components including each component's data,
state, and methods.

For example, if we wanted to grab an entity's three.js camera object or
material object, we could reach into its components:

```js
var camera = document.querySelector('a-entity[camera]').components.camera.camera;
var material = document.querySelector('a-entity[material]').components.material.material;
```

Or if a component exposes an API, we can call its methods:

```js
document.querySelector('a-entity[sound]').components.sound.pause();
```

### `hasLoaded`

Whether the entity has attached and initialized all of its components. Though
the best way to ensure code is run after the entity is ready is to place code
within a component.

### `isPlaying`

Whether the entity is active and playing. If we pause the entity , then
`isPlaying` becomes `false`.

### `object3D`

[object3d]: http://threejs.org/docs/#Reference/Core/Object3D

`<a-entity>.object3D` is a reference to the entity's [three.js
`Object3D`][object3d] representation. More specifically, `object3D` will be a
`THREE.Group` object that may contain different types of `THREE.Object3D`s such
as cameras, meshes, lights, or sounds:

```js
// Gaining access to the internal three.js scene graph.
var groupObject3D = document.querySelector('a-entity').object3D;
console.log(groupObject3D.parent);
console.log(groupObject3D.children);
```

We can access the different types of `Object3D`s through `object3DMap`.

### `object3DMap`

An entity's `object3DMap` is an object that gives access to the different types
of `THREE.Object3D`s (e.g., camera, meshes, lights, sounds) that components
have set.
<commit_msg>fix: threejs reference (#4809)<commit_after>---
title: Entity
section_title: Core API
type: core
layout: docs
parent_section: docs
order: 1
section_order: 3
source_code: src/core/a-entity.js
---

[ecs]: ../introduction/entity-component-system.md

A-Frame represents an entity via the `<a-entity>` element. As defined in the
[entity-component-system pattern][ecs], entities are placeholder objects to
which we plug in components to provide them appearance, behavior, and
functionality.

[position]: ../components/position.md
[rotation]: ../components/rotation.md
[scale]: ../components/scale.md

In A-Frame, entities are inherently attached with the [position][position],
[rotation][rotation], and [scale][scale] components.

<!--toc-->

## Example

Consider the entity below. By itself, it has no appearance, behavior, or
functionality. It does nothing:

```html
<a-entity>
```

[geometry]: ../components/geometry.md
[material]: ../components/material.md

We can attach components to it to make it render something or do something. To
give it shape and appearance, we can attach the [geometry][geometry] and
[material][material] components:

```html
<a-entity geometry="primitive: box" material="color: red">
```

[light]: ../components/light.md

Or to make it emit light, we can further attach the [light][light] component:

```html
<a-entity geometry="primitive: box" material="color: red"
          light="type: point; intensity: 2.0">
```

## Retrieving an Entity

We can simply retrieve an entity using DOM APIs.

```html
<a-entity id="mario"></a-entity>
```

```js
var el = document.querySelector('#mario');
```

Once we have an entity, we have access to its properties and methods detailed
below.

## Properties

### `components`

`<a-entity>.components` is an object of components attached to the entity. This
gives us access to the entity's components including each component's data,
state, and methods.

For example, if we wanted to grab an entity's three.js camera object or
material object, we could reach into its components:

```js
var camera = document.querySelector('a-entity[camera]').components.camera.camera;
var material = document.querySelector('a-entity[material]').components.material.material;
```

Or if a component exposes an API, we can call its methods:

```js
document.querySelector('a-entity[sound]').components.sound.pause();
```

### `hasLoaded`

Whether the entity has attached and initialized all of its components. Though
the best way to ensure code is run after the entity is ready is to place code
within a component.

### `isPlaying`

Whether the entity is active and playing. If we pause the entity , then
`isPlaying` becomes `false`.

### `object3D`

[object3d]: https://threejs.org/docs/#api/en/core/Object3D

`<a-entity>.object3D` is a reference to the entity's [three.js
`Object3D`][object3d] representation. More specifically, `object3D` will be a
`THREE.Group` object that may contain different types of `THREE.Object3D`s such
as cameras, meshes, lights, or sounds:

```js
// Gaining access to the internal three.js scene graph.
var groupObject3D = document.querySelector('a-entity').object3D;
console.log(groupObject3D.parent);
console.log(groupObject3D.children);
```

We can access the different types of `Object3D`s through `object3DMap`.

### `object3DMap`

An entity's `object3DMap` is an object that gives access to the different types
of `THREE.Object3D`s (e.g., camera, meshes, lights, sounds) that components
have set.

{'fraction_non_alphanumeric': 0.12357606344628695, 'fraction_numerical': 0.006633020908435473, 'mean_word_length': 4.902978723404256, 'pattern_counts': {'":': 0, '<': 21, '<?xml version=': 0, '>': 21, 'https://': 1, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5768051', 'n_tokens_mistral': 2084, 'n_tokens_neox': 1995, 'n_words': 783}