Legacy Cleanup

Legacy Cleanup

Do you need this page? Only if you used Unidentified Items before version 0.1.0. If you started on 0.1.0 or later, there is nothing to clean up — you can ignore this page.

Why this exists

Early versions of the module (before 0.1.0) hid items in a destructive way: when you mystified an item, the module overwrote the item's real name, image, and description directly in the database with the masked values, and stashed the originals in hidden backup flags on the item.

That approach had problems — items stayed renamed even with the module disabled, and it could interfere with other tools that read the item's name or image.

Version 0.1.0 switched to a non-destructive model: the item's real data is never touched, and the mask is applied only at display time. Much cleaner.

Version 0.1.0 also shipped an automatic migration that tried to convert old destructive items to the new model on load. That migration turned out to be unreliable and could leave items in a broken, empty-looking state, so it has been removed entirely — the module no longer changes any of your items automatically on load.

Instead, if you have leftover items from the old versions, you can fix them manually and on your own terms with the cleanup macro below.

What the cleanup macro does

For every item that still carries the old backup flags, the macro:

1. Restores the item's real name, image, and description from the backup flags.
2. Removes all of this module's data (flags.dh-unidentified) from the item.

The result: each affected item is returned to exactly how it was before it was ever mystified — a clean item with no trace of the module on it.

Important properties

• GM-only. Only a Game Master can run it.
• Optional. Nothing forces you to run it; run it if and when you want.
• Irreversible. It asks you to confirm first, then applies the changes. There is no undo, so make a world backup first if you want to be safe.
• Targeted. It only touches items that have the old backup flags. Items you currently keep hidden with the new (0.1.0+) model are left untouched — running the macro will not reveal anything you mystified in the new version.
• Covers your world. It scans both world items (the Items directory) and items owned by actors. It does not modify locked compendiums.

How to run it

1. In Foundry, open the Macros hotbar (bottom of the screen) and click an empty slot to create a new macro.
2. Set the macro Type to Script.
3. Copy the entire macro below and paste it into the command box.
4. Save the macro, then click it to run (as GM).
5. A dialog will tell you how many old items were found. Confirm to apply the cleanup, or cancel to do nothing.

💡 Tip: Make a backup of your world before running it. The change cannot be undone from inside Foundry.

The macro

// ============================================================
// dh-unidentified | Legacy cleanup macro
// Restores items mystified by the OLD destructive model (pre-0.1.0)
// to their original state and removes all module data from them.
//
// GM-only. Optional. Irreversible (a confirmation is shown first).
// New-model unidentified items are left untouched.
// ============================================================

if (!game.user.isGM) {
  ui.notifications.warn("[DH Unidentified] Only the GM can run the legacy cleanup.");
  return;
}

// Resolve the module id from the module's single source of truth.
const { MODULE_ID } = await import("/modules/dh-unidentified/scripts/constants.js");

/**
 * A legacy destructive-model item carries at least one of the real* backup
 * flags. Those are the only items this macro touches.
 */
const isLegacy = (item) => {
  const f = item?.flags?.[MODULE_ID];
  return !!f && (
    f.realName        !== undefined ||
    f.realImg         !== undefined ||
    f.realDescription !== undefined
  );
};

/**
 * Builds the update that restores real fields and strips the whole module
 * namespace. Values are read from the current flags, so deleting the namespace
 * in the same object is safe.
 */
const buildUpdate = (item) => {
  const f = item.flags[MODULE_ID];
  const u = { _id: item.id };
  if (f.realName        !== undefined) u.name = f.realName;
  if (f.realImg         !== undefined) u.img  = f.realImg;
  if (f.realDescription !== undefined) u["system.description"] = f.realDescription;
  // Remove the entire dh-unidentified flag namespace from the item.
  u[`flags.-=${MODULE_ID}`] = null;
  return u;
};

// ── Collect affected items ──
// World-level items in one batch; actor-embedded items grouped per parent actor.
const worldUpdates = game.items.contents.filter(isLegacy).map(buildUpdate);

const actorItemUpdates = new Map(); // actorId -> update[]
for (const actor of game.actors.contents) {
  for (const item of actor.items.contents) {
    if (!isLegacy(item)) continue;
    if (!actorItemUpdates.has(actor.id)) actorItemUpdates.set(actor.id, []);
    actorItemUpdates.get(actor.id).push(buildUpdate(item));
  }
}

const total = worldUpdates.length
  + [...actorItemUpdates.values()].reduce((n, arr) => n + arr.length, 0);

if (total === 0) {
  ui.notifications.info("[DH Unidentified] No legacy items found — nothing to clean up.");
  return;
}

// ── Confirm before applying (irreversible) ──
const confirmed = await foundry.applications.api.DialogV2.confirm({
  window: { title: "DH Unidentified — Legacy Cleanup" },
  content: `<p>Found <strong>${total}</strong> legacy item(s) from the old destructive model.</p>
    <p>Their real name, image, and description will be restored from the backup
    flags, and all <code>dh-unidentified</code> data will be removed from them.</p>
    <p><strong>This cannot be undone.</strong> Proceed?</p>`,
});

if (!confirmed) {
  ui.notifications.info("[DH Unidentified] Legacy cleanup cancelled.");
  return;
}

// ── Apply in batches ──
if (worldUpdates.length) {
  await Item.implementation.updateDocuments(worldUpdates);
}
for (const [actorId, updates] of actorItemUpdates) {
  const actor = game.actors.get(actorId);
  if (actor) await Item.implementation.updateDocuments(updates, { parent: actor });
}

console.log(`[${MODULE_ID}] Legacy cleanup complete: ${total} item(s) restored and cleared.`);
ui.notifications.info(`[DH Unidentified] Legacy cleanup complete — ${total} item(s) restored to their original state.`);

What to expect

• If no old items are found, you'll see "No legacy items found — nothing to clean up." and nothing changes.
• Otherwise, you'll get a confirmation dialog with the count. After you confirm, the affected items are restored and a summary notification appears.
• You can safely run the macro again afterward — a second run will report that there is nothing left to clean up.

Troubleshooting

• "Only the GM can run the legacy cleanup." — Log in as a Game Master and run it again.
• The macro errors on the import line. — This means the module is not installed or is disabled in the current world. Enable Unidentified Items and try again.