More Lua documentation about FormId

files/lua_api/openmw/core.lua

@@ -125,11 +125,17 @@
 
 ---
 -- Construct FormId string from content file name and the index in the file.
+-- In ESM3 games (e.g. Morrowind) FormIds are used to reference game objects.
+-- In ESM4 games (e.g. Skyrim) FormIds are used both for game objects and as record ids.
 -- @function [parent=#core] getFormId
 -- @param #string contentFile
 -- @param #number index
 -- @return #string
 -- @usage if obj.recordId == core.getFormId('Skyrim.esm', 0x4d7da) then ... end
+-- @usage -- In ESM3 content files (e.g. Morrowind) ids are human-readable strings
+-- obj.ownerFactionId = 'blades'
+-- -- In ESM4 (e.g. Skyrim) ids should be constructed using `core.getFormId`:
+-- obj.ownerFactionId = core.getFormId('Skyrim.esm', 0x72834)
 -- @usage -- local scripts
 -- local obj = nearby.getObjectByFormId(core.getFormId('Morrowind.esm', 128964))
 -- @usage -- global scripts

files/lua_api/openmw/nearby.lua

@@ -28,6 +28,9 @@
 
 ---
 -- Return an object by RefNum/FormId.
+-- Note: the function always returns @{openmw.core#GameObject} and doesn't validate that
+-- the object exists in the game world. If it doesn't exist or not yet loaded to memory),
+-- then `obj:isValid()` will be `false`.
 -- @function [parent=#nearby] getObjectByFormId
 -- @param #string formId String returned by `core.getFormId`
 -- @return openmw.core#GameObject

files/lua_api/openmw/world.lua

@@ -67,6 +67,9 @@
 
 ---
 -- Return an object by RefNum/FormId.
+-- Note: the function always returns @{openmw.core#GameObject} and doesn't validate that
+-- the object exists in the game world. If it doesn't exist or not yet loaded to memory),
+-- then `obj:isValid()` will be `false`.
 -- @function [parent=#world] getObjectByFormId
 -- @param #string formId String returned by `core.getFormId`
 -- @return openmw.core#GameObject