v1.0.5

Author: sneat

CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## v1.0.5
+
+- Added "How to use" style journals to the Scene Packer compendium.
+- Added options on how to initialise Scene Packer. See readme or compendium Journal for examples.
+- Added "dry run" mode to `await window['scene-packer'].relinkJournalEntries('module-name', {dryRun: true});` allowing
+  you to see the changes that will be made to compendium journals without actually making the changes.
+- Added `await window['scene-packer'].promptRelinkJournalEntries();` as a way to prompt the module name and dry-run
+  mode. Also added a macro version bundled in the compendium.
+- Added better handling of cases where data wasn't in a valid state for packing.
+- Added initial support for specifying Macro packs. Works similar to setting creature or journal
+  packs. `packer.SetMacroPacks();`
+- Removed `packer.DisableImportPrompts();` as it wouldn't fire at the appropriate time. See new methods for initialising
+  Scene Packer for replacement option.
+- Switched config option default so that Scene context menus (right clicking) no longer shows Scene Packer options by
+  default (because most people are users, not developers).
+- Added Macro compendium to assist with usage.
+- Fixed minor typos and grammatical errors.
+
 ## v1.0.4
 
 - Added welcome prompt to import and unpack all scenes in the adventure.
@@ -8,19 +26,23 @@
 
 ## v1.0.3
 
-- Added `packer.DisableImportPrompts();` as a way to prevent the popups from appearing when opening your module's compendiums.
+- Added `packer.DisableImportPrompts();` as a way to prevent the popups from appearing when opening your module's
+  compendiums.
 - Added `Unpack Scene Data` option to Scene context menu.
 - Changed Scene context menu options to only show based on whether the Scene has Packed Data already.
 - Default to showing the context menu on scenes for GMs.
-- Changed the flag used to store whether the adventure module has been imported from a `boolean` to a `version` string to allow future support of "upgrades" to the module.
-- Exposed `HasPackedData(scene, moduleName, tokenFlag, journalFlag)` static method to allow checking whether a given Scene has data packed for the given module.
+- Changed the flag used to store whether the adventure module has been imported from a `boolean` to a `version` string
+  to allow future support of "upgrades" to the module.
+- Exposed `HasPackedData(scene, moduleName, tokenFlag, journalFlag)` static method to allow checking whether a given
+  Scene has data packed for the given module.
 
 ## v1.0.2
 
 - Fixed bug that would occur if Journal entries weren't in a folder of the same name as the adventure.
 - Delay calling `scenePackerReady` hook until after the canvas is ready.
 - Added `await window['scene-packer'].relinkJournalEntries('module-name');` static method
-    - Automatically goes through the Journals in the module's compendium packs and updates the references from the World version to the Compendium versions.
+  - Automatically goes through the Journals in the module's compendium packs and updates the references from the World
+    version to the Compendium versions.
 
 ## v1.0.1
 

README.md

@@ -20,14 +20,14 @@ To use the Scene Packer as part of your module you will need to add it as a depe
 "dependencies": [
   {
     "name": "scene-packer",
-    "manifest": "https://raw.githubusercontent.com/League-of-Foundry-Developers/scene-packer/master/module.json",
+    "manifest": "https://raw.githubusercontent.com/League-of-Foundry-Developers/scene-packer/master/module.json"
   }
 ]
 ```
 
 ### Module code requirements
 
-To unpack your scenes automatically when first viewed by a user, include the following in your module js script, updating the variable names where appropriate.
+To unpack your scenes automatically when first viewed by a user, include the following in your module javascript, updating the variable names where appropriate.
 
 ```javascript
 const adventureName = 'The Name of Your Adventure or Collection';
@@ -58,38 +58,39 @@ const creaturePacks = [`${moduleName}.actors`, 'dnd5e.monsters'];
  * Set to the following to disable:
  *   const journalPacks = [];
  */
