Reproducible asset imports: preserve identity, settings and tool versions

Define what must reproduce

An asset pipeline transforms authored files into runtime resources. Reproducibility requires knowing both the input and the transformation. Two developers can hold identical image bytes yet produce different runtime textures through different import settings. Decide whether the project requires identical output bytes, equivalent resource properties or an agreed visual result; these are different acceptance criteria.

Preserve reference identity

Unity's asset metadata stores a unique identifier and import settings in the accompanying .meta file. Moving an asset outside the Editor requires keeping that file with it; losing metadata can break references. [1] Treat an asset move as an identity-preserving operation, and review metadata changes alongside source changes. A filename is not a substitute for the identifier used by serialized references.

Separate configuration from cache

Godot writes per-asset import configuration beside source files in .import files and recommends committing that configuration. Generated imports live under .godot/imported/ and can be regenerated. [2] Its version-control guidance for Godot 4.1 and later excludes .godot/ cache data. Older releases have different exclusions, so use guidance matching the project version. [3]

Keep required project settings, import scripts and dependency versions with the source of truth. Record target-platform overrides as deliberately as the default settings. Avoid treating a working developer cache as the only surviving copy of a required input.

Work through a clean-import check

Imagine a stone-wall source texture used for both close-up inspection and distant scenery. One machine imports it with mipmaps and a selected compression format; another disables mipmaps. The source image checksum still matches, but the runtime sampling behavior differs.

For a proposed verification run, start with a clean checkout, obtain the actual large-file contents where applicable, and use the pinned engine and importer versions. Regenerate derived data, then inspect dimensions, mip count, format and material references for this fixture. Open a small scene that uses the wall at several distances. Compare the agreed acceptance properties and capture any differences. This is a workflow example, not a claim that an import was executed.

Make changes explainable

When upgrading tools, rebuild representative textures, meshes and audio before rebuilding everything. Keep source hashes, tool versions and import-setting changes in the build record. If output bytes change while the intended resource properties remain stable, investigate before deciding whether the difference is acceptable.

Test renaming and moving the fixture as well as editing it. A reproducible texture that loses every material reference still represents a broken pipeline. Review cache policy, identity preservation and output checks as separate responsibilities.

Sources

[1] Asset metadata — Unity Technologies.

[2] Godot import process — Godot Engine contributors.

[3] Godot version control systems — Godot Engine contributors.