Add object LOD management functions

[Fernando-A-Rocha]

Definitions:
HLOD = High Level of Detail (normal object models the player sees when near the object)
LLOD = Low Level of Detail (object models with less detail the player sees when far from the object)

---

Adds new clientside functions:

• getObjectLowLODModel(number highLODModel) - returns the LLOD model of the HLOD model passed
• getObjectHighLODModel(number lowLODModel) - counterpart function start searches the HLOD of a LLOD
• setObjectCustomLowLODModel(number highLODModel, number lowLODModel) - defines a custom LLOD of a HLOD that will be returned in the previous functions
• resetObjectCustomLowLODModel(number highLODModel) - unsets a custom LLOD of a HLOD that was set with the previous function
• resetAllObjectCustomLowLODModels() - unsets all custom LLODs of HLODs

To be used in conjunction with:

• createObject / createBuilding
• setLowLODElement
• engineSetModelLODDistance

This solves the problem of having to include a Lua LOD_TABLE in every map's script, which has been happening for years (the map editor's LOD table happens to be incomplete as of submitting this PR), providing a simple solution to obtain an object's LLOD model ID in the code.

Related to multitheftauto/mtasa-resources#556

---

Examples:

LLOD model of HLOD model ganghous03_LAx (3655) is lodganghous03_lax (3656).

local function createObjWithLod(model, x, y, z, rx, ry, rz)
  local obj = createObject(model, x, y, z, rx, ry, rz)
  local lowLodModel = getObjectLowLODModel(model)
  if lowLodModel then
    local lowLodObj = createObject(lowLodModel, x, y, z, rx, ry, rz, true) -- isLowLOD
    setElementParent(lowLodObj, obj) -- makes sure this LLOD object gets destroyed together with the parent HLOD
    setLowLodElement(obj, lowLodObj) -- makes the HLOD-LLOD association
end

[FileEX]

The lod arrays from the map editor are incomplete, so I assume this function is also incomplete. Therefore, a note should be added on the wiki once this PR is merged

[Fernando-A-Rocha]

The lod arrays from the map editor are incomplete, so I assume this function is also incomplete. Therefore, a note should be added on the wiki once this PR is merged

No. I completed the table. It's good now.
See the mtasa-resources issue I linked where I explain it.

[lotsofs]

The provided LOD model list not only is incomplete, it also contains plain incorrections. Examples are the LLODs for HLOD models 10428, 10369, 10439.

[Fernando-A-Rocha]

The provided LOD model list not only is incomplete, it also contains plain incorrections. Examples are the LLODs for HLOD models 10428, 10369, 10439.

I'm surprised, I thought the list was generated from the game files not missing anything.

Will you suggest a fix for the array?

[derxgbb]

I'm surprised, I thought the list was generated from the game files not missing anything.

Will you suggest a fix for the array?

Just a note:
Even the game .ipl files are different in other ports (ps2, xbox etc). For example the lanterns and special objects around four dragon casino is only persistent on ps2/xbox. https://imgur.com/MV61hvH
The objects does exist but never used in game.
I don't know if .ide files are different, they shouldn't but who knows.

[Fernando-A-Rocha]

I'm gonna investigate the HLOD => LLOD array. @lotsofs @spooky-spook

I'm surprised, I thought the list was generated from the game files not missing anything.
Will you suggest a fix for the array?

Just a note: Even the game .ipl files are different in other ports (ps2, xbox etc). For example the lanterns and special objects around four dragon casino is only persistent on ps2/xbox. https://imgur.com/MV61hvH The objects does exist but never used in game. I don't know if .ide files are different, they shouldn't but who knows.

It's interesting that PS2 and XBOX versions of the games have different world mapping, but I think this is out of the scope of this LLOD-improvements PR.

https://tcrf.net/Grand_Theft_Auto:_San_Andreas/Version_and_Platform_Differences
There are a large number of objects in Las Venturas missing from the PC version, mainly outside the Four Dragons Casino and The Visage. This seems to be a simple omission from the map as they are still in the game.

[Fernando-A-Rocha]

@lotsofs

There is a function that we can use in MTA to obtain a building (world object)'s LLOD model ID: processLineOfSight