-const journalPacks = [`${moduleName}.journals`];
+const journalPacks = [`${moduleName}.journals`];/**
+ * macroPacks is a list of compendium packs to look in for Macros by name (in prioritised order).
+ * The first entry here assumes that you have a Macro pack in your module with the "name" of "macros".
+ * Set to the following to disable:
+ *   const macroPacks = [];
+ */
+const macroPacks = [`${moduleName}.macros`];
 
 Hooks.once('scenePackerReady', ({ getInstance }) => {
   // Initialise the Scene Packer with your adventure name and module name
-  let packer = getInstance(adventureName, moduleName);
-  if (creaturePacks.length) {
-    packer.SetCreaturePacks(creaturePacks);
-  }
-  if (journalPacks.length) {
-    packer.SetJournalPacks(journalPacks);
-  }
-  if (welcomeJournal) {
-    packer.SetWelcomeJournal(welcomeJournal);
-  }
-  if (additionalJournals.length) {
-    packer.SetAdditionalJournalsToImport(additionalJournals);
-  }
-  // If you don't want the dialogs to appear when your users first open the compendiums, uncomment the following line.
-  // packer.DisableImportPrompts();
+  let packer = getInstance(adventureName, moduleName, {
+    creaturePacks,
+    journalPacks,
+    macroPacks,
+    welcomeJournal,
+    additionalJournals,
+    allowImportPrompts: true, // Set to false if you don't want the popup
+  });
 });
 ```
 
 ### Packing your Scenes
 
 To pack your scene ready for distribution:
 
-1. `Enable Scene Packer context menu` in Module Settings.
+1. Enable the `Scene Packer context menu` in Module Settings.
 2. Build your scene as normal, adding Actors and Journal Pins where you'd like.
-3. Export your Actors/Journals/Roll Tables to compendiums as normal.
-4. Right click on your Scene in the Scenes Directory and choose `Pack Scene Data`.
-5. Export your Scene to your compendium.
-6. Right click on your Scene in the Scenes Directory and choose `Clear Packed Scene Data`.
+3. Export your Actors/Journals/Roll Tables/Items/Macros to your compendiums as normal. 
+4. Run the script to Update Journal links to fix up the journal compendium linking (see section below)
+5. Re-export your Journals to compendiums, be sure to select the "Merge By Name" option to prevent the IDs from changing (and therefore re-breaking the links)
+6. Right click on your Scene in the Scenes Directory and choose `Pack Scene Data`.
+7. Export your Scene to your compendium.
+8. Right click on your Scene in the Scenes Directory and choose `Clear Packed Scene Data`.
 
   - You want to choose this otherwise next time you open your Scene locally it will run the Scene import scripts.
 
@@ -100,13 +101,19 @@ To pack your scene ready for distribution:
 When you build an adventure module, it's a painful process updating all of your Journal references to link to the compendium versions. You can simplify this by running the following command in your browser console putting in your appropriate module name (as per your manifest json name):
 
 ```js
