EngineSetModelLODDistance

2025-03-31T07:29:30Z

Azure: /* Example */

{{Client function}}
__NOTOC__
This function sets a custom LOD distance for any object / model ID. This is the distance at which objects of that model ID are switched to their LOD model, or (if there is no LOD model) become invisible.

'''Notes:'''
The actual draw distance used is modified by the draw distance slider in the settings 'Video' tab of the MTA client.

*When the 'Video' tab draw distance slider is 0%, the engineSetModelLODDistance setting approximately matches the draw distance used.
:''e.g. engineSetModelLODDistance(1337,100) will mean model 1337 will be visible up to a distance of '''100''' units.''

*When the 'Video' tab draw distance slider is 100%, the engineSetModelLODDistance setting is approximately doubled before use.
:''e.g. engineSetModelLODDistance(1337,100) will mean model 1337 will be visible up to a distance of '''200''' units.''

However, there is a general draw distance limit of 325 units. So engineSetModelLODDistance(1337,400) will mean model 1337 will be visible up to a distance of 325 units no matter what the 'Video' tab says.

Therefore, unless it's really important, engineSetModelLODDistance should not be set to anything greater than 170. 
170 will still give the maximum draw distance (of 325 units) on clients that have a 'Video' tab draw distance setting of 100%, and it will help reduce lag for players who chose a lower draw distance in their settings.

'''Note for low LOD [[object]]s''':
*The limit is 325 units, but the actual draw distance used is 5 times the setting value. Also, they ignore the 'Video' tab draw distance slider. So a setting of 200 will mean a low LOD element will always have a draw distance of '''1000''' units.

'''Note for low LOD [[building]]s''':
*The distance must be set greater than 300 for a low LOD building in order to work correctly. Otherwise, the low LOD will always be visible. The actual draw distance is NOT 5 times the setting value.

==Syntax==
<syntaxhighlight lang="lua">
bool engineSetModelLODDistance ( int model, float distance [, bool extendedLod = false ] )
</syntaxhighlight>
{{OOP||Engine.setModelLODDistance}}
===Required Arguments===
*'''model:''' The model / object ID number you want to change the LOD distance of.
*'''distance:''' New LOD distance value in San Andreas units.

===Optional Arguments===
{{OptionalArg}}
{{New feature/item|3.0161|1.6.0|22676|
*'''extendedLod:''' Allows to set a greater distance than the current 325 units.
}}

===Returns===
Returns ''true'' if the function executed succesfully, ''false'' otherwise.

==Example==
<syntaxhighlight lang="lua">
-- Client-side
-- Can cause massive lag by maxing out draw distance of all objects

function setStreamedInObjectsLOD() -- Function to set LOD for currently streamed-in objects

local objects = getElementsByType ( "object" ) -- Get objects when function is called

for theKey,theObject in ipairs(objects) do -- Use a generic "for" loop to iterate through each object

local modelID = getElementModel(theObject) -- Get the model ID of the object element
local lodLevel = 3000 -- Set the desired LOD distance (in this case, 3000)

local previousLODDistance = engineGetModelLODDistance( modelID ) -- Get the LOD distance of the object model
-- outputChatBox ( "The previous LOD distance of the #" .. theKey .. " object model with ID " .. modelID .. " is " .. previousLODDistance .. "." ) -- Debug message that shows the current LOD distance of the object model

engineSetModelLODDistance ( modelID, lodLevel, true ) -- Set the LOD distance of the object model to 3000 and enable the extended LOD parameter
-- outputChatBox ( "The LOD distance of the #" .. theKey .. " object model with ID " .. modelID .. " has been set to " .. lodLevel .. "." ) -- Debug message that shows to what model IDs the changes were applied

-- Optional: You can also check the LOD distance of the object model to verify if it was applied correctly

local newLODDistance = engineGetModelLODDistance( modelID ) -- Get the LOD distance of the object model
-- outputChatBox ( "The new LOD distance of the #" .. theKey .. " object model with ID " .. modelID .. " is " .. newLODDistance .. "." ) -- Debug message that shows the current LOD distance of the object model

end

end

-- Add the command that calls the function setStreamedInObjectsLOD()
addCommandHandler("setStreamedInObjectsLOD", setStreamedInObjectsLOD) -- Bind the function to a command for testing purposes
</syntaxhighlight>

This example will, besides replacing with custom map objects, also set the LOD distance accordingly, a necessary step (otherwise the object could seem to fail loading and only show up 1 feet away)
<syntaxhighlight lang="lua">
function replaceObjects()

local col1 = engineLoadCOL("map1.col")
local col2 = engineLoadCOL("map2.col")

local txd = engineLoadTXD("map.txd")
engineImportTXD(txd, 2357)
engineImportTXD(txd, 2290)

local dff1 = engineLoadDFF("map1.dff")
local dff2 = engineLoadDFF("map2.dff")

engineReplaceCOL(col1, 2357)
engineReplaceCOL(col2, 2290)
engineReplaceModel(dff1, 2357)
engineReplaceModel(dff2, 2290)

engineSetModelLODDistance(2357, 325)
engineSetModelLODDistance(2290, 325)
end
</syntaxhighlight>

This example shows how to use LOD's with buildings
<syntaxhighlight lang="lua">
function createMyPyramid()
local pos = Vector3(0, 0, 3)
local rot = Vector3(0, 0, 0)

local modelHi = 8395 -- This model has a lot of polygons
local modelLow = 8701 -- This model is optimized for drawing at a long distance

-- Always call this function if you don't like default draw distance
-- or you allocated the model with using engineRequestModel
engineSetModelLODDistance(modelHi, 100, true)
engineSetModelLODDistance(modelLow, 500, true)

local lod = createBuilding(modelLow, pos, rot)
local building = createBuilding(modelHi, pos, rot)

setLowLODElement(building,lod)
end
</syntaxhighlight>

==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.6.0-9.22676|Added extendedLod argument}}

==See Also==
* [[getVehiclesLODDistance]]
* [[resetVehiclesLODDistance]]
* [[setVehiclesLODDistance]]
{{Engine_functions}}