engineReplaceModel | Multi Theft Auto: Wiki Skip to content
Multi Theft Auto: Wiki

engineReplaceModel

Client-side
Server-side
Shared

Pair: engineRestoreModel

This function replaces the given model with the model contained in a DFF file loaded by engineLoadDFF.

Note
  • Follow loading order ( COL -> TXD -> DFF ) which is used in the example - as other orders can cause collisions, textures or the DFF not to load.
  • Default GTA map objects behave inconsistently when using this function on them. If you want to replace models in the original GTA map, you need to call engineRestreamWorld after replacing models as well.
  • A raw data DFF element can only be used once, because the underlying memory for the model is released after replacement.
  • If the replacement model is broken and the original model is not loaded/streamed-in at the time of replacement, this function will succeed and you won't see any error message, neither when the model replacement fails once the original model starts to load/stream-in.
Tip
  • If you want to replace CJ's clothing, check out clothes replacement guide.
  • To replace weapon models you must use their object IDs, not weapon IDs. There is a weapon model list available at weapons list.

OOP Syntax Help! I don't understand this!

  • Method:dff:replace(...)

Syntax 

​bool engineReplaceModel ( ​dff theModel, ​string/​int modelNameOrID, [ ​bool alphaTransparency = false ] )
Required Arguments
  • theModel: The model to replace the given model with.
  • modelNameOrID: The model ID or name of the model to be replaced.
Optional Arguments

NOTE: When using optional arguments, you might need to supply all arguments before the one you wish to use.

  • alphaTransparency (default: false): Set to true if model uses semi-transparent textures, e.g. windows. This will ensure other objects behind the semi-transparent textures are rendered correctly. Can slightly impact performance, so only set when required.

Returns

  • bool: result

Returns true if the model was successfully replaced, false if it failed for some reason, ie. the DFF or the model ID is not valid.

Code Examples

client

This example allows you to replace single or many models (with ability to toggle TXD filtering/DFF alpha transparency) - by usingtable. Do not forget to add those file paths to meta.xml.

function onClientResourceStartReplaceModels()
  local modelsToReplace = {
    { -- replace object
      colFile = "object.col",
      txdFile = "object.txd",
      dffFile = "object.dff",
      modelID = 1337,
      alphaTransparency = false,
      filteringEnabled = true,
    },
    { -- replace vehicle
      colFile = false, -- if file is not present set to false/nil
      txdFile = "vehicle.txd",
      dffFile = "vehicle.dff",
      modelID = 434,
      alphaTransparency = false,
      filteringEnabled = true,
    },
    { -- replace skin
      colFile = false, -- if file is not present set to false/nil
      txdFile = "ped.txd",
      dffFile = "ped.dff",
      modelID = 16,
      alphaTransparency = false,
      filteringEnabled = true,
    },
    { -- replace weapon
      colFile = false, -- if file is not present set to false/nil
      txdFile = "m4.txd",
      dffFile = "m4.dff",
      modelID = 356,
      alphaTransparency = false,
      filteringEnabled = true,
    },
  }


  for assetID = 1, #modelsToReplace do
    local modelData = modelsToReplace[assetID]
    local modelCol = modelData.colFile
    local modelTxd = modelData.txdFile
    local modelDff = modelData.dffFile
    local modelID = modelData.modelID


    if (modelCol) then
      local colData = engineLoadCOL(modelCol)


      if (colData) then
        engineReplaceCOL(colData, modelID)
      end
    end


    if (modelTxd) then
      local filteringEnabled = modelData.filteringEnabled
      local txdData = engineLoadTXD(modelTxd, filteringEnabled)


      if (txdData) then
        engineImportTXD(txdData, modelID)
      end
    end


    if (modelDff) then
      local dffData = engineLoadDFF(modelDff)


      if (dffData) then
        local alphaTransparency = modelData.alphaTransparency


        engineReplaceModel(dffData, modelID, alphaTransparency)
      end
    end
  end
end
addEventHandler("onClientResourceStart", resourceRoot, onClientResourceStartReplaceModels)

See Also

Engine Functions
Engine Elements
Reference