<h1>Getting started<aclass="headerlink" href="#getting-started" title="Link to this heading">¶</a></h1>
<p>If you would like to start developing server plugins with Source.Python this is
the right place for you!</p>
<p>In order to use Source.Python you first need to install it on your game server. To
do so, please follow the instructions described <aclass="reference internal" href="../general/installation.html"><spanclass="doc">here</span></a>.</p>
<p>As soon as you have successfully installed Source.Python you can start writing
your first plugin.</p>
<sectionid="writing-your-first-plugin">
<h2>Writing your first plugin<aclass="headerlink" href="#writing-your-first-plugin" title="Link to this heading">¶</a></h2>
<p>The first plugin will be a very simple one. But before writing any code, you
have to create the plugin files.</p>
<p>To do so, please create a directory in Source.Python’s plugin directory
(<codeclass="docutils literal notranslate"><spanclass="pre">../addons/source-python/plugins</span></code>). All plugins will be located in this
directory and must have their own sub-directory. Give the new created
directory an arbitrary name (e.g. test1). Now, you need to create the actual
plugin file. It must be named like its directory. So, if you have created a
<codeclass="docutils literal notranslate"><spanclass="pre">test1</span></code> directory, you have to create a <codeclass="docutils literal notranslate"><spanclass="pre">test1.py</span></code> in that directory.</p>
<p>The first plugin should simply print a message to the server console, when the
plugin has been loaded and another message when the plugin has been unloaded.
You can easily do that by adding a <codeclass="docutils literal notranslate"><spanclass="pre">load</span></code> and an <codeclass="docutils literal notranslate"><spanclass="pre">unload</span></code> function to your
plugin file. These two functions will be called by Source.Python when the
plugin is loaded or unloaded.</p>
<p>To print a message to the console you can use Python’s
<spanclass="nb">print</span><spanclass="p">(</span><spanclass="s1">'Plugin has been unloaded successfully!'</span><spanclass="p">)</span>
</pre></div>
</div>
<p>To load your plugin enter <codeclass="docutils literal notranslate"><spanclass="pre">sp</span><spanclass="pre">plugin</span><spanclass="pre">load</span><spanclass="pre">test1</span></code> in your server console. To
unload or reload it, you can use <codeclass="docutils literal notranslate"><spanclass="pre">sp</span><spanclass="pre">plugin</span><spanclass="pre">reload</span><spanclass="pre">test1</span></code> or
Source.Python plugins are not getting loaded automatically. Thus, you need to
add the statement <codeclass="docutils literal notranslate"><spanclass="pre">sp</span><spanclass="pre">plugin</span><spanclass="pre">load</span><spanclass="pre">test1</span></code> to your <codeclass="docutils literal notranslate"><spanclass="pre">autoexec.cfg</span></code> if you wish
this behaviour.</p>
</section>
<sectionid="modifying-your-first-plugin">
<h2>Modifying your first plugin<aclass="headerlink" href="#modifying-your-first-plugin" title="Link to this heading">¶</a></h2>
<p>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 will
show you how to send the message to the chat of all players.</p>
<p>To send a message to a player you can make use of the <aclass="reference internal" href="modules/messages.html#module-messages" title="messages"><codeclass="xref py py-mod docutils literal notranslate"><spanclass="pre">messages</span></code></a> module.
It provides various classes to send different kinds of messages. For example
you can send messages to the player’s chat or directly in the center of the
player’s screen. In this example we will use <aclass="reference internal" href="modules/messages.html#messages.SayText2" title="messages.SayText2"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">messages.SayText2</span></code></a>,
because we want to print the message in the chat of each player. The basic
procedure to send a message is very simple.</p>
<olclass="arabic simple">
<li><p>Create an object of the desired message class.</p></li>
<li><p>Send the message by using its <aclass="reference internal" href="modules/messages.base.html#messages.base.UserMessageCreator.send" title="messages.base.UserMessageCreator.send"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">send()</span></code></a> method.</p></li>
<spanclass="n">SayText2</span><spanclass="p">(</span><spanclass="s1">'Plugin has been loaded successfully!'</span><spanclass="p">)</span><spanclass="o">.</span><spanclass="n">send</span><spanclass="p">()</span>
<spanclass="n">SayText2</span><spanclass="p">(</span><spanclass="s1">'Plugin has been unloaded successfully!'</span><spanclass="p">)</span><spanclass="o">.</span><spanclass="n">send</span><spanclass="p">()</span>
</pre></div>
</div>
</section>
<sectionid="using-events-in-your-first-plugin">
<h2>Using events in your first plugin<aclass="headerlink" href="#using-events-in-your-first-plugin" title="Link to this heading">¶</a></h2>
<p>Admittedly, this plugin is still very boring, but that will change immediately
when you listen to events. Before continuing please read the
<aclass="reference external" href="events.html#introduction">event introduction</a>. It will give you a short
overview of what events are and how to listen to them.</p>
<p>We will now listen to the <codeclass="docutils literal notranslate"><spanclass="pre">player_spawn</span></code> event to give every player a little
extra HP when they spawn. To modify the player’s health you need an object of
the <aclass="reference internal" href="modules/players.entity.html#players.entity.Player" title="players.entity.Player"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">players.entity.Player</span></code></a> class. Its constructor only requires
a player index. Since the <codeclass="docutils literal notranslate"><spanclass="pre">player_spawn</span></code> event provides the user ID of the
player that spawned, you can use <aclass="reference internal" href="modules/players.helpers.html#players.helpers.index_from_userid" title="players.helpers.index_from_userid"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">players.helpers.index_from_userid()</span></code></a> to
<spanclass="n">SayText2</span><spanclass="p">(</span><spanclass="s1">'Plugin has been loaded successfully!'</span><spanclass="p">)</span><spanclass="o">.</span><spanclass="n">send</span><spanclass="p">()</span>
<spanclass="n">SayText2</span><spanclass="p">(</span><spanclass="s1">'Plugin has been unloaded successfully!'</span><spanclass="p">)</span><spanclass="o">.</span><spanclass="n">send</span><spanclass="p">()</span>
<codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">players.entity.Player.from_userid()</span></code>. It’s a wrapper around
<aclass="reference internal" href="modules/players.helpers.html#players.helpers.index_from_userid" title="players.helpers.index_from_userid"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">players.helpers.index_from_userid()</span></code></a> and will shorten your code in
<spanclass="n">SayText2</span><spanclass="p">(</span><spanclass="s1">'Plugin has been loaded successfully!'</span><spanclass="p">)</span><spanclass="o">.</span><spanclass="n">send</span><spanclass="p">()</span>
<spanclass="n">SayText2</span><spanclass="p">(</span><spanclass="s1">'Plugin has been unloaded successfully!'</span><spanclass="p">)</span><spanclass="o">.</span><spanclass="n">send</span><spanclass="p">()</span>
<h2>What’s next?<aclass="headerlink" href="#what-s-next" title="Link to this heading">¶</a></h2>
<p>You should definitely take a look at the <aclass="reference internal" href="module_tutorials.html"><spanclass="doc">module tutorials section</span></a>.
It contains detailed tutorials about some Source.Python modules/packages.</p>
<p>Moreover, you should take a look at the <aclass="reference internal" href="../py-modindex.html"><spanclass="std std-ref">Module Index</span></a>. It’s a list of all
Source.Python modules/packages and contains the API documentation.</p>