-`await window['scene-packer'].relinkJournalEntries('module-name');`
+await window['scene-packer'].relinkJournalEntries('module-name', {dryRun: false});
 ```
 
+Alternatively, you can run the macro `Relink compendium journal entries` that is included in the Scene Packer compendium, which will prompt you for your module name and whether you want to run in "dry run" mode (not saving changes).
+
+This will automatically go through the Journal compendiums that belong to your module, and change the reference links to the compendium versions. For example, if you had a link to `@Actor[alvhCr52HIrWmoez]{Commoner}` it would change it to `@Compendium[your-module.actors.lOBiqShvkT83eGzY]{Commoner}` using your module and compendium names and ID references.
+
 ## TODO
 
 - Provide example complete module
 
 ## Acknowledgements
 
-A portion of the code is based on code created by <https://onepagemage.com/> and used with permission.
+A portion of the code is based on code created by [honeybadger](https://github.com/trioderegion) and used with permission.
+
+Thanks to [Baileywiki](https://www.patreon.com/baileywiki) for their initial testing and feedback.

languages/en.json

@@ -13,9 +13,9 @@
     },
     "welcome": {
       "title": "{title} Importer",
-      "intro": "<p>Welcome to <strong>{adventure}</strong></p>",
-      "brand-new": "<p>Would you like to import and unpack the Scenes from this adventure?</p>",
-      "update-available": "<p>An update is available. You have <strong>{existing}</strong> installed, and <strong>{version}</strong> is available. Would you like to import and unpack the Scenes from this adventure?</p><p><strong>Note: If you choose to import all, you will end up with a second copy of the scene, the bottom one is the newer version.</strong></p>",
+      "intro": "<h2>Welcome to <strong>{adventure}</strong>.</h2>",
+      "brand-new": "<p>Would you like to import and unpack the Scenes from this module?</p>",
+      "update-available": "<p>An update is available. You have <strong>{existing}</strong> installed, and <strong>{version}</strong> is available. Would you like to import and unpack the Scenes from this module?</p><p><strong>Note: If you choose to import all, you will end up with a second copy of the scenes, the bottom one is the newer version.</strong></p>",
       "yes-all": "Yes import all",
       "let-me-choose": "Let me choose",
       "no": "No",
@@ -25,11 +25,13 @@
       "first-launch": "First launch of this adventure! Unpacking scene...",
       "done": "All done!",
       "pack-scene": {
-        "clear-reminder": "Don't forget to run ScenePacker.ClearPackedData() after exporting to prevent future duplicates.",
+        "clear-reminder": "Don't forget to \"Clear Packed Scene Data\" after exporting to prevent future duplicates.",
         "writing-journals": "Writing {number} journals to scene: {name}",
         "no-journal-pins": "No journal pins detected on the scene.",
-        "no-token-name-warning": "Cannot pack a token that has no name. Check console for details.",
+        "no-token-name-warning": "Cannot pack a token that has no name. Check debug logs for details.",
         "no-token-name-log": "Trying to pack a token that has no name is not going to end well. Please ensure the Token and Actor have a name.",
+        "no-journal-link-warning": "Cannot pack a journal pin that does not link to a valid journal entry. Journal pin is called: \"{pin}\". Check debug logs for details.",
+        "no-journal-link-log": "Trying to pack a journal pin that does not link to a journal entry is not going to end well. Please ensure the pin \"{pin}\" is linked correctly.",
         "writing-tokens": "Writing {number} tokens to scene: {name}",
         "no-tokens": "No tokens detected on the scene."
       },
@@ -46,16 +48,16 @@
         }
       },
       "find-actor": {
-        "missing-name": "Cannot find a token that has no name. Check console for details.",
+        "missing-name": "Cannot find a token that has no name. Check debug logs for details.",
         "missing-name-details": "Trying to find a token that has no name is not going to end well. Please ensure the Token and Actor have a name prior to packing."
       },
       "link-tokens": {
-        "missing": "Could not find {count} actors to link, they will remain unlinked. Check console for details.",
+        "missing": "Could not find {count} actors to link, they will remain unlinked. Check debug logs for details.",
         "missing-details": "Could not find {count} actors to link. The following actor tokens were not found in the \"{adventureName}\" folder.",
         "linking": "Relinking {count} Tokens linked to actors."
       },
       "spawn-notes": {
-        "missing": "Could not find {count} journals to link. Check console for details.",
+        "missing": "Could not find {count} journals to link. Check debug logs for details.",
         "missing-details": "Could not find {count} notes to spawn. The following journals were not found.",
         "spawning": "Spawning {count} journal notes."
       },
@@ -64,7 +66,8 @@
       },
       "clear-data": {
         "done": "Finished clearing Packed Data."
-      }
+      },
+      "deprecated": "Warning, {method} is deprecated and will be removed in the future."
     },
     "scene-context": {
       "pack": {
@@ -108,6 +111,11 @@
         "ui": "Invalid call to SetJournalPacks(). See console for details.",
         "details": "You must pass an array of strings to \"SetJournalPacks()\". They must be the names of Journal Packs. Received: {pack}",
         "missing": "SetJournalPacks() called with no value. This disables importing of Journals."
+      },
+      "macroPacks": {
+        "ui": "Invalid call to SetMacroPacks(). See console for details.",
+        "details": "You must pass an array of strings to \"SetMacroPacks()\". They must be the names of Macro Packs. Received: {pack}",
+        "missing": "SetMacroPacks() called with no value. This disables importing of Macros."
       }
     },
     "world-conversion": {
@@ -116,18 +124,28 @@
         "lock": "Locking compendiums: {list}",
         "checking-and-updating": "Checking and updating {count} journal references from world links to compendium links.",
         "invalid-ref-type": "Found a journal reference that isn't handled: {type}. Skipping reference...",
-        "invalid-no-name": "Found a journal reference but couldn't find its original name. Check console for details.",
+        "invalid-no-name": "Found a journal reference but couldn't find its original name. Check debug logs for details.",
         "invalid-no-matching-name": "Could not find reference name in world data",
-        "invalid-not-found": "Found a journal reference but couldn't find its compendium version by name. Check console for details.",
+        "invalid-not-found": "Found a journal reference but couldn't find its compendium version by name. Check debug logs for details.",
         "invalid-not-found-console": "Could not find reference in compendium data. Skipping updating reference...",
-        "invalid-too-many": "Found a journal reference but found more than one compendium version by name. Check console for details.",
+        "invalid-too-many": "Found a journal reference but found more than one compendium version by name. Check debug logs for details.",
         "invalid-too-many-console": "Found more than one reference in compendium data. Skipping updating reference...",
-        "updating-journal-references": "Changing {count} journal references in: {journal}",
+        "updating-journal-references": "Changing {count} journal references in: \"{journal}\"",
         "updating-reference-console": "Changing {pack}[{journalEntryId}] {type} reference {oldRef} -> {newRefPack}.{newRef}",
-        "updating-reference": "Updating {count} references in {journal}. See console for full details.",
-        "completed-journal": "Completed journal {journal} {entryId}",
+        "updating-reference": "Updating {count} references in \"{journal}\". See console for full details.",
+        "completed-journal": "Completed journal \"{journal}\" {entryId}.",
+        "no-references": "There were no references that needed updating in journal  \"{journal}\" {entryId}.",
+        "checking-journal": "Checking contents of journal \"{journal}\" {entryId}.",
         "completed": "Completed!"
       }
+    },
+    "relink-prompt": {
+      "title": "Relink Journal Entries",
+      "intro": "Select the module you are using Scene Packer with:",
+      "make-changes": "Save changes?",
+      "make-changes-info": "Leaving this unchecked will operate in a \"dry run\" mode, where changes are only output to the console.",
+      "relink": "Relink",
+      "cancel": "Cancel"
     }
   }
 }

module.json

@@ -2,13 +2,14 @@
   "name": "scene-packer",
   "title": "Library: Scene Packer",
   "description": "A module to assist with Scene and Adventure packing and unpacking.",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "library": "true",
   "manifestPlusVersion": "1.0.0",
   "minimumCoreVersion": "0.7.9",
   "compatibleCoreVersion": "0.7.9",
   "author": "The League of Extraordinary FVTT Developers",
-  "authors": [{
+  "authors": [
+    {
       "name": "The League of Extraordinary FVTT Developers",
       "url": "https://github.com/League-of-Foundry-Developers"
     },
@@ -17,17 +18,33 @@
       "discord": "blair#9056"
     }
   ],
+  "packs": [
+    {
+      "name": "journals",
+      "label": "Library: Scene Packer",
+      "path": "/packs/journals.db",
+      "entity": "JournalEntry"
+    },
+    {
+      "name": "macros",
+      "label": "Library: Scene Packer",
+      "path": "/packs/macros.db",
+      "entity": "Macro"
+    }
+  ],
   "esmodules": [
     "/scripts/scene-packer.js"
   ],
-  "languages": [{
-    "lang": "en",
-    "name": "English",
-    "path": "languages/en.json"
-  }],
+  "languages": [
+    {
+      "lang": "en",
+      "name": "English",
+      "path": "languages/en.json"
+    }
+  ],
   "url": "https://github.com/League-of-Foundry-Developers/scene-packer",
   "manifest": "https://github.com/League-of-Foundry-Developers/scene-packer/releases/latest/download/module.json",
-  "download": "https://github.com/League-of-Foundry-Developers/scene-packer/releases/download/1.0.4/module.zip",
+  "download": "https://github.com/League-of-Foundry-Developers/scene-packer/releases/download/1.0.5/module.zip",
   "bugs": "https://github.com/League-of-Foundry-Developers/scene-packer/issues",
   "changelog": "https://github.com/League-of-Foundry-Developers/scene-packer/blob/master/changelog.md",
   "allowBugReporter": true