OnPlayerConnect: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
(Improved examples; added comment about if-else hell)
 
(22 intermediate revisions by 13 users not shown)
Line 2: Line 2:
{{Server event}}
{{Server event}}
This event is triggered when a player attempts to connect to the server.
This event is triggered when a player attempts to connect to the server.
 
{{MessageBox|
  bordercolorhex = CC3333 |
  bgcolorhex = FF8888 |
  message = '''WARNING:'''
* You should never, under any circumstances, modify the player returned by [[getPlayerFromName]] before [[onPlayerJoin]] to avoid desynchronization (e.g. [[setPlayerName]]).
* If you want to set custom disconnect text, [[cancelEvent]] '''should be called at the end''' of the onPlayerConnect event, otherwise the client will be displayed the default text if any other event, native or custom, is triggered before cancelling.
}}
==Parameters==
==Parameters==
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
string playerNick, string playerIP, string playerUsername, string playerSerial, int playerVersion
string playerNick, string playerIP, string playerUsername, string playerSerial, int playerVersionNumber, string playerVersionString
</syntaxhighlight>  
</syntaxhighlight>  


Line 12: Line 18:
*'''playerUsername''': The player's community username.
*'''playerUsername''': The player's community username.
*'''playerSerial''': The player's serial number.
*'''playerSerial''': The player's serial number.
''Extra parameter from 1.0.2 onwards:''
*'''playerVersionNumber''': The player's MTA version in pure numerical form, e.g. ''''256'''' for 1.0, ''''257'''' for 1.0.1, etc.
*'''playerVersion''': The player's MTA version in pure numerical form, e.g. ''''256'''' for 1.0, ''''257'''' for 1.0.1, etc.
*'''playerVersionString''': The player's MTA version in sortable string form. Same as the return value from [[getPlayerVersion]].
 
==Source==
The [[event system#Event source|source]] of this event is the client's [[root element]].


==Cancel effect==
==Cancel effect==
Line 19: Line 28:


==Example==  
==Example==  
<section name="Server" class="server" show="true">
<!-- Explain what the example is in a single sentance -->
This example cancels connection attempts of people who use the nick "Player" or outputs some data about the connecting player otherwise.
This example cancels connection attempts of people who use the nick "Player" or outputs some data about the connecting player otherwise.
<!-- 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">
<syntaxhighlight lang="lua">
--when a player connects
--when a player connects
function playerConnect (playerNick, playerIP, playerUsername, playerSerial, playerVersion)
function playerConnect(playerNick, playerIP, playerUsername, playerSerial)
    if playerNick == "Player" then --check if his nick is "Player"
if playerNick == "Player" then -- check if his nick is "Player"
        cancelEvent(true,"The nick \"Player\" is not allowed, please change it to something else. You can change your nick in Settings menu Multiplayer tab.") --in that case refuse the connection
cancelEvent(true, 'The nick "Player" is not allowed, please change it to something else. You can change your nick in Settings menu Multiplayer tab.')
    else
return -- early return; avoid if-else hell
        --output some data about the player
end
        outputChatBox (playerNick.." just connected to the server.")
-- output some data about the player
        outputChatBox ("IP: "..playerIP.." Username: "..playerUsername.." Serial: "..playerSerial)
outputChatBox(playerNick.." just connected to the server.")
    end
outputChatBox("IP: "..playerIP.." / Username: "..playerUsername.." / Serial: "..playerSerial)
end
end


--add the playerConnect function as a handler for onPlayerConnect
--add the playerConnect function as a handler for onPlayerConnect
addEventHandler ("onPlayerConnect", getRootElement(), playerConnect)
addEventHandler("onPlayerConnect", root, playerConnect)
</syntaxhighlight>
</syntaxhighlight>
</section>
<!-- More info about if-else hell:
 
https://www.freecodecamp.org/news/so-youre-in-if-else-hell-here-s-how-to-get-out-of-it-fc6407fec0e/
https://www.reddit.com/r/programminghorror/comments/bbxnol/ifelse_hell/?rdt=64996
-->


<section name="Server" class="server" show="true">
This example cancels connection if player uses older MTA (older than 1.0.3)
This example cancels connection if player uses older MTA (older than 1.0.3)
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
addEventHandler( "onPlayerConnect", getRootElement(),
function versionCheck(_,_,_,_, clientVersion)
    function ( _,_,_,_, clientVersion )
if clientVersion < 259 then
        if ( clientVersion < 259 ) then
cancelEvent(true, "Update your MTA before you join this server!")
            cancelEvent( true, "Update your MTA before you join this server!" );
end
        end
end
    end
addEventHandler("onPlayerConnect", root, versionCheck)
)
</syntaxhighlight>
</syntaxhighlight>
</section>
 
{{See also/Server event|Player events}}
{{See also/Server event|Player events}}
[[ru:onPlayerConnect]]

Latest revision as of 07:38, 30 October 2023

This event is triggered when a player attempts to connect to the server.

[[{{{image}}}|link=|]] WARNING:
  • You should never, under any circumstances, modify the player returned by getPlayerFromName before onPlayerJoin to avoid desynchronization (e.g. setPlayerName).
  • If you want to set custom disconnect text, cancelEvent should be called at the end of the onPlayerConnect event, otherwise the client will be displayed the default text if any other event, native or custom, is triggered before cancelling.

Parameters

string playerNick, string playerIP, string playerUsername, string playerSerial, int playerVersionNumber, string playerVersionString
  • playerNick: The player's current nickname.
  • playerIP: The player's current IP.
  • playerUsername: The player's community username.
  • playerSerial: The player's serial number.
  • playerVersionNumber: The player's MTA version in pure numerical form, e.g. '256' for 1.0, '257' for 1.0.1, etc.
  • playerVersionString: The player's MTA version in sortable string form. Same as the return value from getPlayerVersion.

Source

The source of this event is the client's root element.

Cancel effect

If this event is canceled, the player will be disconnected with an error message saying the reason specified in cancelEvent or "Disconnected: server refused the connection" if none was specified.

Example

This example cancels connection attempts of people who use the nick "Player" or outputs some data about the connecting player otherwise. 

--when a player connects
function playerConnect(playerNick, playerIP, playerUsername, playerSerial)
	if playerNick == "Player" then -- check if his nick is "Player"
		cancelEvent(true, 'The nick "Player" is not allowed, please change it to something else. You can change your nick in Settings menu Multiplayer tab.')
		return -- early return; avoid if-else hell
	end
	-- output some data about the player
	outputChatBox(playerNick.." just connected to the server.")
	outputChatBox("IP: "..playerIP.." / Username: "..playerUsername.." / Serial: "..playerSerial)
end

--add the playerConnect function as a handler for onPlayerConnect
addEventHandler("onPlayerConnect", root, playerConnect)

This example cancels connection if player uses older MTA (older than 1.0.3) 

function versionCheck(_,_,_,_, clientVersion)
	if clientVersion < 259 then
		cancelEvent(true, "Update your MTA before you join this server!")
	end
end
addEventHandler("onPlayerConnect", root, versionCheck)

See Also

Player events


Event functions

Retrieved from "https://wiki.multitheftauto.com/wiki/OnPlayerConnect?oldid=78458"