AddCommandHandler: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
(→‎Example: Improved example)
Line 49: Line 49:
-- If a player triggered this in-game
-- If a player triggered this in-game
if ( playerSource ) then
if ( playerSource ) then
-- Check we've got all 4 parameters
-- Get the player's vehicle
if ( col1 and col2 and col3 and col4 ) then
playerVehicle = getPlayerOccupiedVehicle ( playerSource )
-- Get the player's vehicle
-- If the player is in a vehicle and we've got at least 1 parameter
playerVehicle = getPlayerOccupiedVehicle ( playerSource )
if ( playerVehicle and col1 ) then
-- Set it's color
-- Get the vehicle's existing color and use it if fewer than 4 arguments were passed
exCol1, exCol2, exCol3, exCol4 = getVehicleColor ( playerVehicle )
 
if not col2 then col2 = exCol2 end
if not col3 then col3 = exCol3 end
if not col4 then col4 = exCol4 end
 
-- Set the vehicle's color
setVehicleColor ( playerVehicle, col1, col2, col3, col4 )
setVehicleColor ( playerVehicle, col1, col2, col3, col4 )
else
else
-- If we didn't get all 4 parameters, display some help text
-- If we didn't get at least 1 parameter or the player doesn't have a vehicle, display some help text
outputConsole ( "This function will set a vehicle's colors. A vehicle can have up to 4 colors.", playerSource )
outputConsole ( "This function will set your current vehicle's colors. A vehicle can have up to 4 colors.", playerSource )
outputConsole ( "Syntax: set_vehicle_color color1 color2 color color4", playerSource )
outputConsole ( "Syntax: set_vehicle_color color1 [ color2 color3 color4 ]", playerSource )
outputConsole ( "You must be in a vehicle to use this function.", playerSource )
end
end
end
end

Revision as of 10:06, 31 August 2006

This function will create a console command and attach it to a function, so that whenever a player or administrator uses the command the function is called.

Multiple command handlers can be attached to a single function, and they will be called in the order that the handlers were attached. Equally, multiple commands can be handled by a single function, and the commandName parameter used to decide the course of action.

Syntax

bool addCommandHandler ( string commandName, string handlerFunction )

Required Arguments

  • commandName: This is the name of the command you wish to add. This is what must be typed into the console to trigger the function.
  • handlerFunction: This is the name of the function that you want the command to trigger. This function should take two parameters, playerSource and commandName followed by as many parameters you expect after your command.
player playerSource, string commandName, [string args ...] 
  • playerSource: The player who triggered the command. If not triggered by a player (e.g. by admin), this will be false.
  • commandName: The name of the command triggered. This is useful if multiple commands go through one function.
  • args: Each word after command name in the original command is passed here in seperate variables. If there is no value for an argument, the variable will contain nil.

Returns

Returns true if the command handler was added successfully, false otherwise.

Example

Example 1: This example defines a command handler for the command createmarker. This will create a red marker at the player who uses it's position.

-- Register the command handler and attach it to the 'consoleCreateMarker' function
addCommandHandler ( "createmarker", "consoleCreateMarker" )
-- Define our function that will handle this command
function consoleCreateMarker ( playerSource, commandName )
	-- If a player triggered it (rather than the admin) then
	if ( playerSource )
		-- Get that player's position
		x, y, z = getEntityPosition ( playerSource )
		-- Create a marker at their position
		createMarker ( x, y, z, 0, "checkpoint", 255, 0, 0, 255 )
		-- Output it in the chat box
		outputChatBox ( "You got a red marker", playerSource )
	end
end

Example 2: This example implements a set_vehicle_color function.

-- Register the command handler and attach it to the 'consoleCreateMarker' function
addCommandHandler ( "set_vehicle_color", "consoleSetVehicleColor" )
-- Define our function that will handle this command
function consoleSetVehicleColor ( playerSource, commandName, col1, col2, col3, col4 )
	-- If a player triggered this in-game
	if ( playerSource ) then
		-- Get the player's vehicle
		playerVehicle = getPlayerOccupiedVehicle ( playerSource )
		-- If the player is in a vehicle and we've got at least 1 parameter
		if ( playerVehicle and col1 ) then
			-- Get the vehicle's existing color and use it if fewer than 4 arguments were passed
			exCol1, exCol2, exCol3, exCol4 = getVehicleColor ( playerVehicle )

			if not col2 then col2 = exCol2 end
			if not col3 then col3 = exCol3 end
			if not col4 then col4 = exCol4 end

			-- Set the vehicle's color
			setVehicleColor ( playerVehicle, col1, col2, col3, col4 )
		else
			-- If we didn't get at least 1 parameter or the player doesn't have a vehicle, display some help text
			outputConsole ( "This function will set your current vehicle's colors. A vehicle can have up to 4 colors.", playerSource )
			outputConsole ( "Syntax: set_vehicle_color color1 [ color2 color3 color4 ]", playerSource )
			outputConsole ( "You must be in a vehicle to use this function.", playerSource )
		end
	end
end

See Also