@blamnetwork/blf 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/helpers/convert_reach_gametype.js

@@ -1,53 +1,50 @@
 /**
- * Convert game variants between Halo Reach TU1 and MCC builds.
+ * Convert game variants between Halo: Reach TU1 (Xbox 360) and MCC.
  *
- * JSON-clone the variant, reject MCC-only megalo features, remap what moved
- * between builds, then write the four top-level fields onto `to`.
+ * Cross-build conversion uses AutoMapper (`@automapper/core` + `@automapper/classes`)
+ * with profiles registered from the source instance graph, then applies build-specific
+ * remaps in place on the mapped target instances.
  *
- * Differences handled here:
- * - MCC-only: temporary explicit refs, `<<=`, `>>=`
- * - `set_to_absolute` exists in both builds but moved (TU1 = 10, MCC = 12)
- * - Survival: unrelated fields — MCC→TU1 sets `m_campaign_difficulty_level` to 1;
- *   TU1→MCC sets `m_encoding_version` to 2; `m_additional_flags` only on MCC
+ * TU1 → MCC is always possible for supported variant kinds (custom / survival).
+ * MCC → TU1 rejects MCC-only megalo features and fails when temporary object,
+ * player, or team references cannot be mapped onto free global slots.
  */
 import { e_game_mode as e_game_mode_tu1, } from "../blam/haloreach/v12065_11_08_24_1738_tu1actual/game/c_game_variant";
-import { e_math_operation as e_math_operation_tu1 } from "../blam/haloreach/v12065_11_08_24_1738_tu1actual/game/megalogamengine/megalogamengine_actions";
-import { c_game_variant as c_game_variant_mcc, e_game_mode as e_game_mode_mcc, } from "../blam/haloreach_mcc/v_untracked_25_08_19_1352/game/c_game_variant";
-import { e_math_operation as e_math_operation_mcc } from "../blam/haloreach_mcc/v_untracked_25_08_19_1352/game/megalogamengine/megalogamengine_actions";
-import { e_explicit_object_type as e_explicit_object_type_mcc } from "../blam/haloreach_mcc/v_untracked_25_08_19_1352/game/megalogamengine/megalogamengine_explicit_object";
-import { e_explicit_player_type as e_explicit_player_type_mcc } from "../blam/haloreach_mcc/v_untracked_25_08_19_1352/game/megalogamengine/megalogamengine_explicit_player";
-import { e_explicit_team_type as e_explicit_team_type_mcc } from "../blam/haloreach_mcc/v_untracked_25_08_19_1352/game/megalogamengine/megalogamengine_explicit_team";
+import { e_explicit_object_type as e_explicit_object_type_tu1 } from "../blam/haloreach/v12065_11_08_24_1738_tu1actual/game/megalogamengine/megalogamengine_explicit_object";
+import { e_explicit_player_type as e_explicit_player_type_tu1 } from "../blam/haloreach/v12065_11_08_24_1738_tu1actual/game/megalogamengine/megalogamengine_explicit_player";
+import { e_explicit_team_type as e_explicit_team_type_tu1 } from "../blam/haloreach/v12065_11_08_24_1738_tu1actual/game/megalogamengine/megalogamengine_explicit_team";
+import { c_custom_variable_reference as c_custom_variable_reference_tu1 } from "../blam/haloreach/v12065_11_08_24_1738_tu1actual/game/megalogamengine/megalogamengine_references";
+import { c_game_variant as c_game_variant_mcc, e_game_mode as e_game_mode_mcc, } from "../blam/haloreach_mcc/v_untracked_25_08_16_1352/game/c_game_variant";
+import { e_action_type as e_action_type_mcc, e_math_operation as e_math_operation_mcc, } from "../blam/haloreach_mcc/v_untracked_25_08_16_1352/game/megalogamengine/megalogamengine_actions";
+import { e_explicit_object_type as e_explicit_object_type_mcc } from "../blam/haloreach_mcc/v_untracked_25_08_16_1352/game/megalogamengine/megalogamengine_explicit_object";
+import { e_explicit_player_type as e_explicit_player_type_mcc } from "../blam/haloreach_mcc/v_untracked_25_08_16_1352/game/megalogamengine/megalogamengine_explicit_player";
+import { e_explicit_team_type as e_explicit_team_type_mcc } from "../blam/haloreach_mcc/v_untracked_25_08_16_1352/game/megalogamengine/megalogamengine_explicit_team";
+import { c_custom_variable_reference as c_custom_variable_reference_mcc } from "../blam/haloreach_mcc/v_untracked_25_08_16_1352/game/megalogamengine/megalogamengine_references";
 import { BlfError } from "../error";
