Effect Refactor Update – 7.0 to 7.1 migration guide

[stoic inlet]

Since a lot of people are confused, lost or not sure what specific words mean exactly in Foundry ecosystem, I decided to make a more in-depth guide to migration. This will be a long one, I will be trying to explain definitions, concepts and reasons behind things.

First, you should probably read the Documentation, but if you are not 100% sure what you should do, no worries, I will take care of you.

First things off. Backups. During this guide I will recommend you make a Backup, so let's start with this.

Foundry has built-in backup system and there are two ways you might take a Backup.

1. Snapshot – this copies everything about your current Foundry environment, it includes all Worlds, Systems, Modules and everything you have ever uploaded to User Data folder. This is recommended before you do a mass update of modules (because sometimes you might want to revert to older versions of modules if new ones break)
2. World Backup – this only backs up the specific world, including all scenes, journals, actors, items, local compendiums etc.

To take a Backup of a World, right click on said world and select "Take Backup" (1). To take a Snapshot, open "Manage Backups" from top right of the Foundry screen (2) or when right clicked on a World (3) and in there click on "Create a Snapshot" (4)

Migration Step-by-Step Guide

Based on personal experience, the order matters, especially if you want to run the script from the documentation. Otherwise my step-by step guide is mostly what I believe to be optimal way of doing this.

1. Backup (preferably a snapshot if you have space)

• this is your backup before updating System and Modules. Snapshot here allows you to restore your Foundry to a point before you updated anything. Even if you think you won't need to go back, I strongly recommend making a snapshot here, or at minimum a World Backup

2. For optimal experience I would say now you should delete all imported Documents that have to be migrated. In this case it's all Actors and Items

• imported means it comes from official module compendiums like Enemy in Shadows, Death on the Reik, Rough Nights & Hard Days and so on
• do not delete your own/custom Actors (such as your own NPCs, Player Characters etc)
• reason to delete them now could be to make automatic migration at step 5 quicker.

3. Update System
4. Update Modules

• you can use Update All button, but if you don't want to update a specific module — like you want to keep Dice so Nice at version 4.6.7, because it's the last one that isn't bugged for d100 rolls in wfrp4e — right click on such a module and click Lock Module

5. Launch the world (automatic migration)

• this will conver all Documents (Actors, Items etc.) in your world to use new Data Models architecture and it needs to migrate some data from one path to another. This is fully automatic and nothing you have to worry about other than letting it finish and do not do anything while it's running

6. Wait a moment until it finishes
7. Exit the world and create a world backup

• this is your backup after you updated System and Modules, but before you attempted any "hardcore" things like for example using a script to bulk update all Actors

8. Re-enter the world. If you haven't removed imported documents from official modules (i.e., Actors and Items) yet, do it now
9. If you want to manually update your actors, go to point 15. If you want to use the script for automatic update, go to point 10
10. If you haven't taken screenshots of character sheets to compare if the correct number of talents and trappings were added, if any advancements disappeared (they shouldn't), and if other changes occurred (this usually happens if you edited an item, but the script will find the same one in the compendium without your changes by name), do it now
11. Run the script from the documentation in the console

• this is main reason why deleting official actors and items had to be done before. This script goes through all Actors, so there is a difference if it runs for 5 PCs and 10 NPCs vs running for 200 NPCs from Death on the Reik (or even 700+ Actors if you imported all of them for some reason)
• this is also why you should also have no imported Items in your world, because they would most likely have old Active Effects on them, and script prioritizes World Items before Compendium Items.

12. Ensure there are no lingering Extended Tests or Effects directly on the Actors. If there are, remove them.
13. Make sure everything on the Actors was added correctly.
14. Go to point 16

15. You need to replace all Items that had previously (old one on Actor) or now (new in compendium) have Active Effects before or after the update. At minimum, this includes Talents, but also check Spells, Prayers, Diseases, Injuries, Traits, Mutations, Trappings, etc.
16. Exit the world and make another backup

• this is your backup "after doing Actor update". Should anything break from now on, you have a backup in place where you would not have to go through all that hassle above again

17. You need to click through the actors and check if the talents appear and calculate correctly. For us, this went smoothly because the players managed their characters 😉

• this is also why I suggested making screenshots in point 10, but if you went through Actors manually, you were probably keeping tabs on everything as you go

18. At this point you can "Initialize" any official module you want. But I would say only import those Actors from the official compendiums you'll need in the next session or two, import those actors

• this in my opinion and is something that I believe should be more common knowledge. Only Import What You Need. I should mention that this is my personal opinion and I disagree with Moo on this one (force import of all actors across all modules). He recommends you to "reinitialize", but what you may not know, initialization is simply a bulk import of all Documents in specific module. And you do not need 200/400/600/1000 Actors. I will explain it in more details below — #1242099485115420762 message —, but in the end, it's up to you 😉

*Congratulations!, you should now have fully updated, migrated and working Warhammer FRP 4th Edition on Foundry on 7.1.0 or higher version. *

Migration FAQ

