Skip to content

Missing and moved files

A scene, a prefab and the Project’s other files name the files they use: a picture, a sound, a prefab, a clip. This page says what happens when one of those files is moved, renamed or deleted, and how to see what is missing.

Move or rename a file in the Assets panel: drag it onto a folder, or Rename it. Every scene, prefab, settings file, tileset, clip and effect that names it is changed to its new place, and so is the open scene. It is one undo step. Code is not changed: see A file a script names.

When a file that something names is not in the asset folder, the Assets panel shows missing files above the files, with a warning sign and how many there are. Open it to see each one: its name, what is lost by it, and the files that name it (the first three, and how many more). Click one of those to show it in the Assets panel.

  • A file the game loads is missing for the game too: it is not in the asset folder.
  • A value that names its file by an id that no one file has now (none has it, or two do), while another file is at its old place, is listed too: its id names no one file of the asset folder now, so the file at its path is loaded in its place (for a prefab that instances follow, or a clip’s rig: followed in its place). Choose the file again to name the one you mean.
  • What only the editor links to is listed too: a prefab file that instances follow (so its instances here follow nothing) and a clip’s rig (so the clip has no rig).
  • A field in the Inspector that names a file which is not there says Missing.
  • The list changes nothing. It is looked at again a moment after a file or the open scene changes.

The Agent sees the same list.

A file moved or renamed outside the editor (by an agent’s own file tools, in a folder on your computer, or with git) is found where it is now wherever a file names it by its id: a value the editor wrote ends in ?id= and the file’s id, and the editor, the built game and the game itself load the file by that id, wherever it is.

A value without an id names a place only: one written before the Project had ids, or typed by hand. A file moved away from such a place leaves it pointing at the old place.

  • In the editor, the files that name the old place are listed under missing files. The editor does not change them by itself: move the file back and then move it in the Assets panel, which changes every file that names it, or pick the file again in each field, which names it by its id.
  • In the built game, when the game is built to publish it, a value with an id is written as the path of its file where it is now; a value without one is written as it is, and the build warns of each whose file is not there. The Project’s own files are not changed by a build.
  • For the play link, when the game is opened with Play on the Project’s card, nothing is written: the game finds a moved file by its id.

The editor names each file a scene, a prefab or another such file names by the id the asset folder gives it as it is at that moment, read again for every save. Where it cannot, it writes nothing, and the Console says which value, which file, and what to do. The file keeps its bytes and its time:

  • the asset folder’s ids could not be read (the editor lost its dev server for a moment): save again;
  • the file it names is there, but has no id of its own:
    • a scene, a prefab or another such file has no fileId (a file written outside the editor may not) or a bad one: it gets its own when it is put in again: choose Replace… on it in the Assets panel and give it its own file. Do this first for each file it names that has none, the deepest first; then save again. A save that names such a file is refused even where the change saved is to another field;
    • two files give one id: the Console names them, and which one keeps it is yours to choose;
    • a picture’s or a sound’s meta file is missing: one is made once the asset folder has been quiet for a moment. One that is another tool’s, unreadable or left behind, the Console names. Then save again;
  • no file has the id a value carries, and another file is at its path: the file it meant is gone and another took its place. The editor does not take the new file to be the one meant: choose the file again, then save again.

A value whose file is not there at all is saved as it is, and listed under missing files.

An action that names a file the same way (adding a prefab to the scene, a picture dropped into the scene view, Make a prefab, New Splash Scene) is refused for the same reasons and changes nothing; an action of several files (a drop, a move) takes back what it had done. A file it cannot take back because another program changed it meanwhile stays, and the Console names it and where anything of it is kept.

