EngineReplaceModel: Difference between revisions

Latest revision as of 13:27, 3 November 2022

This function replaces the given model ID with the model contained in a DFF file loaded by engineLoadDFF. This function supports vehicles, objects, peds and players but not CJ clothing and body parts.

To replace weapon models you must use their object IDs, not weapon IDs. There is a weapon model list available at weapons.

Note:

Please note the loading order that is used in the examples as other orders can cause collisions, textures or the DFF not to load due to technical limitations.
Default GTA map objects behave inconsistently when using this function on them. If you want to replace models in the original GTA map, use one of the methods shown here.
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.

Syntax

bool engineReplaceModel ( dff theModel, int modelID [, bool alphaTransparency = false ] )

OOP Syntax Help! I don't understand this!

Method: dff:replace(...)

Required Arguments

theModel: The model to replace the given model ID with
modelID: The model it to replace the model of

Optional Arguments

alphaTransparency: 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

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.

Example

Click to collapse [-]

Client

This example allows you to replace single or many models (with ability to toggle TXD filtering/DFF alpha transparency) - by using table. 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 .col is not present set to false/nil
			txdFile = "vehicle.txd",
			dffFile = "vehicle.dff",
			modelID = 434,
			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)

@@ Line 1: / Line 1: @@
 __NOTOC__
-{{Client function}}<!-- Change this to "Client function" or "Server function" appropriately-->
+{{Client function}}
-<!-- Describe in plain english what this function does. Don't go into details, just give an overview -->
-This function replaces the given model in the given model ID with the DFF file passed. This function supports vehicles and objects at the moment.
+This function replaces the given model ID with the model contained in a DFF file loaded by [[engineLoadDFF]]. This function supports [[vehicle|vehicles]], [[object|objects]], [[ped|peds]] and [[player|players]] but not CJ clothing and body parts.
+{{Deprecated feature|3.0111|1.1.1|This function does not support ped and weapon models.}}
+To replace weapon models you must use their object IDs, not weapon IDs. There is a weapon model list available at [[weapons]].
+{{Note|
+* Please note the loading order that is used in the examples as other orders can cause collisions, textures or the DFF not to load due to technical limitations.
+* Default GTA map objects behave inconsistently when using this function on them. If you want to replace models in the original GTA map, use one of the [[EngineReplaceModel notes|methods shown here]].
+* 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.}}
 ==Syntax==
-<!-- NOTE: don't use 'special' names for variable names, e.g. you shouldn't be writing things like 'player player, vehicle vehicle', instead write something like 'player thePlayer, vehicle vehicleToGetInto'. This is less confusing and prevents the syntax highlighting being odd -->
 <syntaxhighlight lang="lua">
-bool engineReplaceModel ( dff theModel, number modelID )
+bool engineReplaceModel ( dff theModel, int modelID [, bool alphaTransparency = false ] )
 </syntaxhighlight>
+{{OOP||[[DFF|dff]]:replace}}
 ===Required Arguments===
-<!-- List each argument one per line. This should be the argument's name as in the argument list above, NOT the argument's data type -->
 *'''theModel:''' The model to replace the given model ID with
 *'''modelID:''' The model it to replace the model of
+===Optional Arguments===
+*'''alphaTransparency:''' 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===
-<!-- Make this descriptive. Explain what cases will return false. If you're unsure, add a tag to it so we can check -->
 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.
 ==Example==
-<!-- Explain what the example is in a single sentance -->
+<section name="Client" class="client" show="true">
-This example does...
+This example allows you to replace single or many models (with ability to toggle TXD filtering/DFF alpha transparency) - by using [[table]]. Do not forget to add those file paths to [[meta.xml]]
-<!-- Add the code below, an emphasis should be on making it clear, not optimized. You could provide two versions if you wish, one clear and well commented, the other optimized -->
 <syntaxhighlight lang="lua">
-TODO
+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 .col is not present set to false/nil
+			txdFile = "vehicle.txd",
+			dffFile = "vehicle.dff",
+			modelID = 434,
+			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)
 </syntaxhighlight>
+</section>
 ==See Also==
-<!-- Change FunctionArea to the area that this function is in on the main function list page, e.g. Server, Player, Vehicle etc -->
 {{Engine_functions}}
-[[Category:Needs_Example]] <!-- leave this until the example is completed. -->