<h1>Random Name Generator<aclass="headerlink"href="#random-name-generator"title="Permalink to this headline">¶</a></h1>
<p>Contribution by InspectorCaracal (2022)</p>
<p>A module for generating random names, both real-world and fantasy. Real-world
names can be generated either as first (personal) names, family (last) names, or
full names (first, optional middles, and last). The name data is from <aclass="reference external"href="https://www.behindthename.com/">Behind the Name</a>
and used under the <aclass="reference external"href="https://creativecommons.org/licenses/by-sa/4.0/">CC BY-SA 4.0 license</a>.</p>
<p>Fantasy names are generated from basic phonetic rules, using CVC syllable syntax.</p>
<p>Both real-world and fantasy name generation can be extended to include additional
information via your game’s <codeclass="docutils literal notranslate"><spanclass="pre">settings.py</span></code></p>
<sectionid="installation">
<h2>Installation<aclass="headerlink"href="#installation"title="Permalink to this headline">¶</a></h2>
<p>This is a stand-alone utility. Just import this module (<codeclass="docutils literal notranslate"><spanclass="pre">from</span><spanclass="pre">evennia.contrib.utils</span><spanclass="pre">import</span><spanclass="pre">name_generator</span></code>) and use its functions wherever you like.</p>
</section>
<sectionid="usage">
<h2>Usage<aclass="headerlink"href="#usage"title="Permalink to this headline">¶</a></h2>
<p>Import the module where you need it with the following:</p>
<p>By default, all of the functions will return a string with one generated name.
If you specify more than one, or pass <codeclass="docutils literal notranslate"><spanclass="pre">return_list=True</span></code> as a keyword argument, the returned value will be a list of strings.</p>
<p>The module is especially useful for naming newly-created NPCs, like so:</p>
<h2>Available Settings<aclass="headerlink"href="#available-settings"title="Permalink to this headline">¶</a></h2>
<p>These settings can all be defined in your game’s <codeclass="docutils literal notranslate"><spanclass="pre">server/conf/settings.py</span></code> file.</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">NAMEGEN_FIRST_NAMES</span></code> adds a new list of first (personal) names.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">NAMEGEN_LAST_NAMES</span></code> adds a new list of last (family) names.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">NAMEGEN_REPLACE_LISTS</span></code> - set to <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code> if you want to use only the names defined in your settings.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">NAMEGEN_FANTASY_RULES</span></code> lets you add new phonetic rules for generating entirely made-up names. See the section “Custom Fantasy Name style rules” for details on how this should look.</p></li>
<spanclass="n">NAMEGEN_LAST_NAMES</span><spanclass="o">=</span><spanclass="p">[</span><spanclass="s2">"Beeblebrox"</span><spanclass="p">,</span><spanclass="s2">"Son of Odin"</span><spanclass="p">]</span>
<h2>Generating Real Names<aclass="headerlink"href="#generating-real-names"title="Permalink to this headline">¶</a></h2>
<p>The contrib offers three functions for generating random real-world names:
<codeclass="docutils literal notranslate"><spanclass="pre">first_name()</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">last_name()</span></code>, and <codeclass="docutils literal notranslate"><spanclass="pre">full_name()</span></code>. If you want more than one name
generated at once, you can use the <codeclass="docutils literal notranslate"><spanclass="pre">num</span></code> keyword argument to specify how many.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">first_name</span></code> function also takes a <codeclass="docutils literal notranslate"><spanclass="pre">gender</span></code> keyword argument to filter names
by gender association. ‘f’ for feminine, ‘m’ for masculine, ‘mf’ for feminine
<em>and</em> masculine, or the default <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code> to match any gendering.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">full_name</span></code> function also takes the <codeclass="docutils literal notranslate"><spanclass="pre">gender</span></code> keyword, as well as <codeclass="docutils literal notranslate"><spanclass="pre">parts</span></code> which
defines how many names make up the full name. The minimum is two: a first name and
a last name. You can also generate names with the family name first by setting
the keyword arg <codeclass="docutils literal notranslate"><spanclass="pre">surname_first</span></code> to <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code></p>
<p><codeclass="docutils literal notranslate"><spanclass="pre">NAMEGEN_FIRST_NAMES</span></code> should be a list of tuples, where the first value is the name
and then second value is the gender flag - ‘m’ for masculine-only, ‘f’ for feminine-
only, and ‘mf’ for either one.</p>
<p><codeclass="docutils literal notranslate"><spanclass="pre">NAMEGEN_LAST_NAMES</span></code> should be a list of strings, where each item is an available
<spanclass="n">NAMEGEN_LAST_NAMES</span><spanclass="o">=</span><spanclass="p">[</span><spanclass="s2">"Beeblebrox"</span><spanclass="p">,</span><spanclass="s2">"Son of Odin"</span><spanclass="p">]</span>
</pre></div>
</div>
<p>Set <codeclass="docutils literal notranslate"><spanclass="pre">NAMEGEN_REPLACE_LISTS</span><spanclass="pre">=</span><spanclass="pre">True</span></code> if you want your custom lists above to entirely replace the built-in lists rather than extend them.</p>
</section>
</section>
<sectionid="generating-fantasy-names">
<h2>Generating Fantasy Names<aclass="headerlink"href="#generating-fantasy-names"title="Permalink to this headline">¶</a></h2>
<p>Generating completely made-up names is done with the <codeclass="docutils literal notranslate"><spanclass="pre">fantasy_name</span></code> function. The
contrib comes with three built-in styles of names which you can use, or you can
put a dictionary of custom name rules into <codeclass="docutils literal notranslate"><spanclass="pre">settings.py</span></code></p>
<p>Generating a fantasy name takes the ruleset key as the “style” keyword, and can
return either a single name or multiple names. By default, it will return a
single name in the built-in “harsh” style. The contrib also comes with “fluid” and “alien” styles.</p>
<h3>Multi-Word Fantasy Names<aclass="headerlink"href="#multi-word-fantasy-names"title="Permalink to this headline">¶</a></h3>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">fantasy_name</span></code> function will only generate one name-word at a time, so for multi-word names
you’ll need to combine pieces together. Depending on what kind of end result you want, there are
several approaches.</p>
<sectionid="the-simple-approach">
<h4>The simple approach<aclass="headerlink"href="#the-simple-approach"title="Permalink to this headline">¶</a></h4>
<p>If all you need is for it to have multiple parts, you can generate multiple names at once and <codeclass="docutils literal notranslate"><spanclass="pre">join</span></code> them.</p>
<h4>“Nakku Silversmith”<aclass="headerlink"href="#nakku-silversmith"title="Permalink to this headline">¶</a></h4>
<p>One common fantasy name practice is profession- or title-based surnames. To achieve this effect,
you can use the <codeclass="docutils literal notranslate"><spanclass="pre">last_name</span></code> function with a custom list of last names and combine it with your generated
fantasy name.</p>
<p>Example:</p>
<divclass="highlight-py notranslate"><divclass="highlight"><pre><span></span><spanclass="n">NAMEGEN_LAST_NAMES</span><spanclass="o">=</span><spanclass="p">[</span><spanclass="s2">"Silversmith"</span><spanclass="p">,</span><spanclass="s2">"the Traveller"</span><spanclass="p">,</span><spanclass="s2">"Destroyer of Worlds"</span><spanclass="p">]</span>
<p>Then you could generate names following that ruleset with <codeclass="docutils literal notranslate"><spanclass="pre">namegen.fantasy_name(style="example_style")</span></code>.</p>
<p>The keys <codeclass="docutils literal notranslate"><spanclass="pre">syllable</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">consonants</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">vowels</span></code>, and <codeclass="docutils literal notranslate"><spanclass="pre">length</span></code> must be present, and <codeclass="docutils literal notranslate"><spanclass="pre">length</span></code> must be the minimum and maximum syllable counts. <codeclass="docutils literal notranslate"><spanclass="pre">start</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">end</span></code> are optional.</p>
<sectionid="syllable">
<h4>syllable<aclass="headerlink"href="#syllable"title="Permalink to this headline">¶</a></h4>
<p>The “syllable” field defines the structure of each syllable. C is consonant, V is vowel,
and parentheses mean it’s optional. So, the example <codeclass="docutils literal notranslate"><spanclass="pre">(C)VC</span></code> means that every syllable
will always have a vowel followed by a consonant, and will <em>sometimes</em> have another
consonant at the beginning. e.g. <codeclass="docutils literal notranslate"><spanclass="pre">en</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">bak</span></code></p>
<p><em>Note:</em> While it’s not standard, the contrib lets you nest parentheses, with each layer
being less likely to show up. Additionally, any other characters put into the syllable
structure - e.g. an apostrophe - will be read and inserted as written. The
“alien” style rules in the module gives an example of both: the syllable structure is <codeclass="docutils literal notranslate"><spanclass="pre">C(C(V))(')(C)</span></code>
which results in syllables such as <codeclass="docutils literal notranslate"><spanclass="pre">khq</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">xho'q</span></code>, and <codeclass="docutils literal notranslate"><spanclass="pre">q'</span></code> with a much lower frequency of vowels than
<codeclass="docutils literal notranslate"><spanclass="pre">C(C)(V)(')(C)</span></code> would have given.</p>
</section>
<sectionid="consonants">
<h4>consonants<aclass="headerlink"href="#consonants"title="Permalink to this headline">¶</a></h4>
<p>A simple list of consonant phonemes that can be chosen from. Multi-character strings are
perfectly acceptable, such as “th”, but each one will be treated as a single consonant.</p>
<p>The function uses a naive form of weighting, where you make a phoneme more likely to
occur by putting more copies of it into the list.</p>
</section>
<sectionid="start-and-end">
<h4>start and end<aclass="headerlink"href="#start-and-end"title="Permalink to this headline">¶</a></h4>
<p>These are <strong>optional</strong> lists for the first and last letters of a syllable, if they’re
a consonant. You can add on additional consonants which can only occur at the beginning
or end of a syllable, or you can add extra copies of already-defined consonants to
increase the frequency of them at the start/end of syllables.</p>
<p>For example, in the <codeclass="docutils literal notranslate"><spanclass="pre">example_style</span></code> above, we have a <codeclass="docutils literal notranslate"><spanclass="pre">start</span></code> of m, and <codeclass="docutils literal notranslate"><spanclass="pre">end</span></code> of x and n.
Taken with the rest of the consonants/vowels, this means you can have the syllables of <codeclass="docutils literal notranslate"><spanclass="pre">mez</span></code>
but not <codeclass="docutils literal notranslate"><spanclass="pre">zem</span></code>, and you can have <codeclass="docutils literal notranslate"><spanclass="pre">phex</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">phen</span></code> but not <codeclass="docutils literal notranslate"><spanclass="pre">xeph</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">neph</span></code>.</p>
<p>They can be left out of custom rulesets entirely.</p>
</section>
<sectionid="vowels">
<h4>vowels<aclass="headerlink"href="#vowels"title="Permalink to this headline">¶</a></h4>
<p>Vowels is a simple list of vowel phonemes - exactly like consonants, but instead used for the
vowel selection. Single-or multi-character strings are equally fine. It uses the same naive weighting system
as consonants - you can increase the frequency of any given vowel by putting it into the list multiple times.</p>
</section>
<sectionid="length">
<h4>length<aclass="headerlink"href="#length"title="Permalink to this headline">¶</a></h4>
<p>A tuple with the minimum and maximum number of syllables a name can have.</p>
<p>When setting this, keep in mind how long your syllables can get! 4 syllables might
two-letter phonemes, you can get up to eight characters per syllable.</p>
<hrclass="docutils"/>
<p><small>This document page is generated from <codeclass="docutils literal notranslate"><spanclass="pre">evennia/contrib/utils/name_generator/README.md</span></code>. Changes to this
file will be overwritten, so edit that file rather than this one.</small></p>