-/** MCC math ops with no TU1 equivalent (`<<=`, `>>=`). */
+import { mccToTu1Mapper, tu1ToMccMapper } from "./reach_gametype_automap";
+import { map_reach_gametype_mcc_to_tu1, map_reach_gametype_tu1_to_mcc, } from "./reach_gametype_automapper";
+import { e_reach_gametype_conversion_error } from "./reach_gametype_conversion_error";
+export { e_reach_gametype_conversion_error } from "./reach_gametype_conversion_error";
 const MCC_ONLY_MATH_OPS = [
     e_math_operation_mcc.shift_left_with,
     e_math_operation_mcc.shift_right_with,
 ];
-/** TU1 survival `m_campaign_difficulty_level` when converting from MCC. */
+const MCC_ONLY_ACTION_TYPES = [
+    e_action_type_mcc.begin,
+    e_action_type_mcc.hs_function_call,
+    e_action_type_mcc.get_button_time,
+    e_action_type_mcc.team_set_vehicle_spawning,
+    e_action_type_mcc.player_set_vehicle_spawning,
+    e_action_type_mcc.set_player_respawn_vehicle,
+    e_action_type_mcc.set_team_respawn_vehicle,
+    e_action_type_mcc.hide_object,
+];
 const TU1_SURVIVAL_CAMPAIGN_DIFFICULTY = 1;
-/** MCC survival `m_encoding_version` when converting from TU1. */
 const MCC_SURVIVAL_ENCODING_VERSION = 2;
