<spanid="evennia-contrib-rpg-rpsystem-rplanguage"></span><h1>evennia.contrib.rpg.rpsystem.rplanguage<aclass="headerlink"href="#module-evennia.contrib.rpg.rpsystem.rplanguage"title="Permalink to this headline">¶</a></h1>
<p>Language and whisper obfuscation system</p>
<p>Evennia contrib - Griatch 2015</p>
<p>This module is intented to be used with an emoting system (such as
contrib/rpsystem.py). It offers the ability to obfuscate spoken words
in the game in various ways:</p>
<ulclass="simple">
<li><dlclass="simple">
<dt>Language: The language functionality defines a pseudo-language map</dt><dd><p>to any number of languages. The string will be obfuscated depending
on a scaling that (most likely) will be input as a weighted average of
the language skill of the speaker and listener.</p>
</dd>
</dl>
</li>
<li><dlclass="simple">
<dt>Whisper: The whisper functionality will gradually “fade out” a</dt><dd><p>whisper along as scale 0-1, where the fading is based on gradually
removing sections of the whisper that is (supposedly) easier to
overhear (for example “s” sounds tend to be audible even when no other
meaning can be determined).</p>
</dd>
</dl>
</li>
</ul>
<sectionid="usage">
<h2>Usage<aclass="headerlink"href="#usage"title="Permalink to this headline">¶</a></h2>
<h2>Custom languages<aclass="headerlink"href="#custom-languages"title="Permalink to this headline">¶</a></h2>
<p>To set up new languages, you need to run <strong>add_language()</strong>
helper function in this module. The arguments of this function (see below)
are used to store the new language in the database (in the LanguageHandler,
which is a type of Script).</p>
<p>If you want to remember the language definitions, you could put them all
in a module along with the <strong>add_language</strong> call as a quick way to
rebuild the language on a db reset:</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># a stand-alone module somewhere under mygame. Just import this</span>
<spanclass="c1"># once to automatically add the language!</span>
<spanclass="c1"># you need a representative of all of the minimal grammars here, so if a</span>
<spanclass="c1"># grammar v exists, there must be atleast one phoneme available with only</span>
<spanclass="c1"># one vowel in it</span>
<spanclass="n">phonemes</span><spanclass="o">=</span><spanclass="p">(</span><spanclass="s2">"oi oh ee ae aa eh ah ao aw ay er ey ow ia ih iy "</span>
<spanclass="s2">"oy ua uh uw y p b t d f v t dh s z sh zh ch jh k "</span>
<spanclass="s2">"ng g m n l r w"</span><spanclass="p">)</span>
<spanclass="c1"># how much the translation varies in length compared to the original. 0 is</span>
<spanclass="c1"># smallest, higher values give ever bigger randomness (including removing</span>
<emclass="property">exception </em><codeclass="sig-prename descclassname">evennia.contrib.rpg.rpsystem.rplanguage.</code><codeclass="sig-name descname">LanguageError</code><aclass="reference internal"href="../_modules/evennia/contrib/rpg/rpsystem/rplanguage.html#LanguageError"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.rpg.rpsystem.rplanguage.LanguageError"title="Permalink to this definition">¶</a></dt>
<emclass="property">exception </em><codeclass="sig-prename descclassname">evennia.contrib.rpg.rpsystem.rplanguage.</code><codeclass="sig-name descname">LanguageExistsError</code><aclass="reference internal"href="../_modules/evennia/contrib/rpg/rpsystem/rplanguage.html#LanguageExistsError"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.rpg.rpsystem.rplanguage.LanguageExistsError"title="Permalink to this definition">¶</a></dt>
<emclass="property">class </em><codeclass="sig-prename descclassname">evennia.contrib.rpg.rpsystem.rplanguage.</code><codeclass="sig-name descname">LanguageHandler</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/rpg/rpsystem/rplanguage.html#LanguageHandler"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.rpg.rpsystem.rplanguage.LanguageHandler"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">at_script_creation</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/rpg/rpsystem/rplanguage.html#LanguageHandler.at_script_creation"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.rpg.rpsystem.rplanguage.LanguageHandler.at_script_creation"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">add</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">key</span><spanclass="o">=</span><spanclass="default_value">'default'</span></em>, <emclass="sig-param"><spanclass="n">phonemes</span><spanclass="o">=</span><spanclass="default_value">'ea oh ae aa eh ah ao aw ai er ey ow ia ih iy oy ua uh uw a e i u y p b t d f v t dh s z sh zh ch jh k ng g m n l r w'</span></em>, <emclass="sig-param"><spanclass="n">grammar</span><spanclass="o">=</span><spanclass="default_value">'v cv vc cvv vcc vcv cvcc vccv cvccv cvcvcc cvccvcv vccvccvc cvcvccvv cvcvcvcvv'</span></em>, <emclass="sig-param"><spanclass="n">word_length_variance</span><spanclass="o">=</span><spanclass="default_value">0</span></em>, <emclass="sig-param"><spanclass="n">noun_translate</span><spanclass="o">=</span><spanclass="default_value">False</span></em>, <emclass="sig-param"><spanclass="n">noun_prefix</span><spanclass="o">=</span><spanclass="default_value">''</span></em>, <emclass="sig-param"><spanclass="n">noun_postfix</span><spanclass="o">=</span><spanclass="default_value">''</span></em>, <emclass="sig-param"><spanclass="n">vowels</span><spanclass="o">=</span><spanclass="default_value">'eaoiuy'</span></em>, <emclass="sig-param"><spanclass="n">manual_translations</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">auto_translations</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">force</span><spanclass="o">=</span><spanclass="default_value">False</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/rpg/rpsystem/rplanguage.html#LanguageHandler.add"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.rpg.rpsystem.rplanguage.LanguageHandler.add"title="Permalink to this definition">¶</a></dt>
<dd><p>Add a new language. Note that you generally only need to do
this once per language and that adding an existing language
will re-initialize all the random components to new permanent
values.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>key</strong> (<em>str</em><em>, </em><em>optional</em>) – The name of the language. This
will be used as an identifier for the language so it
should be short and unique.</p></li>
<li><p><strong>phonemes</strong> (<em>str</em><em>, </em><em>optional</em>) – Space-separated string of all allowed
phonemes in this language. If either of the base phonemes
(c, v, cc, vv) are present in the grammar, the phoneme list must
at least include one example of each.</p></li>
<li><p><strong>grammar</strong> (<em>str</em>) – All allowed consonant (c) and vowel (v) combinations
allowed to build up words. Grammars are broken into the base phonemes
(c, v, cc, vv) prioritizing the longer bases. So cvv would be a
the c + vv (would allow for a word like ‘die’ whereas
cvcvccc would be c+v+c+v+cc+c (a word like ‘galosch’).</p></li>
<li><p><strong>word_length_variance</strong> (<em>real</em>) – The variation of length of words.
0 means a minimal variance, higher variance may mean words
have wildly varying length; this strongly affects how the
language “looks”.</p></li>
<li><p><strong>noun_translate</strong> (<em>bool</em><em>, </em><em>optional</em>) – If a proper noun should be translated or
not. By default they will not, allowing for e.g. the names of characters
to be understandable. A ‘noun’ is identified as a capitalized word
<em>not at the start of a sentence</em>. This simple metric means that names
starting a sentence always will be translated (- but hey, maybe
the fantasy language just never uses a noun at the beginning of
sentences, who knows?)</p></li>
<li><p><strong>noun_prefix</strong> (<em>str</em><em>, </em><em>optional</em>) – A prefix to go before every noun
in this language (if any).</p></li>
<li><p><strong>noun_postfix</strong> (<em>str</em><em>, </em><em>optuonal</em>) – A postfix to go after every noun
in this language (if any, usually best to avoid combining
with <strong>noun_prefix</strong> or language becomes very wordy).</p></li>
<li><p><strong>vowels</strong> (<em>str</em><em>, </em><em>optional</em>) – Every vowel allowed in this language.</p></li>
<li><p><strong>manual_translations</strong> (<em>dict</em><em>, </em><em>optional</em>) – This allows for custom-setting
certain words in the language to mean the same thing. It is
on the form <strong>{real_word: fictional_word}</strong>, for example
<strong>{“the”, “y’e”}</strong> .</p></li>
<li><p><strong>auto_translations</strong> (<em>str</em><em> or </em><em>list</em><em>, </em><em>optional</em>) – These are lists
words that should be auto-translated with a random, but
fixed, translation. If a path to a file, this file should
contain a list of words to produce translations for, one
word per line. If a list, the list’s elements should be
the words to translate. The <strong>manual_translations</strong> will
always override overlapping translations created
automatically.</p></li>
<li><p><strong>force</strong> (<em>bool</em><em>, </em><em>optional</em>) – Unless true, will not allow the addition
of a language that is already created.</p></li>
</ul>
</dd>
<dtclass="field-even">Raises</dt>
<ddclass="field-even"><p><aclass="reference internal"href="#evennia.contrib.rpg.rpsystem.rplanguage.LanguageExistsError"title="evennia.contrib.rpg.rpsystem.rplanguage.LanguageExistsError"><strong>LanguageExistsError</strong></a>– Raised if trying to adding a language
with a key that already exists, without <strong>force</strong> being set.</p>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>The <strong>word_file</strong> is for example a word-frequency list for
the N most common words in the host language. The
translations will be random, but will be stored
persistently to always be the same. This allows for
building a quick, decently-sounding fictive language that
tend to produce the same “translation” (mostly) with the
<codeclass="sig-name descname">translate</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">text</span></em>, <emclass="sig-param"><spanclass="n">level</span><spanclass="o">=</span><spanclass="default_value">0.0</span></em>, <emclass="sig-param"><spanclass="n">language</span><spanclass="o">=</span><spanclass="default_value">'default'</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/rpg/rpsystem/rplanguage.html#LanguageHandler.translate"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.rpg.rpsystem.rplanguage.LanguageHandler.translate"title="Permalink to this definition">¶</a></dt>
<dd><p>Translate the text according to the given level.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>text</strong> (<em>str</em>) – The text to translate</p></li>
<li><p><strong>level</strong> (<em>real</em>) – Value between 0.0 and 1.0, where
0.0 means no obfuscation (text returned unchanged) and
1.0 means full conversion of every word. The closer to
1, the shorter words will be translated.</p></li>
<li><p><strong>language</strong> (<em>str</em>) – The language key identifier.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>text (str)</em>– A translated string.</p>
<emclass="property">exception </em><codeclass="sig-name descname">DoesNotExist</code><aclass="headerlink"href="#evennia.contrib.rpg.rpsystem.rplanguage.LanguageHandler.DoesNotExist"title="Permalink to this definition">¶</a></dt>
<emclass="property">exception </em><codeclass="sig-name descname">MultipleObjectsReturned</code><aclass="headerlink"href="#evennia.contrib.rpg.rpsystem.rplanguage.LanguageHandler.MultipleObjectsReturned"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">path</code><emclass="property"> = 'evennia.contrib.rpg.rpsystem.rplanguage.LanguageHandler'</em><aclass="headerlink"href="#evennia.contrib.rpg.rpsystem.rplanguage.LanguageHandler.path"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">typename</code><emclass="property"> = 'LanguageHandler'</em><aclass="headerlink"href="#evennia.contrib.rpg.rpsystem.rplanguage.LanguageHandler.typename"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-prename descclassname">evennia.contrib.rpg.rpsystem.rplanguage.</code><codeclass="sig-name descname">obfuscate_language</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">text</span></em>, <emclass="sig-param"><spanclass="n">level</span><spanclass="o">=</span><spanclass="default_value">0.0</span></em>, <emclass="sig-param"><spanclass="n">language</span><spanclass="o">=</span><spanclass="default_value">'default'</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/rpg/rpsystem/rplanguage.html#obfuscate_language"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.rpg.rpsystem.rplanguage.obfuscate_language"title="Permalink to this definition">¶</a></dt>
<dd><p>Main access method for the language parser.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>text</strong> (<em>str</em>) – Text to obfuscate.</p></li>
<li><p><strong>level</strong> (<em>real</em><em>, </em><em>optional</em>) – A value from 0.0-1.0 determining
the level of obfuscation where 0 means no obfuscation
(string returned unchanged) and 1.0 means the entire
string is obfuscated.</p></li>
<li><p><strong>language</strong> (<em>str</em><em>, </em><em>optional</em>) – The identifier of a language
the system understands.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>translated (str)</em>– The translated text.</p>
<codeclass="sig-prename descclassname">evennia.contrib.rpg.rpsystem.rplanguage.</code><codeclass="sig-name descname">add_language</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/rpg/rpsystem/rplanguage.html#add_language"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.rpg.rpsystem.rplanguage.add_language"title="Permalink to this definition">¶</a></dt>
<dd><p>Access function to creating a new language. See the docstring of
<strong>LanguageHandler.add</strong> for list of keyword arguments.</p>
<codeclass="sig-prename descclassname">evennia.contrib.rpg.rpsystem.rplanguage.</code><codeclass="sig-name descname">available_languages</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/rpg/rpsystem/rplanguage.html#available_languages"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.rpg.rpsystem.rplanguage.available_languages"title="Permalink to this definition">¶</a></dt>
<dd><p>Returns all available language keys.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Returns</dt>
<ddclass="field-odd"><p><em>languages (list)</em>– List of key strings of all available
<codeclass="sig-prename descclassname">evennia.contrib.rpg.rpsystem.rplanguage.</code><codeclass="sig-name descname">obfuscate_whisper</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">whisper</span></em>, <emclass="sig-param"><spanclass="n">level</span><spanclass="o">=</span><spanclass="default_value">0.0</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/rpg/rpsystem/rplanguage.html#obfuscate_whisper"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.rpg.rpsystem.rplanguage.obfuscate_whisper"title="Permalink to this definition">¶</a></dt>
<dd><p>Obfuscate whisper depending on a pre-calculated level
(that may depend on distance, listening skill etc)</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>whisper</strong> (<em>str</em>) – The whisper string to obscure. The
entire string will be considered in the obscuration.</p></li>
<li><p><strong>level</strong> (<em>real</em><em>, </em><em>optional</em>) – This is a value 0-1, where 0
means not obscured (whisper returned unchanged) and 1
