Player Events

@player.on_join

Fired when a player successfully connects to the server

Note

This event will not trigger for failed login attempts; for instance, when a player is banned

Parameters	Type	Description
player*	PlayerScriptObject	Player who joined
data*	dict	{'user': str, 'uuid': str, 'ip': str, 'date': datetime, 'logged-in': bool}
delay	int / float	Wait before running the block, in seconds

@player.on_join(player, data):
    player.log(f'Welcome to {server}, {player}!')

@player.on_leave

Fired when a player disconnects from the server

Note

data['playtime'] is the total delta of the player’s session length between their login and logout times. This is necessary since player.playtime returns None if the player is not connected, and this event is fired after the player has disconnected

Parameters	Type	Description
player*	PlayerScriptObject	Player who left
data*	dict	{'user': str, 'uuid': str, 'ip': str, 'date': datetime, 'logged-in': bool, 'playtime': timedelta}
delay	int / float	Wait before running the block, in seconds

@player.on_leave(player, data):
    server.broadcast(f'Goodbye, {player}!')
    server.log(f'{player} was online for {data["playtime"]}')

@player.on_message

Fired when a player sends a message in the chat, excluding commands

Parameters	Type	Description
player*	PlayerScriptObject	Player who sent the message
message*	str	Message content
delay	int / float	Wait before running the block, in seconds

@player.on_message(player, message):
    if "can i have op" in message.lower():
        acl.ban_player(player)

@player.on_death

Fired when a player dies from another player, or the environment

Parameters	Type	Description
player*	PlayerScriptObject	Victim
enemy*	PlayerScriptObject / None	Attacker, or None if environmental
message*	str	Message content
delay	int / float	Wait before running the block, in seconds

@player.on_death(player, enemy, message):
    if enemy:
        enemy.log(f"Did you know: murder is a crime {enemy}?")
        acl.ban_player(enemy)
    else:
        player.log(f"You should really be more careful {player}!")

@player.on_achieve

Fired upon a player earning an advancement

Parameters	Type	Description
player*	PlayerScriptObject	Awarded player
advancement*	str	Advancement title; see all advancement titles
delay	int / float	Wait before running the block, in seconds

@player.on_achieve(player, advancement):
    if advancement == 'Stone Age':
        player.log_success(f'Seriously {player}?? Pick... on someone your own size!')

@player.on_alias

Used for registering custom commands and augmenting existing ones

Note

amscript commands start with !; therefore making calls visible when executed by a player from the in-game chat. Feedback is hidden when using the server.log() and player.log() methods. They are completely hidden if executed from the server console

Parameters	Type	Description
player*	PlayerScriptObject	Player who executed the command
command*	str	Define the command verb
arguments	dict	Argument map for execution: {'arg1': True, 'arg2': False, ...}   • Argument names are arbitrary. Values can be retrieved with arguments['name']   • True denotes a required argument; optional arguments must follow all required arguments
permission	str	Restricts execution to privileged users; can be 'anyone', 'op', 'server', or a custom permission. Defaults to 'anyone'
description	str	Description displayed in the !help menu; the entry will only be shown to users who meet the minimum permission level
hidden	bool	Defaults to False. Hides the command from !help and suppresses automatic permission/syntax error feedback, but permission and argument validation still apply. This is used for augmenting existing commands

@player.on_alias(player, command='test', arguments={'arg1': True, 'arg2': False}, permission='op'):
    server.log(f'{player.name} executed {command} with the following arguments: {arguments}')

Note

Every alias automatically validates syntax and checks the player’s permission level before execution. The server permission only applies to running amscript commands from the Console

Following the above example when a player with the anyone privilege executes !test foo bar:

• amscript will determine that the player doesn’t meet the minimum permission and will fail
• Permission tree order is: server > op > anyone

Following the above example when a player with the op or server privilege executes !test foo bar:

• arguments will be converted to {'arg1': 'foo', 'arg2': 'bar'} after execution, and can be accessed in the function as such
• Calling arguments['arg1'] will return the value of 'foo'