Repair a cross-package BetonQuest reference after organising files

Moving a quest package can change how other packages reach its features. Map the references before renaming folders so an organisation change does not disconnect a live quest chain.

Check the installed content

BetonQuest expresses a quest through objectives, conditions, events and conversation links. Keep the package and player state together during testing. The linked reference describes the 2.2 documentation branch; select the corresponding documentation if your server runs another major version.

Work through the change

1. Back up the complete QuestPackages tree and list the package being moved. Record the events, objectives, conditions and conversations referenced by other packages.
2. Read the package-path rules for the installed documentation branch. Distinguish a normal subfolder from a folder containing its own package.yml, which creates a separate package boundary.
3. Move a small copied package on staging and update the affected references consistently. Use documented absolute or relative package addressing rather than inserting filesystem paths into event IDs.
4. Load the staging quest set and test one entry from each dependent package. Inspect the first unresolved-reference error before continuing through the rest of the chain.

Verify the result

Every dependent call should resolve to the intended feature after organisation, with no duplicate IDs within the same package. The player should reach the next quest stage through its ordinary entry route.

If the result differs

If a local reference works but an external one fails, inspect the package path and boundary. If both fail, check whether the feature definition loaded before changing cross-package syntax again.

Keep a recovery path

Restore the original directory tree and package references together if the move breaks the chain. Avoid renaming live persistent quest identities during a file tidy-up without a separate state-migration plan.

References and related help

Check the maintainer reference: BetonQuest documentation.

Before changing live data, read how to keep a completed recovery copy. For startup errors, use the log collection guide.