Writing your first plugin¶

The first plugin will be a very simple one. But before writing any code, youhave to create the plugin files.

To do so, please create a directory in Source.Python’s plugin directory(../addons/source-python/plugins). All plugins will be located in thisdirectory and must have their own sub-directory. Give the new createddirectory an arbitrary name (e.g. test1). Now, you need to create the actualplugin file. It must be named like its directory. So, if you have created atest1 directory, you have to create atest1.py in that directory.

The first plugin should simply print a message to the server console, when theplugin has been loaded and another message when the plugin has been unloaded.You can easily do that by adding aload and anunload function to yourplugin file. These two functions will be called by Source.Python when theplugin is loaded or unloaded.

To print a message to the console you can use Python’sprint function.

Your plugin should now look like this.

defload():print('Plugin has been loaded successfully!')defunload():print('Plugin has been unloaded successfully!')

To load your plugin entersppluginloadtest1 in your server console. Tounload or reload it, you can usesppluginreloadtest1 orsppluginunloadtest1.Source.Python plugins are not getting loaded automatically. Thus, you need toadd the statementsppluginloadtest1 to yourautoexec.cfg if you wishthis behaviour.

Modifying your first plugin¶

Just sending a message to the server console is not very exciting. Moreover,players on your server don’t even noticed that. Therefore, this section willshow you how to send the message to the chat of all players.

To send a message to a player you can make use of themessages module.It provides various classes to send different kinds of messages. For exampleyou can send messages to the player’s chat or directly in the center of theplayer’s screen. In this example we will usemessages.SayText2,because we want to print the message in the chat of each player. The basicprocedure to send a message is very simple.

1. Create an object of the desired message class.

2. Send the message by using itssend() method.

Your plugin should now look like this.

frommessagesimportSayText2defload():SayText2('Plugin has been loaded successfully!').send()defunload():SayText2('Plugin has been unloaded successfully!').send()

Using events in your first plugin¶

Admittedly, this plugin is still very boring, but that will change immediatelywhen you listen to events. Before continuing please read theevent introduction. It will give you a shortoverview of what events are and how to listen to them.

We will now listen to theplayer_spawn event to give every player a littleextra HP when they spawn. To modify the player’s health you need an object oftheplayers.entity.Player class. Its constructor only requiresa player index. Since theplayer_spawn event provides the user ID of theplayer that spawned, you can useplayers.helpers.index_from_userid() toconvert the user ID into a player index.

Your plugin should now look like this.

fromeventsimportEventfromplayers.entityimportPlayerfromplayers.helpersimportindex_from_useridfrommessagesimportSayText2# Extra amount of health every player should get on spawnEXTRA_HP=25defload():SayText2('Plugin has been loaded successfully!').send()defunload():SayText2('Plugin has been unloaded successfully!').send()@Event('player_spawn')defon_player_spawn(game_event):# Get the user ID of the spawned playeruserid=game_event['userid']# Convert the user ID into a player indexindex=index_from_userid(userid)# Create a Player object...player=Player(index)# ... to add some extra HPplayer.health+=EXTRA_HP

Alternatively, you can use the classmethodplayers.entity.Player.from_userid(). It’s a wrapper aroundplayers.helpers.index_from_userid() and will shorten your code inevents.

fromeventsimportEventfromplayers.entityimportPlayerfrommessagesimportSayText2# Extra amount of health every player should get on spawnEXTRA_HP=25defload():SayText2('Plugin has been loaded successfully!').send()defunload():SayText2('Plugin has been unloaded successfully!').send()@Event('player_spawn')defon_player_spawn(game_event):# Create a Player object from the user ID...player=Player.from_userid(game_event['userid'])# ... and add some extra HPplayer.health+=EXTRA_HP

What’s next?¶

You should definitely take a look at themodule tutorials section.It contains detailed tutorials about some Source.Python modules/packages.

Moreover, you should take a look at theModule Index. It’s a list of allSource.Python modules/packages and contains the API documentation.