-// ---------------------------------------------------------------------------
-// JSON helpers
-// ---------------------------------------------------------------------------
-const JSON_BIGINT_TAG = "__bigint__";
-function json_clone(value) {
-    return JSON.parse(JSON.stringify(value, (_key, v) => typeof v === "bigint" ? { [JSON_BIGINT_TAG]: v.toString() } : v), (_key, v) => v !== null &&
-        typeof v === "object" &&
-        JSON_BIGINT_TAG in v &&
-        typeof v[JSON_BIGINT_TAG] === "string"
-        ? BigInt(v[JSON_BIGINT_TAG])
-        : v);
-}
-function write_game_variant_json(to, data) {
-    to.m_game_engine = data.m_game_engine;
-    to.m_campaign_variant = data.m_campaign_variant;
-    to.m_custom_variant = data.m_custom_variant;
-    to.m_survival_variant = data.m_survival_variant;
-}
-// ---------------------------------------------------------------------------
-// Tree walk
-// ---------------------------------------------------------------------------
+const HR_GVAR_PREFIX = "$hr_gvar_";
+const MAX_OBJECT_GLOBALS = 16;
+const MAX_PLAYER_GLOBALS = 8;
+const MAX_TEAM_GLOBALS = 8;
 function visit_object_tree(root, fn) {
     if (root === null || typeof root !== "object") {
         return;
@@ -64,133 +61,424 @@ function visit_object_tree(root, fn) {
         visit_object_tree(value, fn);
     }
 }
-function remap_set_to_absolute_mcc_to_tu1(root) {
+function remap_temporary_explicit_refs(root, maps) {
     visit_object_tree(root, (obj) => {
-        if (obj.m_operation === e_math_operation_mcc.set_to_absolute) {
-            obj.m_operation = e_math_operation_tu1.set_to_absolute;
+        const objectType = obj.m_explicit_object_type;
+        if (typeof objectType === "number" &&
+            objectType >= e_explicit_object_type_mcc.temporary_0 &&
+            objectType <= e_explicit_object_type_mcc.temporary_7) {
+            const temporaryIndex = objectType - e_explicit_object_type_mcc.temporary_0;
+            const globalIndex = maps.object.get(temporaryIndex);
+            if (globalIndex !== undefined) {
+                obj.m_explicit_object_type =
+                    e_explicit_object_type_tu1.global_0 + globalIndex;
+            }
+        }
+        const playerType = obj.m_explicit_player_type;
+        if (typeof playerType === "number" &&
+            playerType >= e_explicit_player_type_mcc.temporary_0 &&
+            playerType <= e_explicit_player_type_mcc.temporary_2) {
+            const temporaryIndex = playerType - e_explicit_player_type_mcc.temporary_0;
+            const globalIndex = maps.player.get(temporaryIndex);
+            if (globalIndex !== undefined) {
+                obj.m_explicit_player_type =
+                    e_explicit_player_type_tu1.global_0 + globalIndex;
+            }
         }
-        if (obj.m_math_operation === e_math_operation_mcc.set_to_absolute) {
-            obj.m_math_operation = e_math_operation_tu1.set_to_absolute;
+        const teamType = obj.m_explicit_team_type;
+        if (typeof teamType === "number" &&
+            teamType >= e_explicit_team_type_mcc.temporary_0 &&
+            teamType <= e_explicit_team_type_mcc.temporary_5) {
+            const temporaryIndex = teamType - e_explicit_team_type_mcc.temporary_0;
+            const globalIndex = maps.team.get(temporaryIndex);
+            if (globalIndex !== undefined) {
+                obj.m_explicit_team_type =
+                    e_explicit_team_type_tu1.global_0 + globalIndex;
+            }
         }
     });
 }
-function remap_set_to_absolute_tu1_to_mcc(root) {
-    visit_object_tree(root, (obj) => {
-        if (obj.m_operation === e_math_operation_tu1.set_to_absolute) {
-            obj.m_operation = e_math_operation_mcc.set_to_absolute;
+function extend_global_metadata(metadata, maps) {
+    const maxObjectGlobal = Math.max(0, ...maps.object.values());
+    while (metadata.m_object_variables.length <= maxObjectGlobal) {
+        metadata.m_object_variables.push(0);
+    }
+    const maxPlayerGlobal = Math.max(0, ...maps.player.values());
+    while (metadata.m_player_variables.length <= maxPlayerGlobal) {
+        metadata.m_player_variables.push(0);
+    }
+    const maxTeamGlobal = Math.max(0, ...maps.team.values());
+    while (metadata.m_team_variables.length <= maxTeamGlobal) {
+        metadata.m_team_variables.push([0, 0]);
+    }
+}
+function apply_survival_mcc_to_tu1(survival) {
+    if (survival === undefined) {
+        return;
+    }
+    survival.m_campaign_difficulty_level = TU1_SURVIVAL_CAMPAIGN_DIFFICULTY;
+    delete survival.m_encoding_version;
+    delete survival.m_additional_flags;
+}
+function apply_survival_tu1_to_mcc(survival) {
+    if (survival === undefined) {
+        return;
+    }
+    survival.m_encoding_version = MCC_SURVIVAL_ENCODING_VERSION;
+    survival.m_additional_flags = 0;
+    delete survival.m_campaign_difficulty_level;
+}
+function first_localized_string(table) {
+    const value = table?.strings[0]?.[0];
+    if (value === null || value === undefined || value.length === 0) {
+        return;
+    }
+    return value;
+}
+function resolve_hr_gvar_name(value, localized_name) {
+    if (value === undefined || !value.startsWith(HR_GVAR_PREFIX)) {
+        return value ?? "";
+    }
+    const localized = first_localized_string(localized_name);
+    if (localized !== undefined) {
+        return localized;
+    }
+    return value.slice(HR_GVAR_PREFIX.length).replaceAll("_", " ");
+}
+function resolve_hr_gvar_description(value, localized_description) {
+    if (value === undefined || !value.startsWith(HR_GVAR_PREFIX)) {
+        return value ?? "";
+    }
+    return first_localized_string(localized_description) ?? "";
+}
+function apply_mcc_to_tu1_name_description(from, to) {
+    const mccCustom = from.m_custom_variant;
+    const tu1Custom = to.m_custom_variant;
+    if (mccCustom === undefined || tu1Custom === undefined) {
+        return;
+    }
+    const metadata = tu1Custom.m_base_variant.m_metadata;
+    metadata.name = resolve_hr_gvar_name(mccCustom.m_base_variant.m_metadata.name, mccCustom.m_localized_name);
+    metadata.description = resolve_hr_gvar_description(mccCustom.m_base_variant.m_metadata.description, mccCustom.m_localized_description);
+}
+function object_global_index(value) {
+    if (value >= e_explicit_object_type_tu1.global_0 &&
+        value <= e_explicit_object_type_tu1.global_15) {
+        return value - e_explicit_object_type_tu1.global_0;
+    }
+    return;
+}
+function object_temporary_index(value) {
+    if (value >= e_explicit_object_type_mcc.temporary_0 &&
+        value <= e_explicit_object_type_mcc.temporary_7) {
+        return value - e_explicit_object_type_mcc.temporary_0;
+    }
+    return;
+}
+function player_global_index(value) {
+    if (value >= e_explicit_player_type_tu1.global_0 &&
+        value <= e_explicit_player_type_tu1.global_7) {
+        return value - e_explicit_player_type_tu1.global_0;
+    }
+    return;
+}
+function player_temporary_index(value) {
+    if (value >= e_explicit_player_type_mcc.temporary_0 &&
+        value <= e_explicit_player_type_mcc.temporary_2) {
+        return value - e_explicit_player_type_mcc.temporary_0;
+    }
+    return;
+}
+function team_global_index(value) {
+    if (value >= e_explicit_team_type_tu1.global_0 &&
+        value <= e_explicit_team_type_tu1.global_7) {
+        return value - e_explicit_team_type_tu1.global_0;
+    }
+    return;
+}
+function team_temporary_index(value) {
+    if (value >= e_explicit_team_type_mcc.temporary_0 &&
+        value <= e_explicit_team_type_mcc.temporary_5) {
+        return value - e_explicit_team_type_mcc.temporary_0;
+    }
+    return;
+}
+function reserve_metadata_slots(usage, metadata) {
+    for (let i = 0; i < metadata.m_object_variables.length; i++) {
+        usage.object.add(i);
+    }
+    for (let i = 0; i < metadata.m_player_variables.length; i++) {
+        usage.player.add(i);
+    }
+    for (let i = 0; i < metadata.m_team_variables.length; i++) {
+        usage.team.add(i);
+    }
+    for (let i = 0; i < metadata.m_numeric_variables.length; i++) {
+        usage.numeric.add(i);
+    }
+}
+function collect_slot_usage_from_object(obj, globals, temporaries) {
+    const objectType = obj.m_explicit_object_type;
+    if (typeof objectType === "number") {
+        const globalIndex = object_global_index(objectType);
+        if (globalIndex !== undefined) {
+            globals.object.add(globalIndex);
         }
-        if (obj.m_math_operation === e_math_operation_tu1.set_to_absolute) {
-            obj.m_math_operation = e_math_operation_mcc.set_to_absolute;
+        const temporaryIndex = object_temporary_index(objectType);
+        if (temporaryIndex !== undefined) {
+            temporaries.object.add(temporaryIndex);
         }
-    });
+    }
+    const playerType = obj.m_explicit_player_type;
+    if (typeof playerType === "number") {
+        const globalIndex = player_global_index(playerType);
+        if (globalIndex !== undefined) {
+            globals.player.add(globalIndex);
+        }
+        const temporaryIndex = player_temporary_index(playerType);
+        if (temporaryIndex !== undefined) {
+            temporaries.player.add(temporaryIndex);
+        }
+    }
+    const teamType = obj.m_explicit_team_type;
+    if (typeof teamType === "number") {
+        const globalIndex = team_global_index(teamType);
+        if (globalIndex !== undefined) {
+            globals.team.add(globalIndex);
+        }
+        const temporaryIndex = team_temporary_index(teamType);
+        if (temporaryIndex !== undefined) {
+            temporaries.team.add(temporaryIndex);
+        }
+    }
+    if (obj.m_type === 4 && typeof obj.m_variable_index === "number") {
+        globals.numeric.add(obj.m_variable_index);
+    }
 }
-// ---------------------------------------------------------------------------
-// MCC → TU1 compatibility checks
-// ---------------------------------------------------------------------------
-function variant_uses_temporary_explicit_refs(variant) {
-    let found = false;
-    visit_object_tree(variant, (obj) => {
-        if (found) {
+function collect_slot_usage(root) {
+    const globals = {
+        object: new Set(),
+        player: new Set(),
+        team: new Set(),
+        numeric: new Set(),
+    };
+    const temporaries = {
+        object: new Set(),
+        player: new Set(),
+        team: new Set(),
+    };
+    visit_object_tree(root, (obj) => collect_slot_usage_from_object(obj, globals, temporaries));
+    return { globals, temporaries };
+}
+function allocate_global_slot(used, max) {
+    for (let index = 0; index < max; index++) {
+        if (!used.has(index)) {
+            used.add(index);
+            return index;
+        }
+    }
+    return;
+}
+function build_temporary_to_global_maps(globals, temporaries) {
+    const maps = {
+        object: new Map(),
+        player: new Map(),
+        team: new Map(),
+    };
+    for (const temporaryIndex of [...temporaries.object].sort((a, b) => a - b)) {
+        const globalIndex = allocate_global_slot(globals.object, MAX_OBJECT_GLOBALS);
+        if (globalIndex === undefined) {
             return;
         }
-        const team = obj.m_explicit_team_type;
-        if (typeof team === "number" &&
-            team >= e_explicit_team_type_mcc.temporary_0 &&
-            team <= e_explicit_team_type_mcc.temporary_5) {
-            found = true;
+        maps.object.set(temporaryIndex, globalIndex);
+    }
+    for (const temporaryIndex of [...temporaries.player].sort((a, b) => a - b)) {
+        const globalIndex = allocate_global_slot(globals.player, MAX_PLAYER_GLOBALS);
+        if (globalIndex === undefined) {
             return;
         }
-        const player = obj.m_explicit_player_type;
-        if (typeof player === "number" &&
-            player >= e_explicit_player_type_mcc.temporary_0 &&
-            player <= e_explicit_player_type_mcc.temporary_2) {
-            found = true;
+        maps.player.set(temporaryIndex, globalIndex);
+    }
+    for (const temporaryIndex of [...temporaries.team].sort((a, b) => a - b)) {
+        const globalIndex = allocate_global_slot(globals.team, MAX_TEAM_GLOBALS);
+        if (globalIndex === undefined) {
             return;
         }
-        const object = obj.m_explicit_object_type;
-        if (typeof object === "number" &&
-            object >= e_explicit_object_type_mcc.temporary_0 &&
-            object <= e_explicit_object_type_mcc.temporary_7) {
+        maps.team.set(temporaryIndex, globalIndex);
+    }
+    return maps;
+}
+function get_custom_engine_tu1(variant) {
+    return variant.m_custom_variant?.m_game_engine;
+}
+function copy_variable_metadata_mcc_to_tu1(from, to) {
+    to.m_numeric_variables = from.m_numeric_variables.map(([ref, state]) => [
+        mccToTu1Mapper.map(ref, c_custom_variable_reference_mcc, c_custom_variable_reference_tu1),
+        state,
+    ]);
+    to.m_timer_variables = from.m_timer_variables.map((ref) => mccToTu1Mapper.map(ref, c_custom_variable_reference_mcc, c_custom_variable_reference_tu1));
+    to.m_team_variables = from.m_team_variables.map(([value, state]) => [
+        value,
+        state,
+    ]);
+    to.m_player_variables = [...from.m_player_variables];
+    to.m_object_variables = [...from.m_object_variables];
+}
+function copy_variable_metadata_tu1_to_mcc(from, to) {
+    to.m_numeric_variables = from.m_numeric_variables.map(([ref, state]) => [
+        tu1ToMccMapper.map(ref, c_custom_variable_reference_tu1, c_custom_variable_reference_mcc),
+        state,
+    ]);
+    to.m_timer_variables = from.m_timer_variables.map((ref) => tu1ToMccMapper.map(ref, c_custom_variable_reference_tu1, c_custom_variable_reference_mcc));
+    to.m_team_variables = from.m_team_variables.map(([value, state]) => [
+        value,
+        state,
+    ]);
+    to.m_player_variables = [...from.m_player_variables];
+    to.m_object_variables = [...from.m_object_variables];
+}
+function copy_engine_variable_metadata_mcc_to_tu1(from, to) {
+    copy_variable_metadata_mcc_to_tu1(from.m_global_variable_metadata, to.m_global_variable_metadata);
+    copy_variable_metadata_mcc_to_tu1(from.m_player_variable_metadata, to.m_player_variable_metadata);
+    copy_variable_metadata_mcc_to_tu1(from.m_object_variable_metadata, to.m_object_variable_metadata);
+    copy_variable_metadata_mcc_to_tu1(from.m_team_variable_metadata, to.m_team_variable_metadata);
+}
+function copy_engine_variable_metadata_tu1_to_mcc(from, to) {
+    copy_variable_metadata_tu1_to_mcc(from.m_global_variable_metadata, to.m_global_variable_metadata);
+    copy_variable_metadata_tu1_to_mcc(from.m_player_variable_metadata, to.m_player_variable_metadata);
+    copy_variable_metadata_tu1_to_mcc(from.m_object_variable_metadata, to.m_object_variable_metadata);
+    copy_variable_metadata_tu1_to_mcc(from.m_team_variable_metadata, to.m_team_variable_metadata);
+}
+function get_custom_engine(variant) {
+    return variant.m_custom_variant?.m_game_engine;
+}
+function apply_mcc_to_tu1_megalo_remapping(variant, maps) {
+    const engine = variant.m_custom_variant?.m_game_engine;
+    if (!engine) {
+        return;
+    }
+    remap_temporary_explicit_refs(engine, maps);
+    extend_global_metadata(engine.m_global_variable_metadata, maps);
+}
+function variant_uses_mcc_only_math_ops(variant) {
+    let found = false;
+    visit_object_tree(variant, (obj) => {
+        if (found) {
+            return;
+        }
+        const op = obj.m_operation ?? obj.m_math_operation;
+        if (typeof op === "number" && MCC_ONLY_MATH_OPS.includes(op)) {
             found = true;
         }
     });
     return found;
 }
-function variant_uses_mcc_only_math_ops(variant) {
+function variant_uses_mcc_only_action_types(variant) {
     let found = false;
     visit_object_tree(variant, (obj) => {
         if (found) {
             return;
         }
-        const op = obj.m_operation ?? obj.m_math_operation;
-        if (typeof op === "number" && MCC_ONLY_MATH_OPS.includes(op)) {
+        const actionType = obj.m_type;
+        if (typeof actionType === "number" &&
+            MCC_ONLY_ACTION_TYPES.includes(actionType)) {
             found = true;
         }
     });
     return found;
 }
-/** Returns false when MCC features cannot be represented in TU1. */
-function can_convert_mcc_game_variant_to_tu1(from) {
+function plan_temporary_relocation(variant) {
+    const engine = get_custom_engine(variant);
+    if (!engine) {
+        return { object: new Map(), player: new Map(), team: new Map() };
+    }
+    const { globals, temporaries } = collect_slot_usage(engine);
+    reserve_metadata_slots(globals, engine.m_global_variable_metadata);
+    if (temporaries.object.size === 0 &&
+        temporaries.player.size === 0 &&
+        temporaries.team.size === 0) {
+        return { object: new Map(), player: new Map(), team: new Map() };
+    }
+    return build_temporary_to_global_maps(globals, temporaries);
+}
+function check_mcc_game_variant_to_tu1(from) {
+    if (from.m_game_engine === e_game_mode_mcc.sandbox) {
+        return e_reach_gametype_conversion_error.forge_variant;
+    }
+    if (from.m_game_engine === e_game_mode_mcc.campaign) {
+        return e_reach_gametype_conversion_error.campaign_variant;
+    }
     if (from.m_game_engine === e_game_mode_mcc.survival &&
         from.m_survival_variant !== undefined &&
         from.m_survival_variant.m_additional_flags !== 0) {
-        return false;
+        return e_reach_gametype_conversion_error.mcc_survival_additional_flags;
     }
-    if (variant_uses_temporary_explicit_refs(from)) {
-        return false;
+    if (variant_uses_mcc_only_action_types(from)) {
+        return e_reach_gametype_conversion_error.mcc_exclusive_action;
     }
     if (variant_uses_mcc_only_math_ops(from)) {
-        return false;
+        return e_reach_gametype_conversion_error.mcc_exclusive_math_operator;
     }
-    return true;
-}
-// ---------------------------------------------------------------------------
-// Survival (MCC and TU1 use different field names for unrelated data)
-// ---------------------------------------------------------------------------
-function survival_json_mcc_to_tu1(survival) {
-    survival.m_campaign_difficulty_level = TU1_SURVIVAL_CAMPAIGN_DIFFICULTY;
-    survival.m_encoding_version = undefined;
-    survival.m_additional_flags = undefined;
+    if (plan_temporary_relocation(from) === undefined) {
+        return e_reach_gametype_conversion_error.insufficient_global_slots;
+    }
+    return e_reach_gametype_conversion_error.ok;
 }
-function survival_json_tu1_to_mcc(survival) {
-    survival.m_encoding_version = MCC_SURVIVAL_ENCODING_VERSION;
-    survival.m_campaign_difficulty_level = undefined;
-    survival.m_additional_flags = 0;
+function check_tu1_game_variant_to_mcc(from) {
+    if (from.m_game_engine === e_game_mode_tu1.sandbox) {
+        return e_reach_gametype_conversion_error.forge_variant;
+    }
+    if (from.m_game_engine === e_game_mode_tu1.campaign) {
+        return e_reach_gametype_conversion_error.campaign_variant;
+    }
+    return e_reach_gametype_conversion_error.ok;
 }
-// ---------------------------------------------------------------------------
-// Conversion (cross-version only)
-// ---------------------------------------------------------------------------
 function convert_mcc_to_tu1(from, to) {
-    if (!can_convert_mcc_game_variant_to_tu1(from)) {
-        return false;
+    const error = check_mcc_game_variant_to_tu1(from);
+    if (error !== e_reach_gametype_conversion_error.ok) {
+        return error;
+    }
+    const maps = plan_temporary_relocation(from);
+    if (maps === undefined) {
+        return e_reach_gametype_conversion_error.insufficient_global_slots;
     }
-    const data = json_clone(from);
-    remap_set_to_absolute_mcc_to_tu1(data);
-    if (data.m_survival_variant !== undefined) {
-        survival_json_mcc_to_tu1(data.m_survival_variant);
+    const converted = map_reach_gametype_mcc_to_tu1(from);
+    const sourceEngine = get_custom_engine(from);
+    const targetEngine = converted.m_custom_variant?.m_game_engine;
+    if (sourceEngine !== undefined && targetEngine !== undefined) {
+        copy_engine_variable_metadata_mcc_to_tu1(sourceEngine, targetEngine);
     }
-    write_game_variant_json(to, data);
-    return true;
+    apply_mcc_to_tu1_megalo_remapping(converted, maps);
+    apply_mcc_to_tu1_name_description(from, converted);
+    apply_survival_mcc_to_tu1(converted.m_survival_variant);
+    Object.assign(to, converted);
+    return e_reach_gametype_conversion_error.ok;
 }
 function convert_tu1_to_mcc(from, to) {
-    const data = json_clone(from);
-    remap_set_to_absolute_tu1_to_mcc(data);
-    if (data.m_survival_variant !== undefined) {
-        survival_json_tu1_to_mcc(data.m_survival_variant);
+    const error = check_tu1_game_variant_to_mcc(from);
+    if (error !== e_reach_gametype_conversion_error.ok) {
+        return error;
     }
-    write_game_variant_json(to, data);
-    return true;
-}
-export function convert_reach_gametype(from, to) {
-    if (from.m_game_engine === e_game_mode_tu1.sandbox) {
-        throw new BlfError("Forge game variants are not supported. Where did you even get this?");
+    const converted = map_reach_gametype_tu1_to_mcc(from);
+    const sourceEngine = get_custom_engine_tu1(from);
+    const targetEngine = converted.m_custom_variant?.m_game_engine;
+    if (sourceEngine !== undefined && targetEngine !== undefined) {
+        copy_engine_variable_metadata_tu1_to_mcc(sourceEngine, targetEngine);
     }
+    apply_survival_tu1_to_mcc(converted.m_survival_variant);
+    Object.assign(to, converted);
+    return e_reach_gametype_conversion_error.ok;
+}
+function assert_cross_version(from, to) {
     const from_is_mcc = from instanceof c_game_variant_mcc;
     const to_is_mcc = to instanceof c_game_variant_mcc;
     if (from_is_mcc === to_is_mcc) {
         throw new BlfError("convert_reach_gametype only supports cross-version conversion between Reach TU1 and Reach MCC");
     }
-    if (from_is_mcc) {
+}
+export function convert_reach_gametype(from, to) {
+    assert_cross_version(from, to);
+    if (from instanceof c_game_variant_mcc) {
         return convert_mcc_to_tu1(from, to);
     }
     return convert_tu1_to_mcc(from, to);

package/dist/helpers/game_variant_json.d.ts

@@ -0,0 +1,19 @@
+/**
+ * JSON round-trip for game variant class graphs.
+ *
+ * Uses `c.json` when a type is decorated with `@c.struct()`.
+ * Bitstream-decoded game variant types fall back to a cstruct-compatible walk
+ * that preserves numeric enums and serializes bigint values as strings.
+ */
+type JsonRecord = Record<string, unknown>;
+type ClassConstructor = new () => object;
+/** Serialize a game variant instance to a cstruct-compatible JSON object. */
+export declare function variantToJson<T extends object>(ctor: new () => T, instance: T): JsonRecord;
+/** Build a game variant instance from JSON, optionally remapping nested constructors. */
+export declare function variantFromJson<T extends object>(ctor: new () => T, json: JsonRecord, template?: object, ctorMap?: Map<ClassConstructor, ClassConstructor>): T;
+/** Pair same-named exports from two version bundles for cross-build hydration. */
+export declare function buildCrossVersionConstructorMap(sourceModule: Record<string, unknown>, targetModule: Record<string, unknown>): Map<ClassConstructor, ClassConstructor>;
+/** Deep-clone a variant instance through JSON using cstruct-compatible encoding. */
+export declare function cloneVariantViaJson<T extends object>(ctor: new () => T, instance: object, template?: object, ctorMap?: Map<ClassConstructor, ClassConstructor>): T;
+export {};
+//# sourceMappingURL=game_variant_json.d.ts.map

package/dist/helpers/game_variant_json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game_variant_json.d.ts","sourceRoot":"","sources":["../../src/helpers/game_variant_json.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC1C,KAAK,gBAAgB,GAAG,UAAU,MAAM,CAAC;AA0HzC,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAC5C,IAAI,EAAE,UAAU,CAAC,EACjB,QAAQ,EAAE,CAAC,GACV,UAAU,CAKZ;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAC9C,IAAI,EAAE,UAAU,CAAC,EACjB,IAAI,EAAE,UAAU,EAChB,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,GAAE,GAAG,CAAC,gBAAgB,EAAE,gBAAgB,CAAa,GAC3D,CAAC,CAEH;AAED,kFAAkF;AAClF,wBAAgB,+BAA+B,CAC7C,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,GAAG,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAgBzC;AAED,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EAClD,IAAI,EAAE,UAAU,CAAC,EACjB,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,GAAE,GAAG,CAAC,gBAAgB,EAAE,gBAAgB,CAAa,GAC3D,CAAC,CAOH"}