Add setMaterial helper method

Author: mdingena

docs/Entity.md

@@ -16,6 +16,7 @@
   - [`getMaterial()`](#getmaterial)
   - [`removeAllComponents()`](#removeallcomponents)
   - [`removeComponent(componentArg)`](#removecomponentcomponentarg)
+  - [`setMaterial(materialArg)`](#setmaterialmaterialarg)
   - [`toBinary(componentVersions)`](#tobinarycomponentversions)
   - [`write(writer, componentVersions)`](#writewriter-componentversions)
 
@@ -240,6 +241,25 @@ 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>`](../src/types/PhysicalMaterialPartHash.ts) The physical material's hash or name to set on the entity.
+- Returns: `<this>`
+
+```ts
+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.

src/Entity.test.ts

@@ -359,6 +359,60 @@ describe('Entity.removeComponent()', () => {
   });
 });
 
+describe('Entity.setMaterial()', () => {
+  describe('when given invalid arguments', () => {
+    it('throws an error', () => {
+      const entity = new Entity<'Standard_Side_Pouch_Attachment'>('standard_sidePouch_backPin_L1_7968');
+
+      // @ts-expect-error Passing invalid arguments
+      const expectedToThrow = () => entity.setMaterial();
+      const expectedError = new Error('You must pass a PhysicalMaterialPartHash to set as the material.');
+
+      expect(expectedToThrow).toThrowError(expectedError);
+    });
+  });
+
+  describe('when given a material hash', () => {
+    it('sets the given material', () => {
+      const entity = new Entity<'Standard_Side_Pouch_Attachment'>('standard_sidePouch_backPin_L1_7968');
+
+      entity.setMaterial(PhysicalMaterialPartHash.EvinonSteelAlloy);
+      const materialHash = entity.getMaterial();
+
+      expect(materialHash).toStrictEqual(31502);
+    });
+  });
+
+  describe('when given a material name', () => {
+    it('sets the given material', () => {
+      const entity = new Entity<'Standard_Side_Pouch_Attachment'>('standard_sidePouch_backPin_L1_7968');
+
+      entity.setMaterial('EvinonSteelAlloy');
+      const materialHash = entity.getMaterial();
+
+      expect(materialHash).toStrictEqual(31502);
+    });
+  });
+
+  describe('when the entity already has a PhysicalMaterialPart component', () => {
+    it('sets the given material', () => {
+      const entity = new Entity<'Standard_Side_Pouch_Attachment'>('standard_sidePouch_backPin_L1_7968', {
+        components: {
+          PhysicalMaterialPart: new PhysicalMaterialPartComponent({
+            version: 1,
+            materialHash: PhysicalMaterialPartHash.Gold
+          })
+        }
+      });
+
+      entity.setMaterial(PhysicalMaterialPartHash.EvinonSteelAlloy);
+      const materialHash = entity.getMaterial();
+
+      expect(materialHash).toStrictEqual(31502);
+    });
+  });
+});
+
 describe('Entity.toBinary()', () => {
   it('returns a BinaryString representation of the entity', () => {
     const prefabName = 'Torch';

src/Entity.ts

@@ -9,6 +9,8 @@ import type { UnknownPrefabComponents } from './types/UnknownPrefabComponents.js
 import type { UnsupportedPrefabComponents } from './types/UnsupportedPrefabComponents.js';
 
 import { BinaryWriter } from './BinaryWriter.js';
+import { FALLBACK_PHYSICAL_MATERIAL_PART_VERSION } from './Prefab.js';
+import { PhysicalMaterialPartComponent } from './components/PhysicalMaterialPartComponent.js';
 import { ATTPrefabs } from './types/ATTPrefabs.js';
 import { ComponentHash } from './types/ComponentHash.js';
 import { PhysicalMaterialPartHash } from './types/PhysicalMaterialPartHash.js';
@@ -269,6 +271,40 @@ export class Entity<TPrefabName extends ATTPrefabName> {
     return this;
   }
 
+  /**
+   * Sets the entity's physical material. This can change both its appearance and other qualities such
+   * as durability, damage, heat retention and weight.
+   *
+   * @since v3.1.0
+   *
+   * @example
+   * 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');
+   */
+  setMaterial(materialHash: PhysicalMaterialPartHash): this;
+  setMaterial(materialName: keyof typeof PhysicalMaterialPartHash): this;
+  setMaterial(materialArg: PhysicalMaterialPartHash | keyof typeof PhysicalMaterialPartHash): this {
+    if (typeof materialArg === 'undefined') {
+      throw new Error('You must pass a PhysicalMaterialPartHash to set as the material.');
+    }
+
+    const version = this.components.PhysicalMaterialPart?.version ?? FALLBACK_PHYSICAL_MATERIAL_PART_VERSION;
+    const materialHash = typeof materialArg === 'number' ? materialArg : PhysicalMaterialPartHash[materialArg];
+
+    this.components.PhysicalMaterialPart = new PhysicalMaterialPartComponent({
+      ...this.components.PhysicalMaterialPart,
+      version,
+      materialHash
+    });
+
+    return this;
+  }
+
   /**
    * Returns a `BinaryString` representation of the entity.
    *

src/Prefab.ts

@@ -72,7 +72,7 @@ const FALLBACK_LIQUID_CONTAINER_VERSION =
   constants.latestSupportedComponentVersions.get(ComponentHash.LiquidContainer) ??
   constants.latestLiquidContainerComponentVersion;
 
-const FALLBACK_PHYSICAL_MATERIAL_PART_VERSION =
+export const FALLBACK_PHYSICAL_MATERIAL_PART_VERSION =
   constants.latestSupportedComponentVersions.get(ComponentHash.PhysicalMaterialPart) ??
   constants.latestPhysicalMaterialPartComponentVersion;