hytopia/docs/server.entity.md

The HYTOPIA SDK makes it easy for developers to create massively multiplayer games using JavaScript or TypeScript.

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [server](./server.md) &gt; [Entity](./server.entity.md)

## Entity class

Represents a dynamic or static object in a world.

When to use: any non-player object that needs physics, visuals, or interactions. Do NOT use for: player-controlled avatars (use `PlayerEntity` / `DefaultPlayerEntity`<!-- -->). Do NOT use for: voxel blocks (use block APIs on `ChunkLattice`<!-- -->).

**Signature:**

```typescript
export default class Entity extends RigidBody implements protocol.Serializable 
```
**Extends:** [RigidBody](./server.rigidbody.md)

**Implements:** protocol.Serializable

## Remarks

Entities are created from a block texture or a `.gltf` model and can have rigid bodies, colliders, animations, and controllers.

<h2>Coordinate System</h2>

HYTOPIA uses a right-handed coordinate system where: - \*\*+X\*\* is right - \*\*+Y\*\* is up - \*\*-Z\*\* is forward (identity orientation)

Models should be authored with their front/forward facing the \*\*-Z axis\*\*. When an entity has identity rotation (0,0,0,1 quaternion or yaw=0), it faces -Z.

<h2>Events</h2>

This class is an EventRouter, and instances of it emit events with payloads listed under `EntityEventPayloads`<!-- -->.

## Example


```typescript
const spider = new Entity({
  name: 'Spider',
  modelUri: 'models/spider.gltf',
  rigidBodyOptions: {
    type: RigidBodyType.DYNAMIC,
    enabledRotations: { x: false, y: true, z: false },
    colliders: [
      {
        shape: ColliderShape.ROUND_CYLINDER,
        borderRadius: 0.1,
        halfHeight: 0.225,
        radius: 0.5,
        tag: 'body',
      }
    ],
  },
});

spider.spawn(world, { x: 20, y: 6, z: 10 });
```
\*\*Category:\*\* Entities

## Constructors

<table><thead><tr><th>

Constructor


</th><th>

Modifiers


</th><th>

Description


</th></tr></thead>
<tbody><tr><td>

[(constructor)(options)](./server.entity._constructor_.md)


</td><td>


</td><td>

Creates a new Entity instance.

Use for: defining a new entity before spawning it into a world. Do NOT use for: player-controlled avatars (use `PlayerEntity` or `DefaultPlayerEntity`<!-- -->).


</td></tr>
</tbody></table>

## Properties

<table><thead><tr><th>

Property


</th><th>

Modifiers


</th><th>

Type


</th><th>

Description


</th></tr></thead>
<tbody><tr><td>

[availableModelAnimationNames](./server.entity.availablemodelanimationnames.md)


</td><td>

`readonly`


</td><td>

Readonly&lt;string\[\]&gt;


</td><td>

The names of the animations available in the entity's model.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[availableModelNodeNames](./server.entity.availablemodelnodenames.md)


</td><td>

`readonly`


</td><td>

Readonly&lt;string\[\]&gt;


</td><td>

The names of the nodes available in the entity's model.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[blockHalfExtents](./server.entity.blockhalfextents.md)


</td><td>

`readonly`


</td><td>

[Vector3Like](./server.vector3like.md) \| undefined


</td><td>

The half extents of the block entity's visual size.


</td></tr>
<tr><td>

[blockTextureUri](./server.entity.blocktextureuri.md)


</td><td>

`readonly`


</td><td>

string \| undefined


</td><td>

The texture URI for block entities.


</td></tr>
<tr><td>

[controller](./server.entity.controller.md)


</td><td>

`readonly`


</td><td>

[BaseEntityController](./server.baseentitycontroller.md) \| undefined


</td><td>

The controller for the entity.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[depth](./server.entity.depth.md)


</td><td>

`readonly`


</td><td>

number


</td><td>

The depth (Z-axis) of the entity's model or block size.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[emissiveColor](./server.entity.emissivecolor.md)


</td><td>

`readonly`


</td><td>

[RgbColor](./server.rgbcolor.md) \| undefined


</td><td>

The emissive color of the entity.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[emissiveIntensity](./server.entity.emissiveintensity.md)


</td><td>

`readonly`


</td><td>

number \| undefined


</td><td>

The emissive intensity of the entity.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[height](./server.entity.height.md)


</td><td>

`readonly`


</td><td>

number


</td><td>

The height (Y-axis) of the entity's model or block size.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[id](./server.entity.id.md)


</td><td>

`readonly`


</td><td>

number \| undefined


</td><td>

The unique identifier for the entity.


</td></tr>
<tr><td>