A script names a file by its URL, such as '/assets/textures/crate.png'. Where the asset folder has no such file, the Code panel underlines the string as a warning: “/assets/textures/crate.png” names a file that is not in the asset folder. The underline comes and goes with the file, with no key pressed. While the script is open, its row in the Scripts panel counts it as a warning; when the script is saved, the Console says it too; and the Agent’s type check says the same.

  • Only a URL written whole is looked at: not one built from parts, nor a string in a type, a frame name or a settings key.
  • ?v=2 or #idle after the name belongs to the URL: it names the file before it.
  • A URL that carries its file’s id (?id= and 32 letters and digits after the name) is followed by that id, as the game follows it. After the file is moved, the Code panel notes where it is now, and the string still loads it. A URL whose id no single file has is underlined as a warning: the game then loads what its path names, if anything.
  • Where the editor can mend the string, it offers to. Press Ctrl+Shift+M (Cmd+Shift+M on a Mac) in the Code panel to list the script’s problems, choose one with the arrow keys, and press the underlined letter of what it offers, or click it: Attach its id writes the file’s id after a URL that has one, and Write where it is now writes the path where the file is now, its id as it was. Only that string changes, and Undo takes it back. Once you have typed in that string, its fix does nothing until the editor has looked at it again. A URL whose id no single file has offers nothing: change it yourself.

To write a file’s URL with its id, right-click the file in the Assets panel and choose Copy reference, then paste it into the string; or drag the file from the Assets panel into the Code panel, which writes the same where it is dropped. The Console says what was copied. The id is read as the files are when you copy or drop, so a file made a moment before has its id too. Where no single file has an id (two files give one, or a picture’s meta file is missing or not one the editor reads), the reference is the plain URL, and the Console says it finds the file only while it stays where it is.

A move or rename in the Assets panel does not change code. The Console says which code still names the file’s old URL, and what its URL is now: change it there. Code whose URL carries the file’s id is not listed: the id follows the file. When the editor could not look through the code, the Console says that instead: then look for the old URL in the scripts yourself.

Each scene, prefab, settings file, clip, effect and tileset that the editor saves keeps its own id at its end, fileId, which stays the same when the file is moved or renamed. A value that names the file carries it after ?id=. The editor writes it at every save: leave it as it is, and never write or copy an id by hand. A field still holds the file’s place as well, the URL the game loads it from (such as /assets/textures/crate.png?id=…).

A file saved by an older editor may also have a references entry at its end. The editor no longer writes it, and drops it the next time it saves the file.

  • A copy of a file made outside the editor has its original’s id. The editor changes neither file, since which one is the original cannot be told, and its console says so. Until one of them has an id of its own, a value that names that id loads the file at its own path, and a save of a file that names it is refused (above). Decide which one keeps the id. Move each other one out of the asset folder and add it back through the Assets panel, which gives it an id of its own. Then change each value and script that names the old id and means that file, to name it by its new id: once one file alone gives the old id, the old id loads that one. A plain path would load the file now, but would not follow it if it is moved later.

A picture or a sound keeps its id in a meta file beside it: crate.png has crate.png.meta, with its id and the fingerprint of its bytes. The editor makes it and moves, deletes and restores it with its file: the Assets panel does not list it. Moved outside the editor, a picture or a sound should take its meta file with it. A copy should not: it is given a meta file of its own.

Where the editor cannot tell which file an id belongs to, it changes nothing, and its Console names the files and says how to settle it. The editor looks again as the files change.

  • A meta file records other bytes than its file has: the file was painted over, or another file was put in its place, outside the editor. If it is the same file changed, choose Replace… on it in the Assets panel and pick that file: its bytes are recorded and it keeps its id.
  • A meta file the editor does not read: another tool’s file of that name, or one a merge left conflict markers in. The editor never writes over it. Move another tool’s file out of the asset folder, and the picture gets a meta file of its own; put the editor’s own back as it was (with git, if a merge changed it).
  • Files that give one id, such as a picture copied with its meta file: as for a copy of a scene above, move each other one with its meta file out of the asset folder, and add it back through the Assets panel. Where a scene, a prefab or another such file and a picture’s or a sound’s meta file give one id, adding a file back does not settle it: decide which keeps the id, and do not add, copy or move a meta file alone to settle it.
  • A picture or a sound without a meta file, beside a meta file whose file is gone: a file moved or renamed outside the editor without it. Move the meta file beside it, named as the file with .meta after it, and it keeps its id.

Wherever a file is given a new id, change each value and script that names the old id and means that file, to name it by its new id.