MTA Map Editor makes use of this to find any building's LLOD model so it can be removed from the map along with its HLOD model, using removeWorldModel.

The provided LOD model list not only is incomplete, it also contains plain incorrections. Examples are the LLODs for HLOD models 10428, 10369, 10439.

I found that, for example, 10369'S LLOD model is 10511.

Both these HLOD and LLOD models are defined in the game IPL files:

10511 is defined in a plaintext IPL "SFs.ipl", while 10369 is in a binary IPL that I converted to text "sfs_stream0.ipl"

😃 According to these 2 images, you can see that 10369's IPL line has "128" in the last position, which means that its LLOD model is the object instantiated at index 128 (indexes start at 0) of SFs. The LLOD 10511 is instantiated at exactly index 128 in SFS.ipl. The only annoying fact is that they are in different files that both start with sfs.

---

So, yes, something went wrong creating the LODs table, I will look into generating a correct one.

[derxgbb]

It's interesting that PS2 and XBOX versions of the games have different world mapping, but I think this is out of the scope of this LLOD-improvements PR.

Don't get me wrong I didn't mean that you should fix this :) It was just a note that game files are different on some platforms.

We cannot be sure on how much port has differences. Not only xbox, ps2 and pc. The newer versions mainly use the xbox version, but who knows if they left out something OR re-added missing objects for example. (They could also added new objects, object-placements which were missing from ps2/xbox but were existed in dev files.)

The xbox and ps2 persions created at the same time, but ps2 was the superior. Yet they still could have made differences in xbox's .ipl and .ide files for some reason. (very likely they didn't) PC is ported from xbox, and they cut of a lot of objects from the .ipl files there who knows why. But that doesn't mean that these objects not even exist, they can be used, they still have LLODs as well but never used in the game. So for someone who wants to collect the LLOD ids by deleting objects in map editor is not ideal if the objects newer placed at all.

Problem is if the ports also have different .ide files, then the objects doesn't even exist. (Very likely the .ide files are not touched, only .ipl files are)
However this wouldn't affect the LLOD table at all since these objects newer existed in the game files of PC port. (or at least the PC port which MTA is based on)

And btw, the site you give me is very good, I didn't read it fully but I already read some things which I didn't know and I'm always interested to read about this game, especially if its new to me.

I'd like to point out that these sites, and youtube videos etc are mainly based on very dedicated person's self observations when playing the game. So like nobody had the chance to have all main ports game files at their side and make comparisons between them, they just noticed these changes/differences by playing :)

What i wrote now has nothing to do with this PR and it's just a side note.
If one read this, and wants to 'fix' this problem then he/she should get all game files (.ipl and ide if we talk about objects) of every platform (mainly ps2, xbox and pc) and make the file comparisons.
Then if its done, then the missing object placements from .ipl file could be added into the mapfixes resource.
But comparing these files are not the hard work, getting them it is.

[Fernando-A-Rocha]

@derxgbb Thank you for the observations. Indeed, we could work on improving the mapfixes resource to add missing objects etc!

I didn't mind you mentioning this stuff on this PR as it is related to the theme of LODs. :-)

[Fernando-A-Rocha]

The provided LOD model list not only is incomplete, it also contains plain incorrections. Examples are the LLODs for HLOD models 10428, 10369, 10439.

I made a few experiments and a script to generate the new HLOD=>LLOD table (fixed, no missing models or incorrect assignments) directly from games files. I've commited the newly generated file! Now, with model names and IPL file names!

mtasa-blue/Shared/mods/deathmatch/logic/CLodModels.cpp

