File Validation

What is Wolvenkit File Validation? How do I use it?

Summary

Last documented update: March 12 2025 by mana vortex

This page will tell you how to use and configure the File Validation feature (added in 8.9.1)

This feature has an impact on performance — every time you save, there will be a short lag while the file validation does its thing. You can turn this off (check The automatic hook).

What is it?

This feature will try to validate the internal structure and — based on your settings — dependent files.

By default, it will trigger every time you save a file. You can turn this off (check The automatic hook) and trigger it by hand (see below).

The log will yell at you if your files have issues now

Running File Validation

In the editor

Inside the editor, you can run File Validation from the menu bar:

On the entire project

From the Project Menu in the main bar, you can run File Validation on the entire project.

Since this can take a long time, Wolvenkit will show you a warning first.

The automatic hook

By default, File Validation will trigger every time you save. Since this can impact performance for larger files, you might want to disable it.

I don't want it, how do I get rid of it?

In the Script Manager, switch to the Hooks tab and uncheck the box behind hook_global:

For details, see Configuring File Validation below.

There was an error

If you're here because of a link in the Wolvenkit console, there's nothing to worry about, your file saved fine! However, you've managed to run into something that the program isn't equipped to handle yet.

If you would like to help us fix it, you can open a ticket on github or create a forum post on our Discord server in #wkit-bugs-and-requests.

Please attach a minimal version of your project's source folder (we only need archive, but all involved files have to be present, or we won't be able to reproduce your exact error).

Configuring File Validation

There is no fancy UI for the configuration right now (sorry for that), but you can fine-tune file validation via Script Manager.

You need to change the settings inhook_settings.wscript. This is how you open it:

That will open the script editor panel, which looks like this:

You can toggle features on and off by switching values between true and false. Be careful that you don't delete any commas!

In an ideal world, this wiki is always up-to-date with the existing source code. However, that doesn't happen automatically (and can't easily be made that way), and the Wolvenkit team focuses on fixing bugs and developing new features.

The most up-to-date documentation will always be in the source code. Read the comment blocks (green in the screenshot above) for a description of what a flag does.

Here, you will see a list of settings, which are documented in the next section.

Global and shared settings

Depot paths

File Validation will check if any given depot path exists, and warn you if the file could not be found.

This will give false positives if you're on the mod browser!

Enabled

The flag Enabled in line 4 will enable/disable file validation globally.

Each entry in the list has an individual Enabled flag that lets you turn off validation for this particular type of file.

DisableAutofix

File validation can automatically correct certain errors for you. There are certain advanced use cases where you'd want to turn this off — if you don't know about them, then you'll probably want this.

Right now, this is set to false by default and affects the following toggles:

• Workspot.fixIndexOrder

• Workspot.autoReopenFile

validateRecursively

This is the reason behind the micro freeze each time you save a file. If it is enabled, then Wolvenkit will also look at included files — for example, if you save an .app file, it will collect all included meshes (via components or via root entity) and warn you about missing appearances.

You can disable this to save performance, but that will reduce file validation to a glorified typo checker for your file paths. Its developer strongly advises against it, as the feature has saved her hours of frustration already, and at the point of writing it hasn't even been released.

Anims: animation files (.anim)

Checks if all animation names are unique. Since animations are targeted by name, this is the #1 reason why your mod will show the wrong animation.

checkForDuplicates

Will warn you about duplicate animation names (e.g. animations 2 and 31 are both named "facepalm")

App: app files (.app)

Checks all appearances and their associated partsOverrides and partsValues.

checkComponentNameDuplication

Will warn you about duplicate component names. Components are targeted by name, so they should be unique for each appearance or mesh entity.

checkForCrashyDependencies

inplaceResources can crash your game (it's complicated and has something to do with timing and async loading). This flag will toggle the check.

checkPotentialOverrideCollisions

Will warn you if components with the same name are pointing to different meshes.

checkCookPaths

Will print a warning if you have cookedOverrides set in the root or in individual appearances. These things are the reason why mods such as cookedAppsNulled exist.

csv (ArchiveXL factory files)

File validation assumes that this is a factory for ArchiveXL or similar. If it isn't, you can ignore any warnings, or create an issue so that we can add your use case.

checkProjectResourcePaths

Assumes that entries are file paths. Will print a warning if the files can't be found.

warnAboutInvalidDepotPaths

Prints warnings for everything that doesn't look like it's a file path (by regular expression checking, there should be at least one slash)

ent: Root or mesh entity

Similar to the .app file, this will validate nested files, basically checking the entire ArchiveXL chain of dependencies.

validateRecursively

This is really performant and will only look into each file once. That being said, the more files you pull in, the longer it takes, and you might want to disable this feature. On the other hand, saving the root entity is a great way to find out what exactly is broken about your ArchiveXL project.

checkComponentNameDuplication

Same as in the app file: will warn you about duplicate component names. Components are targeted by name, so they should be unique for each appearance or mesh entity.

checkDynamicAppearanceTag

Will print a warning that you might have forgotten to add a DynamicAppearances tag to your root entity if either of the following conditions is true:

• There are empty appearance names in your root entity

• Your .app partsOverrides appearance names or your mesh entity use dynamic string substitution

… since ArchiveXL won't work its magic if you haven't set the tag.

Json: Localization files

Will try to warn you about issues that will cause empty or incorrect strings to be displayed

checkDuplicateKeys

This will warn you if any entries will overwrite each other due to shared key data.

checkEmptyFemaleVariant

By default, the game uses femaleVariant - maleVariant will only be considered if you use either the gender suffix or dynamic ArchiveXL appearances.

Mesh: 3d object

Will check your mesh's internal material assignment. Will warn you about missing files, unresolved dependencies or errors with definitions and file types (some of which might potentially crash your game).

validateMaterialsRecursively

Will also check .mi files and their material setup. As the .mi chains can be quite long, this can cause performance issues.

checkDuplicateMaterialDefinitions

Will warn you if two of your materials appear to be identical

Mi: Material Template

Will check the material setup.

validateMaterialsRecursively

Will check nested .mi files and their material setup, if you are using any.

Workspot: loading .anim files

Mostly for use with this tutorial. Will check if the workspot pulls in existing .anim files, warning you about duplicate definitions.

fixIndexOrder

Convenience: Will automatically set indices of defined animations for you. There are advanced use cases where you might not want this. If you don't know what they are, you might want to turn on autoReopenFile in addition to this.

autoReopenFile

More convenience: Automatically close and re-open the file after using fixIndexOrder (instead of bothering you about it). Default is false.

showUnusedAnimsInFiles

Will warn you about animations in the included .anim files that aren't used by the workspot, in case you want to delete them.

showUndefinedWorkspotAnims

Shows animations that you include in your workspot, but which aren't defined in any of the included .anims files.

checkIdleAnimNames

Will warn you if the idle anim name deviates from the appearance anim name. This isn't strictly necessary, but since the idle anim name is displayed in the list, you will never find the right appearance otherwise.

checkIdDuplication

Only triggers if you aren't using fixIndexOrder: this will warn you about duplicate numeric ID assignments. These will cause the game to mix up your animations.

checkFilepaths

Checks the files included via finalAnimSets, warning you about any loading errors (invalid file paths, invalid extensions, you forgot to add the entry to loadingHandles)