<h2>A first example with a first character<aclass="headerlink"href="#a-first-example-with-a-first-character"title="Permalink to this headline">¶</a></h2>
<p>Let’s create a character to begin with.</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>@charcreate a merchant
</pre></div>
</div>
<p>This will create a merchant in the room where you currently are. It doesn’t have anything, like a
description, you can decorate it a bit if you like.</p>
<p>As said above, the in-game Python system consists in linking objects with arbitrary code. This code
will be executed in some circumstances. Here, the circumstance is “when someone says something in
the same room”, and might be more specific like “when someone says hello”. We’ll decide what code
to run (we’ll actually type the code in-game). Using the vocabulary of the in-game Python system,
we’ll create a callback: a callback is just a set of lines of code that will run under some
conditions.</p>
<p>You can have an overview of every “conditions” in which callbacks can be created using the <codeclass="docutils literal notranslate"><spanclass="pre">@call</span></code>
command (short for <codeclass="docutils literal notranslate"><spanclass="pre">@callback</span></code>). You need to give it an object as argument. Here for instance, we
could do:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>@call a merchant
</pre></div>
</div>
<p>You should see a table with three columns, showing the list of events existing on our newly-created
merchant. There are quite a lot of them, as it is, althougn no line of code has been set yet. For
our system, you might be more interested by the line describing the <codeclass="docutils literal notranslate"><spanclass="pre">say</span></code> event:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>| say | 0 (0) | After another character has said something in |
| | | the character's room. |
</pre></div>
</div>
<p>We’ll create a callback on the <codeclass="docutils literal notranslate"><spanclass="pre">say</span></code> event, called when we say “hello” in the merchant’s room:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>@call/add a merchant = say hello
</pre></div>
</div>
<p>Before seeing what this command displays, let’s see the command syntax itself:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">@call</span></code> is the command name, <codeclass="docutils literal notranslate"><spanclass="pre">/add</span></code> is a switch. You can read the help of the command to get the
help of available switches and a brief overview of syntax.</p></li>
<li><p>We then enter the object’s name, here “a merchant”. You can enter the ID too (“#3” in my case),
which is useful to edit the object when you’re not in the same room. You can even enter part of the
name, as usual.</p></li>
<li><p>An equal sign, a simple separator.</p></li>
<li><p>The event’s name. Here, it’s “say”. The available events are displayed when you use <codeclass="docutils literal notranslate"><spanclass="pre">@call</span></code>
without switch.</p></li>
<li><p>After a space, we enter the conditions in which this callback should be called. Here, the
conditions represent what the other character should say. We enter “hello”. Meaning that if
someone says something containing “hello” in the room, the callback we are now creating will be
called.</p></li>
</ul>
<p>When you enter this command, you should see something like this:</p>
<p>That’s some list of information. What’s most important to us now is:</p>
<ulclass="simple">
<li><p>The “say” event is called whenever someone else speaks in the room.</p></li>
<li><p>We can set callbacks to fire when specific keywords are present in the phrase by putting them as
additional parameters. Here we have set this parameter to “hello”. We can have several keywords
separated by a comma (we’ll see this in more details later).</p></li>
<li><p>We have three default variables we can use in this callback: <codeclass="docutils literal notranslate"><spanclass="pre">speaker</span></code> which contains the
character who speaks, <codeclass="docutils literal notranslate"><spanclass="pre">character</span></code> which contains the character who’s modified by the in-game Python
system (here, or merchant), and <codeclass="docutils literal notranslate"><spanclass="pre">message</span></code> which contains the spoken phrase.</p></li>
</ul>
<p>This concept of variables is important. If it makes things more simple to you, think of them as
parameters in a function: they can be used inside of the function body because they have been set
when the function was called.</p>
<p>This command has opened an editor where we can type our Python code.</p>
<p>For our first test, let’s type something like:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="n">character</span><spanclass="o">.</span><spanclass="n">location</span><spanclass="o">.</span><spanclass="n">msg_contents</span><spanclass="p">(</span><spanclass="s2">"</span><spanclass="si">{character}</span><spanclass="s2"> shrugs and says: 'well, yes, hello to you!'"</span><spanclass="p">,</span>
<p>Once you have entered this line, you can type <codeclass="docutils literal notranslate"><spanclass="pre">:wq</span></code> to save the editor and quit it.</p>
<p>And now if you use the “say” command with a message containing “hello”:</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="n">You</span><spanclass="n">say</span><spanclass="p">,</span><spanclass="s2">"Hello sir merchant!"</span>
<spanclass="n">a</span><spanclass="n">merchant</span><spanclass="p">(</span><spanclass="c1">#3) shrugs and says: 'well, yes, hello to you!'</span>
</pre></div>
</div>
<p>If you say something that doesn’t contain “hello”, our callback won’t execute.</p>
<p><strong>In summary</strong>:</p>
<olclass="simple">
<li><p>When we say something in the room, using the “say” command, the “say” event of all characters
(except us) is called.</p></li>
<li><p>The in-game Python system looks at what we have said, and checks whether one of our callbacks in
the “say” event contains a keyword that we have spoken.</p></li>
<li><p>If so, call it, defining the event variables as we have seen.</p></li>
<li><p>The callback is then executed as normal Python code. Here we have called the <codeclass="docutils literal notranslate"><spanclass="pre">msg_contents</span></code>
method on the character’s location (probably a room) to display a message to the entire room. We
have also used mapping to easily display the character’s name. This is not specific to the in-game
Python system. If you feel overwhelmed by the code we’ve used, just shorten it and use something
more simple, for instance:</p></li>
</ol>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="n">speaker</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"You have said something to me."</span><spanclass="p">)</span>
<h2>The same callback for several keywords<aclass="headerlink"href="#the-same-callback-for-several-keywords"title="Permalink to this headline">¶</a></h2>
<p>It’s easy to create a callback that will be triggered if the sentence contains one of several
keywords.</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>@call/add merchant = say trade, trader, goods
</pre></div>
</div>
<p>And in the editor that opens:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="n">character</span><spanclass="o">.</span><spanclass="n">location</span><spanclass="o">.</span><spanclass="n">msg_contents</span><spanclass="p">(</span><spanclass="s2">"</span><spanclass="si">{character}</span><spanclass="s2"> says: 'Ho well, trade's fine as long as roads are</span>
<p>Then you can say something with either “trade”, “trader” or “goods” in your sentence, which should
call the callback:</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="n">You</span><spanclass="n">say</span><spanclass="p">,</span><spanclass="s2">"and how is your trade going?"</span>
<spanclass="n">a</span><spanclass="n">merchant</span><spanclass="p">(</span><spanclass="c1">#3) says: 'Ho well, trade's fine as long as roads are safe.'</span>
</pre></div>
</div>
<p>We can set several keywords when adding the callback. We just need to separate them with commas.</p>
</section>
<sectionid="a-longer-callback">
<h2>A longer callback<aclass="headerlink"href="#a-longer-callback"title="Permalink to this headline">¶</a></h2>
<p>So far, we have only set one line in our callbacks. Which is useful, but we often need more. For
an entire dialogue, you might want to do a bit more than that.</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>@call/add merchant = say bandit, bandits
</pre></div>
</div>
<p>And in the editor you can paste the following lines:</p>
<spanclass="n">character</span><spanclass="o">.</span><spanclass="n">location</span><spanclass="o">.</span><spanclass="n">msg_contents</span><spanclass="p">(</span><spanclass="s2">"</span><spanclass="si">{character}</span><spanclass="s2"> scratches his head, considering."</span><spanclass="p">,</span>
<spanclass="n">character</span><spanclass="o">.</span><spanclass="n">location</span><spanclass="o">.</span><spanclass="n">msg_contents</span><spanclass="p">(</span><spanclass="s2">"</span><spanclass="si">{character}</span><spanclass="s2"> whispers: 'Aye, saw some of them, north from here. No</span>
<spanclass="n">speaker</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"</span><spanclass="si">{character}</span><spanclass="s2"> looks at you more</span>
<spanclass="n">speaker</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"</span><spanclass="si">{character}</span><spanclass="s2"> continues in a low voice: 'Ain't my place to say, but if you need to find</span>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="n">You</span><spanclass="n">say</span><spanclass="p">,</span><spanclass="s2">"have you seen bandits?"</span>
<spanclass="n">a</span><spanclass="n">merchant</span><spanclass="p">(</span><spanclass="c1">#3) scratches his head, considering.</span>
<spanclass="n">a</span><spanclass="n">merchant</span><spanclass="p">(</span><spanclass="c1">#3) whispers: 'Aye, saw some of them, north from here. No trouble o' mine, but...'</span>
<spanclass="n">a</span><spanclass="n">merchant</span><spanclass="p">(</span><spanclass="c1">#3) looks at you more closely.</span>
<spanclass="n">a</span><spanclass="n">merchant</span><spanclass="p">(</span><spanclass="c1">#3) continues in a low voice: 'Ain't my place to say, but if you need to find 'em,</span>
<spanclass="n">they</span><spanclass="s1">'re encamped some distance away from the road, I guess near a cave or something.'</span><spanclass="o">.</span>
</pre></div>
</div>
<p>Notice here that the first lines of dialogue are spoken to the entire room, but then the merchant is
talking directly to the speaker, and only the speaker hears it. There’s no real limit to what you
can do with this.</p>
<ulclass="simple">
<li><p>You can set a mood system, storing attributes in the NPC itself to tell you in what mood he is,
which will influence the information he will give… perhaps the accuracy of it as well.</p></li>
<li><p>You can add random phrases spoken in some context.</p></li>
<li><p>You can use other actions (you’re not limited to having the merchant say something, you can ask
him to move, gives you something, attack if you have a combat system, or whatever else).</p></li>
<li><p>The callbacks are in pure Python, so you can write conditions or loops.</p></li>
<li><p>You can add in “pauses” between some instructions using chained events. This tutorial won’t
describe how to do that however. You already have a lot to play with.</p></li>
</ul>
</section>
<sectionid="tutorial-f-a-q">
<h2>Tutorial F.A.Q.<aclass="headerlink"href="#tutorial-f-a-q"title="Permalink to this headline">¶</a></h2>
<ulclass="simple">
<li><p><strong>Q:</strong> can I create several characters who would answer to specific dialogue?</p></li>
<li><p><strong>A:</strong> of course. Te in-game Python system is so powerful because you can set unique code for
various objects. You can have several characters answering to different things. You can even have
different characters in the room answering to greetings. All callbacks will be executed one after
another.</p></li>
<li><p><strong>Q:</strong> can I have two characters answering to the same dialogue in exactly the same way?</p></li>
<li><p><strong>A:</strong> It’s possible but not so easy to do. Usually, event grouping is set in code, and depends
on different games. However, if it is for some infrequent occurrences, it’s easy to do using
