Item mods: make sure your items have set GUIDs!

[pampl]

GUIDs are unique identifiers assigned to each unit when Torchlight first reads their .dat file. For most units, like monsters and NPCs, these only need to stay constant while Torchlight is running and they're active. However, items that a player has in inventory or equipped will be stored with a reference to the GUID. That means if the GUID changes, the item disappears. GUIDs appear to be set randomly, so if you don't fill in the GUID fields and a player downloads an updated version of your mod - or even just overwrites the mod with a fresh copy of the same version - the game will roll up a new set of GUIDs for your items and all of 'em that the player has will go poof. This will also happen if your item's GUID changes between versions, so try to avoid doing that too.

The only downsides (I know of) from including GUIDs are a file size increase of ~0.1kB/item (~100k/tier) and an impossibly minuscule chance of GUID collision

The only other kind of units that might be effected is player-type units, so this might be important for class mods too, but I haven't tested. NPCs and monsters don't have to remember anything from session to session AFAIK.

[mattdesl]

Bump. This should be stickied.

Also very important:
If your mod makes any changes to original items, make sure the GUIDs are the same!
Otherwise users could lose items just by installing your mod! This has happened multiple times now.

For example, if you copy healthpotion.dat to your mod directory to give it a new DISPLAYNAME, make sure that the UNIT_GUID -- and its identifying NAME, for that matter -- match the original.

[TorchLeech]

Bump & vote for sticky.

Crosslink to a previous discussion about this GUID issue in the TLeech thread (few pages above). We will post a list of all mods without GUIDs supported by TLeech.

List of mods without GUIDs:

• Level/Skill Mod (v2)
• Tier-3 Ancient Items (1.0)
• Total Respec Mod (1.1-fix)

GUID collision: Next version (1.2b) of TLeech release the new conflict check. On our test machine it runs through 1,000 files per second and check for duplicated or missing GUIDs, identical filenames and incorrect file encoding. To check your mod for maximum compatibility you can install all known mods (via TLeech or yourself) and run the check. I have seen some guides from modders to avoid conflicts - maybe we should set links to them in this thread too.

[mattdesl]

Also worth mentioning...

Always let Torchlight randomize GUIDs for you. To do this, simply delete the UNIT_GUID field in the dat, remove the .adm, and run Torchlight or TorchED. Torchlight will generate one in the .dat and .adm files for you.

If everybody lazily changed a few numbers of the original GUID, or mashed their number pad to get a "random" string, we'd start seeing GUID collisions in no time.

[thisbarb]

Also worth mentioning...

Always let Torchlight randomize GUIDs for you. To do this, simply delete the UNIT_GUID field, remove the .adm, and run Torchlight or TorchED.

If everybody lazily changed a few numbers of the original GUID, or mashed their number pad to get a "random" string, we'd start seeing GUID collisions in no time.

How does that work? Is the GUID created by Torchlight and placed back into the unit file or is the GUID re-created every time you startup (which doesn't really make sense)? Or is the random GUID only stored in the .adm?

[Redattack34]

No, it's stored into the .dat file.