Lines 18 to 29 in 81c971a

	constexpr std::array<std::pair<std::uint32_t, std::uint32_t>, OBJ_LOD_MODELS_COUNT> OBJ_LOD_MODELS = {{
	{694, 784}, // sm_redwoodgrp => lod_redwoodgrp (countryS)
	{791, 785}, // vbg_fir_copse => lod_vbg_fir_co (countrye)
	{1259, 1268}, // billbd1 => lodlbd1 (LAe)
	{1260, 1266}, // billbd3 => lodlbd3 (LAe)
	{1267, 1261}, // billbd2 => lodlbd2 (LAe)
	{1309, 1325}, // bigbillbrd => lodlbrd (vegasS)
	{1376, 1397}, // containercrane_03 => lodtainercrane_03 (SFSe)
	{1378, 1396}, // containercrane_04 => lodtainercrane_04 (LAs2)
	{2785, 2786}, // cj_slot_bank => lodcj_slot_bank (int_veg)
	{3167, 3340}, // trailer_large1_01 => lodtrail_lg1_01 (countrye)
	{3168, 3343}, // trailer2_01 => lodtrail2_01 (countn2)

⚠️ However, I noticed that the game applies different LODs for 3 cases of the same model, depending on the placed object, for these specific HLOD models:

HLOD 3427 (derrick01):

• LLOD 16274 (oilderricklod01)
• LLOD 16274 (oilderricklod02)
• LLOD 16274 (oilderricklod03)
• LLOD 16274 (oilderricklod04)
• LLOD 16274 (oilderricklod05)
• LLOD 16274 (oilderricklod06)
• LLOD 16274 (oilderricklod07)

HLOD 3303 (des_bighus03):

• LLOD 3373 (lod_d_bighus3_)
• 3372 (lod_d_bighus2_)

HLOD 3724 (laxrf_cargotop):

• LLOD 5164 (lodcargoshp03d)
• LLOD 5352 (lodcargoshp03f)

Here Rockstar applies different LLODs for HLOD 16273 (derrick01), which can be oilderricklod02, oilderricklod03 etc... Also happens for des_bighus03 and laxrf_cargotop. Doesn't happen for any other HLOD models. This seems pointless.

[Fernando-A-Rocha]

Upon closer inspection of the models that have multiple LLODs for one HLOD, I conclude that Rockstar was dumb by duplicating DFFs that are all the same both visually and size.

Case of 3427 (derrick01):

[Fernando-A-Rocha]

Case of 3303 (des_bighus03):

The two LLOD models are extremely similar. There is no point having two.

Case of 3724 (laxrf_cargotop):

[Fernando-A-Rocha]

✅ I conclude that these 3 different models with various super similar LLODs were mistakes made by the creators.

I have chosen only 1 LOD for each of these 3 models in CLodModels.cpp (that best match the High Level of Detail model) :D

[Fernando-A-Rocha]

In my opinion this is now ready to be implemented. I'd be happy to hear from the people who have commented on this PR previously.

[TheNormalnij]

I would suggest to move these functions into a resource. So developers will able to customize the list with their own models

[lotsofs]

ProcessLineOfSight is useful, but about .5% of LLODs are not caught by it. Indeed, I have started deleting the entirety of San Andreas in the map editor to compile a list of removeWorldObjects in the .map file which contains both HLOD and LLOD models, and apply manual corrections where applicable. It's about 40% done. It takes a bit of time, but it's also kind of therapeutic so I mind not. Once it's done it can be put side by side with your newly automatic generated list and we can investigate discrepancies. Unfortunately I have neglected to make note of the special cases that required manual correction.

[Fernando-A-Rocha]

Once it's done it can be put side by side with your newly automatic generated list and we can investigate discrepancies. Unfortunately I have neglected to make note of the special cases that required manual correction.

Please comment again when you've compared the table I've generated with yours.

If you look at the comment at the end of each line in OBJ_LOD_MODELS (CLodModels.cpp), you see that all LLOD model names contain 'lod' in the name, and generally correspond to a matching HLOD model name.
Exception: 11497 (des_baitshop) => 11615 (desN_baitshop) doesn't contain 'lod' in the name.
Additionally, these LLOD models are declared in .ide files with different .txd that include lower resolution textures.
e.g.

I'm sure with high certainty that this table is correct.

[Fernando-A-Rocha]

I would suggest to move these functions into a resource. So developers will able to customize the list with their own models

The benefit of not having a resource is so that new .map generated by the Map Editor can have native LOD support without the need to include a separate resource just for this in the server, thanks to small .lua script included in the map resource (without a HUGE lods lua table).

See multitheftauto/mtasa-resources#556

I can easily make a "set function" to "customize this list" in this c++ PR. Let me try.

[Fernando-A-Rocha]

Done, check it out @TheNormalnij