Update toSaveString and clone options

Author: mdingena

docs/Prefab.md

@@ -20,7 +20,7 @@
   - [`addComponent(component)`](#addcomponentcomponent)
   - [`addEntity(entity)`](#addentityentity)
   - [`addGift(giftPrefab)`](#addgiftgiftprefab)
-  - [`clone()`](#clone)
+  - [`clone(options?)`](#cloneoptions)
   - [`getAngularVelocity()`](#getangularvelocity)
   - [`getChildPrefab(prefabName, parentHash?)`](#getchildprefabprefabname-parenthash)
   - [`getComponentVersions()`](#getcomponentversions)
@@ -61,7 +61,7 @@
   - [`setSpawnArea(populationDefinitionArg, props?)`](#setspawnareapopulationarg-props)
   - [`setVelocity(velocity)`](#setvelocityvelocity)
   - [`toBinary(componentVersions)`](#tobinarycomponentversions)
-  - [`toSaveString(force?)`](#tosavestringforce)
+  - [`toSaveString(options?)`](#tosavestringoptions)
 
 ## Types
 
@@ -472,10 +472,11 @@ box.addGift(gift);
 
 ---
 
-### `clone()`
+### `clone(options?)`
 
 Returns a deep clone of the prefab.
 
+- `options` (optional, default `{}`) See [`toSaveString(options?)`](#tosavestringoptions).
 - Returns: `<Prefab>`
 
 ```ts
@@ -1192,11 +1193,13 @@ const binaryString = prefab.toBinary(componentVersions);
 
 ---
 
-### `toSaveString(excludeComponentVersions?)`
+### `toSaveString(options?)`
 
-Returns the `SaveString` to spawn this prefab in the game. You may pass a boolean to force returning a save string for prefabs that contain indeterminate component versions.
+Returns the `SaveString` to spawn this prefab in the game. You may pass additional options to change the output behaviour.
 
-- `excludeComponentVersions` (optional, default `false`) `<boolean>` Set to true to force a save string without component versions.
+- `options` (optional, default `{}`) `<ToSaveStringOptions>`
+- `options.excludeComponentVersions` (optional, default `false`) Set to true to force a save string without component versions.
+- `options.ignoreIndeterminateComponentVersions` (optional, default `false`) Same as `excludeComponentVersions` but only when encountering indeterminate component versions.
 - Returns: [`<SaveString>`](./SaveString.md)
 
 ```ts

src/Prefab.test.ts

@@ -2175,10 +2175,11 @@ describe('Prefab.toSaveString()', () => {
       });
     });
 
-    describe('when excluding component versions', () => {
+    describe('when ignoring indeterminate component versions', () => {
       it('returns a save string without component versions', () => {
         const prefab = new Prefab('Torch', {
           components: {
+            NetworkRigidbody: new NetworkRigidbodyComponent({ version: 1 }),
             Unknown: [
               new UnsupportedComponent({
                 hash: 1337,
@@ -2190,9 +2191,31 @@ describe('Prefab.toSaveString()', () => {
           }
         });
 
-        const saveString = prefab.toSaveString(true);
+        const saveString = prefab.toSaveString({
+          ignoreIndeterminateComponentVersions: true
+        });
+
+        expect(saveString).toStrictEqual(
+          '56698,116,56698,0,0,0,0,0,0,1065353216,1065353216,2290978823,418,0,0,0,0,0,0,1065353216,0,0,0,0,0,0,334,1073741829,1036795904,0,0,'
+        );
+      });
+    });
+
+    describe('when excluding component versions', () => {
+      it('returns a save string without component versions', () => {
+        const prefab = new Prefab('Torch', {
+          components: {
+            NetworkRigidbody: new NetworkRigidbodyComponent({ version: 1 })
+          }
+        });
+
+        const saveString = prefab.toSaveString({
+          excludeComponentVersions: true
+        });
 
-        expect(saveString).toStrictEqual('56698,56,56698,0,0,0,0,0,0,1065353216,1065353216,1337,20,4147183616,0,0,');
+        expect(saveString).toStrictEqual(
+          '56698,108,56698,0,0,0,0,0,0,1065353216,1065353216,2290978823,418,0,0,0,0,0,0,1065353216,0,0,0,0,0,0,0,0,0,'
+        );
       });
     });
   });

src/Prefab.ts

@@ -45,6 +45,11 @@ type PrefabHash<TPrefabName extends ATTPrefabName> = (typeof ATTPrefabs)[TPrefab
 
 type PrefabName<TPrefabName extends ATTPrefabName> = (typeof ATTPrefabs)[TPrefabName]['name'];
 
+type ToSaveStringOptions = {
+  excludeComponentVersions?: boolean | undefined;
+  ignoreIndeterminateComponentVersions?: boolean | undefined;
+};
+
 export type PrefabProps<TPrefabName extends ATTPrefabName> = {
   position?: Position | undefined;
   rotation?: Rotation | undefined;
@@ -548,8 +553,8 @@ export class Prefab<TPrefabName extends ATTPrefabName = ATTPrefabName> {
    * const cloneMaterial = clone.getMaterial();
    * // `cloneMaterial` is `56394` (Gold)
    */
-  clone(): Prefab<PrefabName<TPrefabName>> {
-    return Prefab.fromSaveString<PrefabName<TPrefabName>>(this.toSaveString());
+  clone(options: ToSaveStringOptions = {}): Prefab<PrefabName<TPrefabName>> {
+    return Prefab.fromSaveString<PrefabName<TPrefabName>>(this.toSaveString(options));
   }
 
   /**
@@ -1714,8 +1719,8 @@ export class Prefab<TPrefabName extends ATTPrefabName = ATTPrefabName> {
   }
 
   /**
-   * Returns the `SaveString` to spawn this prefab in the game. You may pass a boolean to force
-   * returning a save string for prefabs that contain indeterminate component versions.
+   * Returns the `SaveString` to spawn this prefab in the game. You may pass additional options to
+   * change the output behaviour.
    *
    * @example
    * import { Prefab } from 'att-string-transcoder';
@@ -1724,13 +1729,13 @@ export class Prefab<TPrefabName extends ATTPrefabName = ATTPrefabName> {
    *
    * const saveString = prefab.toSaveString();
    */
-  toSaveString(excludeComponentVersions = false): SaveString {
+  toSaveString(options: ToSaveStringOptions = {}): SaveString {
     const componentVersions = this.getComponentVersions();
     const data = this.toBinary(componentVersions);
 
     const hasIndeterminateVersions = [...componentVersions.values()].includes(0);
 
-    if (hasIndeterminateVersions && !excludeComponentVersions) {
+    if (hasIndeterminateVersions && !options.ignoreIndeterminateComponentVersions) {
       throw new Error(
         'Prefab contains components with version `0`. Current in-game versions for those components are not available. The produced save string will not contain component versions and may not be spawnable in-game.\n\nYou may call `.toSaveString(true)` to force producing a save string with this limitation.\n'
       );
@@ -1759,7 +1764,7 @@ export class Prefab<TPrefabName extends ATTPrefabName = ATTPrefabName> {
     }
 
     /* Return SaveString. */
-    const strings = [binaryDataString, componentVersionsString].filter(Boolean);
+    const strings = [binaryDataString, !options.excludeComponentVersions && componentVersionsString].filter(Boolean);
     return `${strings.join(',|')},` as SaveString;
   }
 }