Entity.md

Class: Entity

• Types
  • <EntityFromBinaryProps>
  • <EntityProps>
• Constructors
  • new Entity(key, props?)
  • Entity.fromBinary(reader, props)
• Properties
  • hash
  • name
  • isAlive
  • components
• Methods
  • addComponent(component)
  • getMaterial()
  • removeAllComponents()
  • removeComponent(componentArg)
  • setMaterial(materialArg)
  • toBinary(componentVersions)
  • write(writer, componentVersions)

Types

<EntityFromBinaryProps>

A configuration object to pass to the fromBinary constructor. Lets you instantiate an Entity from reading its binary data.

type EntityFromBinaryProps = {
  key: string;
  hash: number;
  componentVersions?: Map<number, number> | undefined;
};

• key EntityKey The key (${name}_${hash}) of the entity.
• hash <number> The hash of the entity.
• componentVersions (optional) <Map<number, number>> A map of component versions to assume are encoded in the binary data.

---

<EntityProps>

A configuration object to optionally pass to the Entity constructor. Lets you instantiate an Entity with predefined data. Any properties that you do not pass will be created with a default value.

type EntityProps = {
  hash?: number | undefined;
  isAlive?: boolean | undefined;
  components?: (SupportedPrefabComponents & UnsupportedPrefabComponents & Partial<UnknownPrefabComponents>) | undefined;
};

• hash (optional) <number> The hash of the entity.
• isAlive (optional, default true) <boolean> Whether ATT considers this entity "alive".
• components (optional) <PrefabComponents> A mapped object of components on the entity.

Constructors

new Entity(key, props?)

Creates a new Entity object configured with the passed in configuration.

• key EntityKey The key (${name}_${hash}) of the entity.
• props (optional) <EntityProps> Additional configuration of the entity to create.
• Returns: <Entity>

import { Entity } from 'att-string-transcoder';

const torchFireEntity = new Entity<'Torch'>('Fire_30100', {
  hash: 30100,
  isAlive: true,
  components: {}
});

⚠️ This argument must be passed with at least the hash property when manually creating an unrecognised entity.

import { Entity } from 'att-string-transcoder';

const torchUnknownEntity = new Entity<'Torch'>('Unknown', { hash: 1337 });

---

Entity.fromBinary(reader, props)

Reads the binary string data and returns an instantiated entity.

• reader BinaryReader The BinaryReader instance containing the entity binary data.
• props <EntityFromBinaryProps> The configuration for interpreting the binary data.

import { Entity } from 'att-string-transcoder';

const torchFireEntity = Entity.fromBinary<'Torch'>(binaryReader, { key, hash });

Properties

Note that the following properties are sorted in order of appearance when decoding entity binary data.

hash

The hash of the entity.

• <number> The hash of the entity.

import { Entity } from 'att-string-transcoder';

const entity = new Entity<'Torch'>('Fire_30100');

const hash = entity.hash;
// `hash` is `30100`

---

name

The name of the entity.

• <string> The name of the entity.

import { Entity } from 'att-string-transcoder';

const entity = new Entity<'Torch'>('Fire_30100');

const name = entity.name;
// `name` is `'Fire'`

---

isAlive

The alive state of the entity.

• <boolean> The alive state of the entity.

import { Entity } from 'att-string-transcoder';

const entity = new Entity<'Torch'>('Fire_30100');

const isAlive = entity.isAlive;
// `isAlive` is `true`

---

components

Provides access to the components stored in this entity. Components are keyed to their respective names, unless its data contained an unrecognised hash. In that case, the component will be stored in an array under the Unknown key.

• <PrefabComponents> A map of the stored components.

import { Entity } from 'att-string-transcoder';

const entity = new Entity<'Torch'>('Fire_30100');

const components = entity.components;
// `components` is `{ Unknown: [] }`

Methods

addComponent(component)

Adds a Component to the entity. Will override any existing component with that name.

• component <Component> The component to set on the entity.
• Returns: <this>

import { Entity, PhysicalMaterialPartComponent, PhysicalMaterialPartHash } from 'att-string-transcoder';

const entity = new Entity<'Standard_Side_Pouch_Attachment'>('standard_sidePouch_backPin_L1_7968');
const component = new PhysicalMaterialPartComponent({ version: 1, materialHash: PhysicalMaterialPartHash.Iron });

entity.addComponent(component);

---

getMaterial()

Gets the entity's physical material.

• Returns: <PhysicalMaterialPartHash>

import { Entity, PhysicalMaterialPartHash } from 'att-string-transcoder';

const entity = new Entity<'Standard_Side_Pouch_Attachment'>('standard_sidePouch_backPin_L1_7968');

const materialHash = entity.getMaterial();
const materialName = PhysicalMaterialPartHash[materialHash];

---

removeAllComponents()

Removes all components on this entity.

• Returns: <this>

import { Entity } from 'att-string-transcoder';

const entity = new Entity<'Standard_Side_Pouch_Attachment'>('standard_sidePouch_backPin_L1_7968');

entity.removeAllComponents();

---

removeComponent(componentArg)

Removes the specified component from this entity.

• componentArg <ComponentHash | keyof Omit<PrefabComponents, 'Unknown'>> The component's hash or name to remove from this entity.
• Returns: <this>

import { ComponentHash, Entity } from 'att-string-transcoder';

const entity = new Entity<'Standard_Side_Pouch_Attachment'>('standard_sidePouch_backPin_L1_7968');

entity.removeComponent(ComponentHash.NetworkRigidbody);
// or
entity.removeComponent('NetworkRigidbody');

---

setMaterial(materialArg)

Sets the entity's physical material. This can change both its appearance and other qualities such as durability, damage, heat retention and weight.

• materialArg <PhysicalMaterialPartHash | keyof typeof PhysicalMaterialPartHash> The physical material's hash or name to set on the entity.
• Returns: <this>

import { Entity, PhysicalMaterialPartHash } from 'att-string-transcoder';

const entity = new Entity<'Standard_Side_Pouch_Attachment'>('standard_sidePouch_backPin_L1_7968');

entity.setMaterial(PhysicalMaterialPartHash.Mythril);
// or
entity.setMaterial('Mythril');

---

toBinary(componentVersions)

Returns a BinaryString representation of the entity.

• componentVersions <Map<number, number>> A map of component versions to ensure are encoded in the binary data.
• Returns: <BinaryString>

import { ComponentHash, Entity } from 'att-string-transcoder';

const torchFireEntity = new Entity<'Torch'>('Fire_30100');

const componentVersions = new Map<number, number>([
  [ComponentHash.NetworkRigidbody, 1],
  [ComponentHash.PhysicalMaterialPart, 1],
  [ComponentHash.Pickup, 2]
  // etc...
]);

const binaryString = torchFireEntity.toBinary(componentVersions);

---

write(writer, componentVersions)

Writes a BinaryString representation of the entity to the given BinaryWriter, including the entity hash and data length.

• writer <BinaryWriter> The BinaryWriter instance in which to store the binary data.
• componentVersions <Map<number, number>> A map of component versions to ensure are encoded in the binary data.
• Returns: <void>

import { BinaryWriter, ComponentHash, Entity } from 'att-string-transcoder';

const torchFireEntity = new Entity<'Torch'>('Fire_30100');

const componentVersions = new Map<number, number>([
  [ComponentHash.NetworkRigidbody, 1],
  [ComponentHash.PhysicalMaterialPart, 1],
  [ComponentHash.Pickup, 2]
  // etc...
]);

const writer = new BinaryWriter();

torchFireEntity.write(writer, componentVersions);