Why do I have to delete official Actors?

1. They have Items and Effects from before refactor. While some may work, most will probably not, especially Talents on them.
2. You do not strictly have to delete them, you can update them manually if you want. But there are hundreds. It's faster to delete and grab new one from Compendium

I modified an official Actor, what should I do?

If you duplicated them before modifying them, I think you should be fine, because they now have unique ID and using system initialization's settings to click "Update" button (import + override) will not overwrite your custom one.

If you didn't duplicate them before, do it now. Or preferably store them in your local compendium for the duration of migration.

Do I have to remove ALL Items from Actors?

No. Only those that either had Active Effect before (it could get changed or removed), and those that have Active Effect now (in compendium, because if they have it now, they either got new one or it changed).

For example, Skill type Items do not have Active Effect (with exception of Heal skill now, which is the only one). Also most Weapon, Armour, Ammunition and Trapping type Items do not have Active Effects, but there are exceptions, mainly draughts/potions/poultices (for example Healing Draught, Faxtoryll, Practical Robes (WoM) or Enchanted Staff (WoM))

Note: automatic script from documentation doesn't care and will replace every single Item it can find replacement for it by matching name and type.

Do I have to uninstall modules?

No. Why? You almost never have to do it. "Module content" is what Moo calls "Documents imported from official Modules' Compendiums".

Having to uninstall and reinstall something is very rare and often occurs if something breaks during release, or a developer releases new version with the same "version number", or if manifest URL was broken. Everyone makes mistakes from time to time, but it's still rare.

WoM, UIA, AotE2 had an errata, how do I get it?

Go to Configure Settings for these Modules (only for these three), then press Setup button to open Initialization Dialog. On it, click the Update button.

On a new prompt that appears, uncheck everything except Overwrite Journals - because you only need updated Journals.

You do not have to do it for any other module
.

Should I reinitialize modules as Moo Man suggests?

Well, it depends on you. Keep in mind that "to initialize" simply means "to import all Documents". My personal opinions is "not really". But for that I need to explain some concepts and how Foundry operates.

Whenever any user (client) connects to Foundry by accessing the /game URL - either they just logged in, or they presses F5 to refresh Foundry - they load ALL DOCUMENTS FROM THAT WORLD. Yes, you heard me right. All Documents. No matter the ownership, permissions, anything. I have 200 Actors currently on my world (yes, I have most from Death on the Reik and some custom VIP NPCs) and 53 scenes. Players can only see 6 scenes in navigation and maybe 20 Actors with Limited or better permission. But when as a Player I check in console how many documents there are, you can see, it shows all of them. Meaning all of them loaded. Screenshot 1

This is because if something is in World, then Foundry assumes "it might be needed at any moment, so better to keep it loaded". This is intended. This is also why making use of Compendiums is intended and encouraged.

And this is true for all Documents: Macro, JournalEntry, JournalEntryPage, Cards, Card, Playlist, Sound, RollTable, RollTableResult etc.

Why does it matter?
It primarily affects loading time. Have you ever noticed that every F5/log in takes a while? And you are sure it was faster in the past? Yeah, it's amount of Documents your Browser needs to load. It is especially noticeable on slower connections or PCs with low amount of RAM which with conjuction with how inefficient browsers are at memory management...
Less important, but also true is that amount of Documents may affect performance. This however very unlikely to be of any issue, unless you use animated images (gif/webm etc) for Documents images, or you use big images (no reason to have portrait on Actor bigger than 800px in height or 1200px in width imho) in unoptimized format (png is worts, jpg also bad, webp best). Usually a single animation is more impactful that hundreds of documents.
So in the end it is about load times

But what about Compendiums?
Compendium is different. All data from Compendiums is stored on your server (wherever you host your foundry) and only it's index is loaded into the browser (very lightweight info, basically id, name, img, type). Whenever you access specific Document in a Compendium (by dragging Item it to an Actor, importing it to your world, or opening its sheet), it's then loaded from server to your browser. You might have noticed that when you try to open Item Sheet from Compendium it's a bit slower than if it's in your World or on an Actor.
Because of that, Compendiums barely matter during loading times. Index data from a single compendium is most likely less than that of an Actor.

**But I have 500 of my own custom Actors 😦 **
You can create your own local compendiums. They are technically stored in your World, but as Compendiums are not loaded (only their index) during load times. I would strongly recommend archiving any Actors you have in such a Compendium and delete them from your World. And only re-import them if you know you will need them.
My rule of thumb is "will I need it in the upcoming few sessions", but with official adventures I do bulk import of all Actors. So when we finished Enemy in Shadows, I deleted all of Actors related to EiS and imported all Actors related to DotR. It's not optimal, but whatever. I'm lazy 😛

Also, on a last note. I mostly talk about Actors here, because Actor is not just an Actor. Actor can have Items and Effects. Items also can have Effects. Here is how many actual Documents there are in a single player character (elf wizard on 2nd career): Screenshot 2. So basically I could have like a 100 of Items and it would have similar impact to a single Player Character.

.

.

.