Merge
Functions
merge
▸ merge(oldObject, newTable, traversalDescription, classConstructors?): void
merge takes the values from a new table and recursively merges them into an old object (while
performing appropriate deserialization).
This function is used to merge incoming data from the "save#.dat" file into a mod's variables. Merging is useful instead of blowing away a table entirely because mod code often relies on the local table/object references.
This function always assumes that the new table is serialized data and will attempt to perform
deserialization on the objects within. In other words, unlike the deepCopy function, the
merge function will always operates in the mode of SerializationType.DESERIALIZE. For the
types of objects that will be deserialized, see the documentation for the deepCopy function.
This function does not iterate over the old object, like you would naively expect. This is
because it is common for a variable to have a type of something | null. If this is the case,
the key would not appear when iterating over the old object (because a value of null transpiles
to nil, which means the table key does not exist). Thus, we must instead iterate over the new
object and copy the values backwards. The consequence of this is that merge can copy over old
variables that are no longer used in the code, or copy over old variables of a different type,
which can cause run-time errors. In such cases, users will have to manually delete their save
data.
Parameters
| Name | Type | Description |
|---|---|---|
oldObject | ReadonlyMap<AnyNotNil, unknown> | Readonly<LuaMap<AnyNotNil, unknown>> | ReadonlySet<AnyNotNil> | The old object to merge the values into. This can be either a Lua table, a TSTL map, or a TSTL set. |
newTable | LuaMap<AnyNotNil, unknown> | The new table to merge the values from. This must be a Lua table that represents serialized data. In other words, it should be created with the deepCopy function using SerializationType.SERIALIZE. |
traversalDescription | string | Used to track the current key that we are operating on for debugging purposes. Use a name that corresponds to the name of the merging table. |
classConstructors | LuaMap<string, AnyClass> | Optional. A Lua table that maps the name of a user-defined TSTL class to its corresponding constructor. If the deepCopy function finds any user-defined TSTL classes when recursively iterating through the given object, it will use this map to instantiate a new class. Default is an empty Lua table. |
Returns
void