Mtasa-blue: Add efficient modding interface for new model ID's

[TheNormalnij]

Is your feature request related to a problem? Please describe.

• [x] engineReplaceModel stores file in RAM (fixed via IMG loading)
• [x] engineImportTexture stores textures in RAM (fixed via IMG loading)
• [ ] engineReplaceCol doesn't support col's library (.col with few collisions)
• [x] We can't set model flags and fix some rendering issues (object with alpha disable render for objects behind this object) and collision issues (#1702) (Fixed via #1702)
  This is a reason why we can't properly load big mods

Describe the solution you'd like

I want to load IMG and stream files from this archive and add some engine functions and change some API.

Rename API

engineRequestModel can be renamed into engineRequestNew

IMG support

Done in #1677
Main functions engineAddImage and engineImageLinkModel

Add engineGetStreamOffset

local  iOffset =  engineGetStreamOffset( "txd"/"dff"/"col"/"Ifp" )

Will return:
0 for dff
20000 for txd
25000 for col
25256 for ipl
25575 for ifp

This function can return another values when limit adjuster will be added

Add TXD support

-- Register new TXD
local txdID = engineRequestNew( "txd", "TXDNAME" ) -- will assigned to existing txd
local iStreamOffset = engineGetStreamOffset( "txd" ) + txdID -- Get stream offest
engineImageLinkModel( pIMG, "file.txd", iStreamOffset ) -- Assign file to new txd

-- Assign txd to existing files
engineSetModelTXDID( 1337, txdID )
engineSetModelTXDID( 1338, txdID )

Change engineRequestModel API

local newModelID = engineRequestNew( "obejct", "MODEL_NAME", "MODEL_TXD_NAME", drawDistance, flags )
engineImageLinkModel( pIMG, "file.dff", newModelID  ) -- DFF has 0 stream offset

New will have custom name. By default assigned to existing gta file ( from 1337 model )
If MTA find txd "MODEL_TXD_NAME" this txdID will be used for this model
flags - IDE flags

Same with another types, "vehicle", "timed-object", "animated-object" "weapon-object" we will use IDE syntax

Add COL from IMG support

local colID = engineRequestNew( "col", "COLNAME(?)" ) --Allocate COL id
local iStreamOffset = engineGetStreamOffset( "col" ) + colID -- Get stream offest
engineImageLinkModel( pIMG, "file.col", iStreamOffset )
engineLoadCol( colID ) -- Will load all cols from "file.col" and assign collisions to models.

engineLoadCol will find models by name in COL

Add IFP support

-- Register new IFP
local ifpID = engineRequestNew( "ifp", "IFPNAME" ) -- will assigned to existing ifp
local iStreamOffset = engineGetStreamOffset( "ifp" ) + ifpID -- Get stream offest
engineImageLinkModel( pIMG, "file.ifp", iStreamOffset ) -- Assign file to new txd

-- Assign ifp to existing files
engineSetModelIFPID( 1337, ifpID )
engineSetModelIFPID( 1338, ifpID )

Additional context

An error.img file can be add into MTA client and assign new models to this file.

[AlexTMjugador]

Renaming engineRequestModel to engineRequestNew does not convince me. Why renaming it instead of adding engineRequestTXD, engineRequestDFF and such? I feel that the "new" suffix makes the function name needlessly different (no MTA function I'm aware of ends like that), and engine functions are already named in a way that is pretty specific for the RW resource they work with, so I think it is more consistent to keep it like that.

On the other hand, if engineGetStreamOffset is meant to return constants that may change over time as MTA limits are adjusted, I think that a better API would be one that makes using its return value unnecessary, so scripters can't make the mistake of hardcoding the current return values and call it a day. My proposal is to make engineImageLinkModel probe the file type and automatically add the correct offset to the ID, rendering engineGetStreamOffset unnecessary.

Also, speaking of engineImageLinkModel, I think that the "model" part of the name is not very accurate provided that it also works with IFPs and TXDs, so I'd name it otherwise, but right now I can't think of a name that's a lot better. engineImageLinkResource, perhaps?

Other than these nitpicks, this looks good 👍

[TheNormalnij]

GTA use few classes for DFF, maybe this will be better:
engineRequestVehicle
engineRequestPed
engineRequestObject
engineRequestTimedObject
engineRequestDamagableObject -- not sure because gta uses flag in IDE to detect this type
engineRequestTXD
engineRequestCOL
engineRequestIFP
... by file format

[saml1er]

engineReplaceCol doesn't support col's library (.col with few collisions)

@TheNormalnij hmm? col library? can you elaborate?

@AlexTMjugador

On the other hand, if engineGetStreamOffset is meant to return constants that may change over time as MTA limits are adjusted, I think that a better API would be one that makes using its return value unnecessary, so scripters can't make the mistake of hardcoding the current return values and call it a day. My proposal is to make engineImageLinkModel probe the file type and automatically add the correct offset to the ID, rendering engineGetStreamOffset unnecessary.

Yes, I fully agree with this.

Also, speaking of engineImageLinkModel, I think that the "model" part of the name is not very accurate provided that it also works with IFPs and TXDs, so I'd name it otherwise, but right now I can't think of a name that's a lot better. engineImageLinkResource, perhaps?

I think engineImageLinkModel is fine. We have engineReplaceModel and that might be a bit confusing, but it won't be an issue with documentation.

[TheNormalnij]

My proposal is to make engineImageLinkModel probe the file type and automatically add the correct offset to the ID, rendering engineGetStreamOffset unnecessary.

Also, speaking of engineImageLinkModel, I think that the "model" part of the name is not very accurate provided that it also works with IFPs and TXDs, so I'd name it otherwise, but right now I can't think of a name that's a lot better. engineImageLinkResource, perhaps?

engineImageLinkDFF
engineImageLinkTXD
engineImageLinkCOL

[AlexTMjugador]

GTA use few classes for DFF, maybe this will be better:
engineRequestVehicle
engineRequestPed
engineRequestObject
engineRequestTimedObject
engineRequestDamagableObject -- not sure because gta uses flag in IDE to detect this type

In that case I'd fancy a function named engineRequestDFF with a string parameter that specifies the exact type of DFF to be requested; for example, engineRequestDFF("vehicle", ...). I think that's a good balance between function profileration and function specifity, but of course this is up to discussion.

[TheNormalnij]

hmm? col library? can you elaborate?

Modelers concat few col files into one to save size in img. Block size in IMG is 2048 bytes and col file can have extremely small size 100 bytes.

[tederis]

hmm? col library? can you elaborate?

Modelers concat few col files into one to save size in img. Block size in IMG is 2048 bytes and col file can have extremely small size 100 bytes.

The size saving is not the main reason for this. Collisions should be grouped together for the sake of RAM saving and collision detection perfomance. The physics engine internally has many optimizations relying on the COLL zone structure.

[Pirulax]

My proposal is to make engineImageLinkModel probe the file type and automatically add the correct offset to the ID, rendering engineGetStreamOffset unnecessary.

Also, speaking of engineImageLinkModel, I think that the "model" part of the name is not very accurate provided that it also works with IFPs and TXDs, so I'd name it otherwise, but right now I can't think of a name that's a lot better. engineImageLinkResource, perhaps?

engineImageLinkDFF
engineImageLinkTXD
engineImageLinkCOL

Would it be possible to add a single function, like:
engineImageLink(pImg, "veh.txd", "txd")?
Or perhaps, as suggested, probe the file, and automatically figure out the type?