EngineReplaceModel: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
 
(35 intermediate revisions by 16 users not shown)
Line 1: Line 1:
__NOTOC__  
__NOTOC__  
{{Client function}}
{{Client function}}
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.


Note: Due to a bug, when replacing models with built in collisions (i.e. vehicles), the collision may not get replaced correctly. The current work around is to load the dff again and do another replace after a short delay.
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 example 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==  
==Syntax==  
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
bool engineReplaceModel ( dff theModel, int modelID )
bool engineReplaceModel ( dff theModel, int modelID [, bool alphaTransparency = false ] )
</syntaxhighlight>  
</syntaxhighlight>  
 
{{OOP||[[DFF|dff]]:replace}}
===Required Arguments===  
===Required Arguments===  
*'''theModel:''' The model to replace the given model ID with
*'''theModel:''' The model to replace the given model ID with
*'''modelID:''' The model it to replace the model of
*'''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===
Line 18: Line 29:


==Example==  
==Example==  
'''Example 1:'''
<section name="Client" class="client" show="true">
<section name="Client" class="client" show="true">
Client-Side example for replacing vehicle collisions, model and texture with custom ones.
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]]
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
function ReplaceVehicle ( )
function onClientResourceStartReplaceModels()
outputChatBox ( "> replacing the euros vehicle" )
local modelsToReplace = {
{ -- replace object (all object IDs here: https://dev.prineside.com/en/gtasa_samp_model_id/)
colFile = "object.col",
txdFile = "object.txd",
dffFile = "object.dff",
modelID = 1337,
alphaTransparency = false,
filteringEnabled = true,
},
{ -- replace vehicle (all vehicle IDs here: https://wiki.multitheftauto.com/wiki/Vehicle_IDs)
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 (all ped IDs here: https://wiki.multitheftauto.com/wiki/Character_Skins)
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 (all weapon IDs here: https://wiki.multitheftauto.com/wiki/Weapons)
colFile = false, -- if file is not present set to false/nil
txdFile = "m4.txd",
dffFile = "m4.dff",
modelID = 356,
alphaTransparency = false,
filteringEnabled = true,
},
}


--We will not load the TXD for now
for assetID = 1, #modelsToReplace do
  dff = engineLoadDFF ( "data/euros.dff", 587 ) --Load the DFF for first time with an ID specified (required for collisions)
local modelData = modelsToReplace[assetID]
  engineReplaceModel ( dff, 587 ) --Replace it for first time
local modelCol = modelData.colFile
  x, y, z = getElementPosition ( getLocalPlayer() ) -- Get the player position
local modelTxd = modelData.txdFile
  vehicle = createVehicle ( 587, x, y+3, z ) -- Create the vehicle near player position (the car you want to replace must be near the player for the collisions)
local modelDff = modelData.dffFile
  setTimer ( function () destroyElement ( vehicle ) end, 3000, 1 ) -- Destroy it after 3000 seconds
local modelID = modelData.modelID
  setTimer ( function () -- Now we will load the TXD for first time, and the DFF for second time
    txd = engineLoadTXD ( "data/euros.txd" )--Load the TXD
    engineImportTXD ( txd, 587 )
 
    dff = engineLoadDFF ( "data/euros.dff", 587 ) --Load the DFF for second time
    engineReplaceModel ( dff, 587 )
  end, 50, 1 )
end


addEvent ( "replaceVeh", true )
if (modelCol) then
addEventHandler ( "replaceVeh", getRootElement(), ReplaceVehicle )
local colData = engineLoadCOL(modelCol)
</syntaxhighlight>
</section>
<section name="Server" class="server" show="true">
Server-side example function for triggering the replace.
<syntaxhighlight lang="lua">
function ReplaceCommand ( )
triggerClientEvent( "replaceVeh", getRootElement(), replaceVeh )
end
addCommandHandler( "replace", ReplaceCommand )
</syntaxhighlight>
</section>


'''Example 2:'''
if (colData) then
<section name="Client" class="client" show="true">
engineReplaceCOL(colData, modelID)
Client-Side example for replacing object model, collision and texture with custom ones.
end
<syntaxhighlight lang="lua">
end
function ReplaceObject ( )


txd = engineLoadTXD( "MyModel.txd" )
if (modelTxd) then
col = engineLoadCOL( "MyModel.col" )
local filteringEnabled = modelData.filteringEnabled
dff = engineLoadDFF( "MyModel.dff", 0 ) --modelid is everytime 0, when you replace no vehicle
local txdData = engineLoadTXD(modelTxd, filteringEnabled)


engineImportTXD( txd, 1234 )
if (txdData) then
engineReplaceCOL( col, 1234 )
engineImportTXD(txdData, modelID)
engineReplaceModel( dff, 1234 )-- replace the model at least
end
end


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


addEvent ( "replaceObj", true )
if (dffData) then
addEventHandler ( "replaceObj", getRootElement(), ReplaceObject )
local alphaTransparency = modelData.alphaTransparency
</syntaxhighlight>
</section>
engineReplaceModel(dffData, modelID, alphaTransparency)
<section name="Server" class="server" show="true">
end
Server-side example function for triggering the replace.
end
<syntaxhighlight lang="lua">
end
function ReplaceCommand ( )
triggerClientEvent( "replaceObj", getRootElement(), replaceObj )
end
end
addCommandHandler( "replace", ReplaceCommand )
addEventHandler("onClientResourceStart", resourceRoot, onClientResourceStartReplaceModels)
</syntaxhighlight>
</syntaxhighlight>
</section>
</section>

Latest revision as of 21:35, 2 August 2024

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.

[[{{{image}}}|link=|]] Note:
  • Please note the loading order that is used in the example 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 (all object IDs here: https://dev.prineside.com/en/gtasa_samp_model_id/)
			colFile = "object.col",
			txdFile = "object.txd",
			dffFile = "object.dff",
			modelID = 1337,
			alphaTransparency = false,
			filteringEnabled = true,
		},
		{ -- replace vehicle (all vehicle IDs here: https://wiki.multitheftauto.com/wiki/Vehicle_IDs)
			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 (all ped IDs here: https://wiki.multitheftauto.com/wiki/Character_Skins)
			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 (all weapon IDs here: https://wiki.multitheftauto.com/wiki/Weapons)
			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


Retrieved from "https://wiki.multitheftauto.com/wiki/EngineReplaceModel?oldid=79984"