[isBlockEntity](./server.entity.isblockentity.md)


</td><td>

`readonly`


</td><td>

boolean


</td><td>

Whether this entity is a block entity.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[isEnvironmental](./server.entity.isenvironmental.md)


</td><td>

`readonly`


</td><td>

boolean


</td><td>

Whether the entity is environmental.


</td></tr>
<tr><td>

[isModelEntity](./server.entity.ismodelentity.md)


</td><td>

`readonly`


</td><td>

boolean


</td><td>

Whether this entity is a model entity.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[isSpawned](./server.entity.isspawned.md)


</td><td>

`readonly`


</td><td>

boolean


</td><td>

Whether the entity is spawned in a world.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[modelAnimations](./server.entity.modelanimations.md)


</td><td>

`readonly`


</td><td>

Readonly&lt;[EntityModelAnimation](./server.entitymodelanimation.md)<!-- -->\[\]&gt;


</td><td>

The animations of the entity's model that have been accessed or configured.


</td></tr>
<tr><td>

[modelNodeOverrides](./server.entity.modelnodeoverrides.md)


</td><td>

`readonly`


</td><td>

Readonly&lt;[EntityModelNodeOverride](./server.entitymodelnodeoverride.md)<!-- -->\[\]&gt;


</td><td>

The node overrides of the entity's model that have been accessed or configured.


</td></tr>
<tr><td>

[modelPreferredShape](./server.entity.modelpreferredshape.md)


</td><td>

`readonly`


</td><td>

[ColliderShape](./server.collidershape.md) \| undefined


</td><td>

The preferred collider shape when auto-generating colliders from the model.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[modelScale](./server.entity.modelscale.md)


</td><td>

`readonly`


</td><td>

[Vector3Like](./server.vector3like.md)


</td><td>

The scale of the entity's model.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[modelScaleInterpolationMs](./server.entity.modelscaleinterpolationms.md)


</td><td>

`readonly`


</td><td>

number \| undefined


</td><td>

The interpolation time in milliseconds applied to model scale changes.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[modelTextureUri](./server.entity.modeltextureuri.md)


</td><td>

`readonly`


</td><td>

string \| undefined


</td><td>

The texture URI that overrides the model entity's default texture.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[modelUri](./server.entity.modeluri.md)


</td><td>

`readonly`


</td><td>

string \| undefined


</td><td>

The URI or path to the `.gltf` model asset.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[name](./server.entity.name.md)


</td><td>

`readonly`


</td><td>

string


</td><td>

The name of the entity.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[opacity](./server.entity.opacity.md)


</td><td>

`readonly`


</td><td>

number


</td><td>

The opacity of the entity between 0 and 1.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[outline](./server.entity.outline.md)


</td><td>

`readonly`


</td><td>

[Outline](./server.outline.md) \| undefined


</td><td>

The outline rendering options for the entity.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[parent](./server.entity.parent.md)


</td><td>

`readonly`


</td><td>

[Entity](./server.entity.md) \| undefined


</td><td>

The parent entity, if attached.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[parentNodeName](./server.entity.parentnodename.md)


</td><td>

`readonly`


</td><td>

string \| undefined


</td><td>

The parent model node name, if attached.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[positionInterpolationMs](./server.entity.positioninterpolationms.md)


</td><td>

`readonly`


</td><td>

number \| undefined


</td><td>

The interpolation time in milliseconds applied to position changes.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[rotationInterpolationMs](./server.entity.rotationinterpolationms.md)


</td><td>

`readonly`


</td><td>

number \| undefined


</td><td>

The interpolation time in milliseconds applied to rotation changes.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[tag](./server.entity.tag.md)


</td><td>

`readonly`


</td><td>

string \| undefined


</td><td>

An arbitrary identifier tag for your own logic.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[tintColor](./server.entity.tintcolor.md)


</td><td>

`readonly`


</td><td>

[RgbColor](./server.rgbcolor.md) \| undefined


</td><td>

The tint color of the entity.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[width](./server.entity.width.md)


</td><td>

`readonly`


</td><td>

number


</td><td>

The width (X-axis) of the entity's model or block size.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[world](./server.entity.world.md)


</td><td>

`readonly`


</td><td>

[World](./server.world.md) \| undefined


</td><td>

The world the entity is in, if spawned.

\*\*Category:\*\* Entities


</td></tr>
</tbody></table>

## Methods

<table><thead><tr><th>

Method


</th><th>

Modifiers


</th><th>

Description


</th></tr></thead>
<tbody><tr><td>

[clearModelNodeOverrides()](./server.entity.clearmodelnodeoverrides.md)


</td><td>


</td><td>

Clears all model node overrides from the entity's model.

\*\*Category:\*\* Entities


</td></tr>
<tr><td>

[despawn()](./server.entity.despawn.md)


</td><td>


</td><td>

Despawns the entity and all children from the world.

Use for: removing entities from the world. Do NOT use for: temporary hiding; consider visibility or animations instead.


</td></tr>
<tr><td>

[getModelAnimation(name)](./server.entity.getmodelanimation.md)


</td><td>


</td><td>

Gets or lazily creates a model animation for the entity's model by name.


</td></tr>
<tr><td>

[getModelNodeOverride(nameMatch)](./server.entity.getmodelnodeoverride.md)


</td><td>


</td><td>

Gets or lazily creates a model node override for the entity's model.


</td></tr>
<tr><td>

[interact(player, raycastHit)](./server.entity.interact.md)


</td><td>


</td><td>

Triggers an interaction on the entity from a player.

Use for: programmatic interactions that should mimic a player click/tap. Do NOT use for: server-only effects without player context.


</td></tr>
<tr><td>

[removeModelNodeOverride(nameMatch)](./server.entity.removemodelnodeoverride.md)


</td><td>


</td><td>

Removes a model node override from the entity's model.


</td></tr>
<tr><td>

[removeModelNodeOverrides(nameMatches)](./server.entity.removemodelnodeoverrides.md)


</td><td>


</td><td>

Removes multiple model node overrides from the entity's model.


</td></tr>
<tr><td>

[setBlockTextureUri(blockTextureUri)](./server.entity.setblocktextureuri.md)


</td><td>


</td><td>


</td></tr>
<tr><td>

[setEmissiveColor(emissiveColor)](./server.entity.setemissivecolor.md)


</td><td>


</td><td>

Sets the emissive color of the entity.

Use for: glow effects or highlighted states.


</td></tr>
<tr><td>

[setEmissiveIntensity(emissiveIntensity)](./server.entity.setemissiveintensity.md)


</td><td>


</td><td>

Sets the emissive intensity of the entity.


</td></tr>
<tr><td>

[setModelScale(modelScale)](./server.entity.setmodelscale.md)


</td><td>


</td><td>

Sets the scale of the entity's model and proportionally scales its colliders.


</td></tr>
<tr><td>

[setModelScaleInterpolationMs(interpolationMs)](./server.entity.setmodelscaleinterpolationms.md)


</td><td>


</td><td>

Sets the interpolation time in milliseconds applied to model scale changes.


</td></tr>
<tr><td>

[setModelTextureUri(modelTextureUri)](./server.entity.setmodeltextureuri.md)


</td><td>


</td><td>

Sets the texture uri of the entity's model. Setting this overrides the model's default texture.


</td></tr>
<tr><td>

[setOpacity(opacity)](./server.entity.setopacity.md)


</td><td>


</td><td>

Sets the opacity of the entity.


</td></tr>
<tr><td>

[setOutline(outline, forPlayer)](./server.entity.setoutline.md)


</td><td>


</td><td>

Sets the outline rendering options for the entity.


</td></tr>
<tr><td>

[setParent(parent, parentNodeName, position, rotation)](./server.entity.setparent.md)


</td><td>


</td><td>

Sets the parent of the entity and resets this entity's position and rotation.


</td></tr>
<tr><td>

[setPositionInterpolationMs(interpolationMs)](./server.entity.setpositioninterpolationms.md)


</td><td>


</td><td>

Sets the interpolation time in milliseconds applied to position changes.


</td></tr>
<tr><td>

[setRotationInterpolationMs(interpolationMs)](./server.entity.setrotationinterpolationms.md)


</td><td>


</td><td>

Sets the interpolation time in milliseconds applied to rotation changes.


</td></tr>
<tr><td>

[setTintColor(tintColor)](./server.entity.settintcolor.md)


</td><td>


</td><td>

Sets the tint color of the entity.


</td></tr>
<tr><td>

[spawn(world, position, rotation)](./server.entity.spawn.md)


</td><td>


</td><td>

Spawns the entity in the world.

Use for: placing the entity into a world so it simulates and syncs to clients. Do NOT use for: reusing a single entity instance across multiple worlds.


</td></tr>
<tr><td>

[stopAllModelAnimations(exclusionFilter)](./server.entity.stopallmodelanimations.md)


</td><td>


</td><td>

Stops all model animations for the entity, optionally excluding the provided animations from stopping.


</td></tr>
<tr><td>

[stopModelAnimations(modelAnimationNames)](./server.entity.stopmodelanimations.md)


</td><td>


</td><td>

Stops the provided model animations for the entity.


</td></tr>
</tbody></table>