evennia/docs/latest/api/evennia.utils.create.html
Evennia docbuilder action 243d596662 Updated HTML docs.
2025-08-15 18:14:21 +00:00

635 lines
No EOL
45 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>evennia.utils.create &#8212; Evennia latest documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d75fae25" />
<link rel="stylesheet" type="text/css" href="../_static/nature.css?v=279e0f84" />
<link rel="stylesheet" type="text/css" href="../_static/custom.css?v=e4a91a55" />
<script src="../_static/documentation_options.js?v=c6e86fd7"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="evennia.utils.dbserialize" href="evennia.utils.dbserialize.html" />
<link rel="prev" title="evennia.utils.containers" href="evennia.utils.containers.html" />
</head><body>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="evennia.utils.dbserialize.html" title="evennia.utils.dbserialize"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="evennia.utils.containers.html" title="evennia.utils.containers"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="../Evennia-API.html" >API Summary</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="evennia-api.html" >evennia</a> &#187;</li>
<li class="nav-item nav-item-3"><a href="evennia.html" >evennia</a> &#187;</li>
<li class="nav-item nav-item-4"><a href="evennia.utils.html" accesskey="U">evennia.utils</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">evennia.utils.create</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-evennia.utils.create">
<span id="evennia-utils-create"></span><h1>evennia.utils.create<a class="headerlink" href="#module-evennia.utils.create" title="Link to this heading"></a></h1>
<p>This module gathers all the essential database-creation functions for the game
engines various object types.</p>
<p>Only objects created stand-alone are in here. E.g. object Attributes are
always created through their respective objects handlers.</p>
<p>Each <strong>creation_*</strong> function also has an alias named for the entity being created,
such as create_object() and object(). This is for consistency with the
utils.search module and allows you to do the shorter <strong>create.object()</strong>.</p>
<p>The respective object managers hold more methods for manipulating and searching
objects already existing in the database.</p>
<dl class="py function">
<dt class="sig sig-object py" id="evennia.utils.create.create_object">
<span class="sig-prename descclassname"><span class="pre">evennia.utils.create.</span></span><span class="sig-name descname"><span class="pre">create_object</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/create.html#create_object"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.utils.create.create_object" title="Link to this definition"></a></dt>
<dd><p>Create a new in-game object.</p>
<dl class="field-list simple">
<dt class="field-odd">Keyword Arguments<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>typeclass</strong> (<em>class</em><em> or </em><em>str</em>) Class or python path to a typeclass.</p></li>
<li><p><strong>key</strong> (<em>str</em>) Name of the new object. If not set, a name of
<strong>#dbref</strong> will be set.</p></li>
<li><p><strong>location</strong> (<em>Object</em><em> or </em><em>str</em>) Obj or #dbref to use as the location of the new object.</p></li>
<li><p><strong>home</strong> (<em>Object</em><em> or </em><em>str</em>) Obj or #dbref to use as the objects home location.</p></li>
<li><p><strong>permissions</strong> (<em>list</em>) A list of permission strings or tuples (permstring, category).</p></li>
<li><p><strong>locks</strong> (<em>str</em>) one or more lockstrings, separated by semicolons.</p></li>
<li><p><strong>aliases</strong> (<em>list</em>) A list of alternative keys or tuples (aliasstring, category).</p></li>
<li><p><strong>tags</strong> (<em>list</em>) List of tag keys or tuples (tagkey, category) or (tagkey, category, data).</p></li>
<li><p><strong>destination</strong> (<em>Object</em><em> or </em><em>str</em>) Obj or #dbref to use as an Exits target.</p></li>
<li><p><strong>report_to</strong> (<em>Object</em>) The object to return error messages to.</p></li>
<li><p><strong>nohome</strong> (<em>bool</em>) This allows the creation of objects without a
default home location; only used when creating the default
location itself or during unittests.</p></li>
<li><p><strong>attributes</strong> (<em>list</em>) Tuples on the form (key, value) or (key, value, category),
(key, value, lockstring) or (key, value, lockstring, default_access).
to set as Attributes on the new object.</p></li>
<li><p><strong>nattributes</strong> (<em>list</em>) Non-persistent tuples on the form (key, value). Note that
adding this rarely makes sense since this data will not survive a reload.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><em>object (Object)</em> A newly created object of the given typeclass.</p>
</dd>
<dt class="field-odd">Raises<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference internal" href="evennia.accounts.accounts.html#evennia.accounts.accounts.ObjectDB.DoesNotExist" title="evennia.accounts.accounts.ObjectDB.DoesNotExist"><strong>ObjectDB.DoesNotExist</strong></a> If trying to create an Object with
<strong>location</strong> or <strong>home</strong> that cant be found.</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="evennia.utils.create.create_script">
<span class="sig-prename descclassname"><span class="pre">evennia.utils.create.</span></span><span class="sig-name descname"><span class="pre">create_script</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/create.html#create_script"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.utils.create.create_script" title="Link to this definition"></a></dt>
<dd><p>Create a new script. All scripts are a combination of a database
object that communicates with the database, and an typeclass that
decorates the database object into being different types of
scripts. Its behaviour is similar to the game objects except
scripts has a time component and are more limited in scope.</p>
<dl class="field-list simple">
<dt class="field-odd">Keyword Arguments<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>typeclass</strong> (<em>class</em><em> or </em><em>str</em>) Class or python path to a typeclass.</p></li>
<li><p><strong>key</strong> (<em>str</em>) Name of the new object. If not set, a name of
#dbref will be set.</p></li>
<li><p><strong>obj</strong> (<em>Object</em>) The entity on which this Script sits. If this
is <strong>None</strong>, we are creating a “global” script.</p></li>
<li><p><strong>account</strong> (<em>Account</em>) The account on which this Script sits. It is
exclusiv to <strong>obj</strong>.</p></li>
<li><p><strong>locks</strong> (<em>str</em>) one or more lockstrings, separated by semicolons.</p></li>
<li><p><strong>interval</strong> (<em>int</em>) The triggering interval for this Script, in
seconds. If unset, the Script will not have a timing
component.</p></li>
<li><p><strong>start_delay</strong> (<em>bool</em>) If <strong>True</strong>, will wait <strong>interval</strong> seconds
before triggering the first time.</p></li>
<li><p><strong>repeats</strong> (<em>int</em>) The number of times to trigger before stopping.
If unset, will repeat indefinitely.</p></li>
<li><p><strong>persistent</strong> (<em>bool</em>) If this Script survives a server shutdown
or not (all Scripts will survive a reload).</p></li>
<li><p><strong>autostart</strong> (<em>bool</em>) If this Script will start immediately when
created or if the <strong>start</strong> method must be called explicitly.</p></li>
<li><p><strong>report_to</strong> (<em>Object</em>) The object to return error messages to.</p></li>
<li><p><strong>desc</strong> (<em>str</em>) Optional description of script</p></li>
<li><p><strong>tags</strong> (<em>list</em>) List of tags or tuples (tag, category).</p></li>
<li><p><strong>attributes</strong> (<em>list</em>) List if tuples (key, value) or (key, value, category)
(key, value, lockstring) or (key, value, lockstring, default_access).</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><em>script (obj)</em> An instance of the script created</p>
</dd>
</dl>
<p>See evennia.scripts.manager for methods to manipulate existing
scripts in the database.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="evennia.utils.create.create_help_entry">
<span class="sig-prename descclassname"><span class="pre">evennia.utils.create.</span></span><span class="sig-name descname"><span class="pre">create_help_entry</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/create.html#create_help_entry"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.utils.create.create_help_entry" title="Link to this definition"></a></dt>
<dd><p>Create a static help entry in the help database. Note that Command
help entries are dynamic and directly taken from the __doc__
entries of the command. The database-stored help entries are
intended for more general help on the game, more extensive info,
in-game setting information and so on.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>key</strong> (<em>str</em>) The name of the help entry.</p></li>
<li><p><strong>entrytext</strong> (<em>str</em>) The body of te help entry</p></li>
<li><p><strong>category</strong> (<em>str</em><em>, </em><em>optional</em>) The help category of the entry.</p></li>
<li><p><strong>locks</strong> (<em>str</em><em>, </em><em>optional</em>) A lockstring to restrict access.</p></li>
<li><p><strong>aliases</strong> (<em>list</em><em> of </em><em>str</em><em>, </em><em>optional</em>) List of alternative (likely shorter) keynames.</p></li>
<li><p><strong>tags</strong> (<em>lst</em><em>, </em><em>optional</em>) List of tags or tuples <strong>(tag, category)</strong>.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><em>help (HelpEntry)</em> A newly created help entry.</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="evennia.utils.create.create_message">
<span class="sig-prename descclassname"><span class="pre">evennia.utils.create.</span></span><span class="sig-name descname"><span class="pre">create_message</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/create.html#create_message"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.utils.create.create_message" title="Link to this definition"></a></dt>
<dd><p>Create a new communication Msg. Msgs represent a unit of
database-persistent communication between entites.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>senderobj</strong> (<em>Object</em><em>, </em><em>Account</em><em>, </em><em>Script</em><em>, </em><em>str</em><em> or </em><em>list</em>) The entity (or
entities) sending the Msg. If a <strong>str</strong>, this is the id-string
for an external sender type.</p></li>
<li><p><strong>message</strong> (<em>str</em>) Text with the message. Eventual headers, titles
etc should all be included in this text string. Formatting
will be retained.</p></li>
<li><p><strong>receivers</strong> (<em>Object</em><em>, </em><em>Account</em><em>, </em><em>Script</em><em>, </em><em>str</em><em> or </em><em>list</em>) An Account/Object to send
to, or a list of them. If a string, its an identifier for an external
receiver.</p></li>
<li><p><strong>locks</strong> (<em>str</em>) Lock definition string.</p></li>
<li><p><strong>tags</strong> (<em>list</em>) A list of tags or tuples <strong>(tag, category)</strong>.</p></li>
<li><p><strong>header</strong> (<em>str</em>) Mime-type or other optional information for the message</p></li>
</ul>
</dd>
</dl>
<p class="rubric">Notes</p>
<p>The Comm system is created to be very open-ended, so its fully
possible to let a message both go several receivers at the same time,
its up to the command definitions to limit this as desired.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="evennia.utils.create.create_channel">
<span class="sig-prename descclassname"><span class="pre">evennia.utils.create.</span></span><span class="sig-name descname"><span class="pre">create_channel</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/create.html#create_channel"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.utils.create.create_channel" title="Link to this definition"></a></dt>
<dd><p>Create A communication Channel. A Channel serves as a central hub
for distributing Msgs to groups of people without specifying the
receivers explicitly. Instead accounts may connect to the channel
and follow the flow of messages. By default the channel allows
access to all old messages, but this can be turned off with the
keep_log switch.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>key</strong> (<em>str</em>) This must be unique.</p>
</dd>
<dt class="field-even">Keyword Arguments<span class="colon">:</span></dt>
<dd class="field-even"><ul class="simple">
<li><p><strong>aliases</strong> (<em>list</em><em> of </em><em>str</em>) List of alternative (likely shorter) keynames.</p></li>
<li><p><strong>desc</strong> (<em>str</em>) A description of the channel, for use in listings.</p></li>
<li><p><strong>locks</strong> (<em>str</em>) Lockstring.</p></li>
<li><p><strong>keep_log</strong> (<em>bool</em>) Log channel throughput.</p></li>
<li><p><strong>typeclass</strong> (<em>str</em><em> or </em><em>class</em>) The typeclass of the Channel (not
often used).</p></li>
<li><p><strong>tags</strong> (<em>list</em>) A list of tags or tuples <strong>(tag[,category[,data]])</strong>.</p></li>
<li><p><strong>attrs</strong> (<em>list</em>) List of attributes on form <strong>(name, value[,category[,lockstring]])</strong></p></li>
</ul>
</dd>
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p><em>channel (Channel)</em> A newly created channel.</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="evennia.utils.create.create_account">
<span class="sig-prename descclassname"><span class="pre">evennia.utils.create.</span></span><span class="sig-name descname"><span class="pre">create_account</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/utils/create.html#create_account"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.utils.create.create_account" title="Link to this definition"></a></dt>
<dd><p>This creates a new account.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>key</strong> (<em>str</em>) The accounts name. This should be unique.</p></li>
<li><p><strong>email</strong> (<em>str</em><em> or </em><em>None</em>) Email on valid <a class="reference external" href="mailto:addr&#37;&#52;&#48;addr&#46;domain">addr<span>&#64;</span>addr<span>&#46;</span>domain</a> form. If
the empty string, will be set to None.</p></li>
<li><p><strong>password</strong> (<em>str</em>) Password in cleartext.</p></li>
</ul>
</dd>
<dt class="field-even">Keyword Arguments<span class="colon">:</span></dt>
<dd class="field-even"><ul class="simple">
<li><p><strong>typeclass</strong> (<em>str</em>) The typeclass to use for the account.</p></li>
<li><p><strong>is_superuser</strong> (<em>bool</em>) Whether or not this account is to be a superuser</p></li>
<li><p><strong>locks</strong> (<em>str</em>) Lockstring.</p></li>
<li><p><strong>permission</strong> (<em>list</em>) List of permission strings.</p></li>
<li><p><strong>tags</strong> (<em>list</em>) List of Tags on form <strong>(key, category[, data])</strong></p></li>
<li><p><strong>attributes</strong> (<em>list</em>) List of Attributes on form
<strong>(key, value [, category, [,lockstring [, default_pass]]])</strong></p></li>
<li><p><strong>report_to</strong> (<em>Object</em>) An object with a msg() method to report
errors to. If not given, errors will be logged.</p></li>
</ul>
</dd>
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p><em>Account</em> The newly created Account.</p>
</dd>
<dt class="field-even">Raises<span class="colon">:</span></dt>
<dd class="field-even"><p><strong>ValueError</strong> If <strong>key</strong> already exists in database.</p>
</dd>
</dl>
<p class="rubric">Notes</p>
<p>Usually only the server admin should need to be superuser, all
other access levels can be handled with more fine-grained
permissions or groups. A superuser bypasses all lock checking
operations and is thus not suitable for play-testing the game.</p>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="evennia.utils.create.SimpleLazyObject">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">evennia.utils.create.</span></span><span class="sig-name descname"><span class="pre">SimpleLazyObject</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">func</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/django/utils/functional.html#SimpleLazyObject"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.utils.create.SimpleLazyObject" title="Link to this definition"></a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">LazyObject</span></code></p>
<p>A lazy object initialized from any function.</p>
<p>Designed for compound objects of unknown type. For builtins or objects of
known type, use django.utils.functional.lazy.</p>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.utils.create.SimpleLazyObject.__init__">
<span class="sig-name descname"><span class="pre">__init__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">func</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/django/utils/functional.html#SimpleLazyObject.__init__"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.utils.create.SimpleLazyObject.__init__" title="Link to this definition"></a></dt>
<dd><p>Pass in a callable that returns the object to be wrapped.</p>
<p>If copies are made of the resulting SimpleLazyObject, which can happen
in various circumstances within Django, then you must ensure that the
callable can be safely run more than once and will return the same
value.</p>
</dd></dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="evennia.utils.create.account">
<span class="sig-prename descclassname"><span class="pre">evennia.utils.create.</span></span><span class="sig-name descname"><span class="pre">account</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#evennia.utils.create.account" title="Link to this definition"></a></dt>
<dd><p>This creates a new account.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>key</strong> (<em>str</em>) The accounts name. This should be unique.</p></li>
<li><p><strong>email</strong> (<em>str</em><em> or </em><em>None</em>) Email on valid <a class="reference external" href="mailto:addr&#37;&#52;&#48;addr&#46;domain">addr<span>&#64;</span>addr<span>&#46;</span>domain</a> form. If
the empty string, will be set to None.</p></li>
<li><p><strong>password</strong> (<em>str</em>) Password in cleartext.</p></li>
</ul>
</dd>
<dt class="field-even">Keyword Arguments<span class="colon">:</span></dt>
<dd class="field-even"><ul class="simple">
<li><p><strong>typeclass</strong> (<em>str</em>) The typeclass to use for the account.</p></li>
<li><p><strong>is_superuser</strong> (<em>bool</em>) Whether or not this account is to be a superuser</p></li>
<li><p><strong>locks</strong> (<em>str</em>) Lockstring.</p></li>
<li><p><strong>permission</strong> (<em>list</em>) List of permission strings.</p></li>
<li><p><strong>tags</strong> (<em>list</em>) List of Tags on form <strong>(key, category[, data])</strong></p></li>
<li><p><strong>attributes</strong> (<em>list</em>) List of Attributes on form
<strong>(key, value [, category, [,lockstring [, default_pass]]])</strong></p></li>
<li><p><strong>report_to</strong> (<em>Object</em>) An object with a msg() method to report
errors to. If not given, errors will be logged.</p></li>
</ul>
</dd>
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p><em>Account</em> The newly created Account.</p>
</dd>
<dt class="field-even">Raises<span class="colon">:</span></dt>
<dd class="field-even"><p><strong>ValueError</strong> If <strong>key</strong> already exists in database.</p>
</dd>
</dl>
<p class="rubric">Notes</p>
<p>Usually only the server admin should need to be superuser, all
other access levels can be handled with more fine-grained
permissions or groups. A superuser bypasses all lock checking
operations and is thus not suitable for play-testing the game.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="evennia.utils.create.channel">
<span class="sig-prename descclassname"><span class="pre">evennia.utils.create.</span></span><span class="sig-name descname"><span class="pre">channel</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#evennia.utils.create.channel" title="Link to this definition"></a></dt>
<dd><p>Create A communication Channel. A Channel serves as a central hub
for distributing Msgs to groups of people without specifying the
receivers explicitly. Instead accounts may connect to the channel
and follow the flow of messages. By default the channel allows
access to all old messages, but this can be turned off with the
keep_log switch.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>key</strong> (<em>str</em>) This must be unique.</p>
</dd>
<dt class="field-even">Keyword Arguments<span class="colon">:</span></dt>
<dd class="field-even"><ul class="simple">
<li><p><strong>aliases</strong> (<em>list</em><em> of </em><em>str</em>) List of alternative (likely shorter) keynames.</p></li>
<li><p><strong>desc</strong> (<em>str</em>) A description of the channel, for use in listings.</p></li>
<li><p><strong>locks</strong> (<em>str</em>) Lockstring.</p></li>
<li><p><strong>keep_log</strong> (<em>bool</em>) Log channel throughput.</p></li>
<li><p><strong>typeclass</strong> (<em>str</em><em> or </em><em>class</em>) The typeclass of the Channel (not
often used).</p></li>
<li><p><strong>tags</strong> (<em>list</em>) A list of tags or tuples <strong>(tag[,category[,data]])</strong>.</p></li>
<li><p><strong>attrs</strong> (<em>list</em>) List of attributes on form <strong>(name, value[,category[,lockstring]])</strong></p></li>
</ul>
</dd>
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p><em>channel (Channel)</em> A newly created channel.</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="evennia.utils.create.help_entry">
<span class="sig-prename descclassname"><span class="pre">evennia.utils.create.</span></span><span class="sig-name descname"><span class="pre">help_entry</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#evennia.utils.create.help_entry" title="Link to this definition"></a></dt>
<dd><p>Create a static help entry in the help database. Note that Command
help entries are dynamic and directly taken from the __doc__
entries of the command. The database-stored help entries are
intended for more general help on the game, more extensive info,
in-game setting information and so on.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>key</strong> (<em>str</em>) The name of the help entry.</p></li>
<li><p><strong>entrytext</strong> (<em>str</em>) The body of te help entry</p></li>
<li><p><strong>category</strong> (<em>str</em><em>, </em><em>optional</em>) The help category of the entry.</p></li>
<li><p><strong>locks</strong> (<em>str</em><em>, </em><em>optional</em>) A lockstring to restrict access.</p></li>
<li><p><strong>aliases</strong> (<em>list</em><em> of </em><em>str</em><em>, </em><em>optional</em>) List of alternative (likely shorter) keynames.</p></li>
<li><p><strong>tags</strong> (<em>lst</em><em>, </em><em>optional</em>) List of tags or tuples <strong>(tag, category)</strong>.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><em>help (HelpEntry)</em> A newly created help entry.</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="evennia.utils.create.message">
<span class="sig-prename descclassname"><span class="pre">evennia.utils.create.</span></span><span class="sig-name descname"><span class="pre">message</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#evennia.utils.create.message" title="Link to this definition"></a></dt>
<dd><p>Create a new communication Msg. Msgs represent a unit of
database-persistent communication between entites.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>senderobj</strong> (<em>Object</em><em>, </em><em>Account</em><em>, </em><em>Script</em><em>, </em><em>str</em><em> or </em><em>list</em>) The entity (or
entities) sending the Msg. If a <strong>str</strong>, this is the id-string
for an external sender type.</p></li>
<li><p><strong>message</strong> (<em>str</em>) Text with the message. Eventual headers, titles
etc should all be included in this text string. Formatting
will be retained.</p></li>
<li><p><strong>receivers</strong> (<em>Object</em><em>, </em><em>Account</em><em>, </em><em>Script</em><em>, </em><em>str</em><em> or </em><em>list</em>) An Account/Object to send
to, or a list of them. If a string, its an identifier for an external
receiver.</p></li>
<li><p><strong>locks</strong> (<em>str</em>) Lock definition string.</p></li>
<li><p><strong>tags</strong> (<em>list</em>) A list of tags or tuples <strong>(tag, category)</strong>.</p></li>
<li><p><strong>header</strong> (<em>str</em>) Mime-type or other optional information for the message</p></li>
</ul>
</dd>
</dl>
<p class="rubric">Notes</p>
<p>The Comm system is created to be very open-ended, so its fully
possible to let a message both go several receivers at the same time,
its up to the command definitions to limit this as desired.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="evennia.utils.create.object">
<span class="sig-prename descclassname"><span class="pre">evennia.utils.create.</span></span><span class="sig-name descname"><span class="pre">object</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#evennia.utils.create.object" title="Link to this definition"></a></dt>
<dd><p>Create a new in-game object.</p>
<dl class="field-list simple">
<dt class="field-odd">Keyword Arguments<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>typeclass</strong> (<em>class</em><em> or </em><em>str</em>) Class or python path to a typeclass.</p></li>
<li><p><strong>key</strong> (<em>str</em>) Name of the new object. If not set, a name of
<strong>#dbref</strong> will be set.</p></li>
<li><p><strong>location</strong> (<em>Object</em><em> or </em><em>str</em>) Obj or #dbref to use as the location of the new object.</p></li>
<li><p><strong>home</strong> (<em>Object</em><em> or </em><em>str</em>) Obj or #dbref to use as the objects home location.</p></li>
<li><p><strong>permissions</strong> (<em>list</em>) A list of permission strings or tuples (permstring, category).</p></li>
<li><p><strong>locks</strong> (<em>str</em>) one or more lockstrings, separated by semicolons.</p></li>
<li><p><strong>aliases</strong> (<em>list</em>) A list of alternative keys or tuples (aliasstring, category).</p></li>
<li><p><strong>tags</strong> (<em>list</em>) List of tag keys or tuples (tagkey, category) or (tagkey, category, data).</p></li>
<li><p><strong>destination</strong> (<em>Object</em><em> or </em><em>str</em>) Obj or #dbref to use as an Exits target.</p></li>
<li><p><strong>report_to</strong> (<em>Object</em>) The object to return error messages to.</p></li>
<li><p><strong>nohome</strong> (<em>bool</em>) This allows the creation of objects without a
default home location; only used when creating the default
location itself or during unittests.</p></li>
<li><p><strong>attributes</strong> (<em>list</em>) Tuples on the form (key, value) or (key, value, category),
(key, value, lockstring) or (key, value, lockstring, default_access).
to set as Attributes on the new object.</p></li>
<li><p><strong>nattributes</strong> (<em>list</em>) Non-persistent tuples on the form (key, value). Note that
adding this rarely makes sense since this data will not survive a reload.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><em>object (Object)</em> A newly created object of the given typeclass.</p>
</dd>
<dt class="field-odd">Raises<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference internal" href="evennia.accounts.accounts.html#evennia.accounts.accounts.ObjectDB.DoesNotExist" title="evennia.accounts.accounts.ObjectDB.DoesNotExist"><strong>ObjectDB.DoesNotExist</strong></a> If trying to create an Object with
<strong>location</strong> or <strong>home</strong> that cant be found.</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="evennia.utils.create.script">
<span class="sig-prename descclassname"><span class="pre">evennia.utils.create.</span></span><span class="sig-name descname"><span class="pre">script</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#evennia.utils.create.script" title="Link to this definition"></a></dt>
<dd><p>Create a new script. All scripts are a combination of a database
object that communicates with the database, and an typeclass that
decorates the database object into being different types of
scripts. Its behaviour is similar to the game objects except
scripts has a time component and are more limited in scope.</p>
<dl class="field-list simple">
<dt class="field-odd">Keyword Arguments<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>typeclass</strong> (<em>class</em><em> or </em><em>str</em>) Class or python path to a typeclass.</p></li>
<li><p><strong>key</strong> (<em>str</em>) Name of the new object. If not set, a name of
#dbref will be set.</p></li>
<li><p><strong>obj</strong> (<em>Object</em>) The entity on which this Script sits. If this
is <strong>None</strong>, we are creating a “global” script.</p></li>
<li><p><strong>account</strong> (<em>Account</em>) The account on which this Script sits. It is
exclusiv to <strong>obj</strong>.</p></li>
<li><p><strong>locks</strong> (<em>str</em>) one or more lockstrings, separated by semicolons.</p></li>
<li><p><strong>interval</strong> (<em>int</em>) The triggering interval for this Script, in
seconds. If unset, the Script will not have a timing
component.</p></li>
<li><p><strong>start_delay</strong> (<em>bool</em>) If <strong>True</strong>, will wait <strong>interval</strong> seconds
before triggering the first time.</p></li>
<li><p><strong>repeats</strong> (<em>int</em>) The number of times to trigger before stopping.
If unset, will repeat indefinitely.</p></li>
<li><p><strong>persistent</strong> (<em>bool</em>) If this Script survives a server shutdown
or not (all Scripts will survive a reload).</p></li>
<li><p><strong>autostart</strong> (<em>bool</em>) If this Script will start immediately when
created or if the <strong>start</strong> method must be called explicitly.</p></li>
<li><p><strong>report_to</strong> (<em>Object</em>) The object to return error messages to.</p></li>
<li><p><strong>desc</strong> (<em>str</em>) Optional description of script</p></li>
<li><p><strong>tags</strong> (<em>list</em>) List of tags or tuples (tag, category).</p></li>
<li><p><strong>attributes</strong> (<em>list</em>) List if tuples (key, value) or (key, value, category)
(key, value, lockstring) or (key, value, lockstring, default_access).</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><em>script (obj)</em> An instance of the script created</p>
</dd>
</dl>
<p>See evennia.scripts.manager for methods to manipulate existing
scripts in the database.</p>
</dd></dl>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo of Evennia"/>
</a></p>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">evennia.utils.create</a><ul>
<li><a class="reference internal" href="#evennia.utils.create.create_object"><code class="docutils literal notranslate"><span class="pre">create_object()</span></code></a></li>
<li><a class="reference internal" href="#evennia.utils.create.create_script"><code class="docutils literal notranslate"><span class="pre">create_script()</span></code></a></li>
<li><a class="reference internal" href="#evennia.utils.create.create_help_entry"><code class="docutils literal notranslate"><span class="pre">create_help_entry()</span></code></a></li>
<li><a class="reference internal" href="#evennia.utils.create.create_message"><code class="docutils literal notranslate"><span class="pre">create_message()</span></code></a></li>
<li><a class="reference internal" href="#evennia.utils.create.create_channel"><code class="docutils literal notranslate"><span class="pre">create_channel()</span></code></a></li>
<li><a class="reference internal" href="#evennia.utils.create.create_account"><code class="docutils literal notranslate"><span class="pre">create_account()</span></code></a></li>
<li><a class="reference internal" href="#evennia.utils.create.SimpleLazyObject"><code class="docutils literal notranslate"><span class="pre">SimpleLazyObject</span></code></a><ul>
<li><a class="reference internal" href="#evennia.utils.create.SimpleLazyObject.__init__"><code class="docutils literal notranslate"><span class="pre">SimpleLazyObject.__init__()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#evennia.utils.create.account"><code class="docutils literal notranslate"><span class="pre">account()</span></code></a></li>
<li><a class="reference internal" href="#evennia.utils.create.channel"><code class="docutils literal notranslate"><span class="pre">channel()</span></code></a></li>
<li><a class="reference internal" href="#evennia.utils.create.help_entry"><code class="docutils literal notranslate"><span class="pre">help_entry()</span></code></a></li>
<li><a class="reference internal" href="#evennia.utils.create.message"><code class="docutils literal notranslate"><span class="pre">message()</span></code></a></li>
<li><a class="reference internal" href="#evennia.utils.create.object"><code class="docutils literal notranslate"><span class="pre">object()</span></code></a></li>
<li><a class="reference internal" href="#evennia.utils.create.script"><code class="docutils literal notranslate"><span class="pre">script()</span></code></a></li>
</ul>
</li>
</ul>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="evennia.utils.containers.html"
title="previous chapter">evennia.utils.containers</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="evennia.utils.dbserialize.html"
title="next chapter">evennia.utils.dbserialize</a></p>
</div>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/api/evennia.utils.create.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com/docs/latest/index.html">Documentation Top</a> </li>
<li><a href="https://www.evennia.com">Evennia Home</a> </li>
<li><a href="https://github.com/evennia/evennia">Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Doc Versions</h3>
<ul>
<li>
<a href="https://www.evennia.com/docs/latest/index.html">latest (main branch)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/5.x/index.html">v5.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/4.x/index.html">v4.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/3.x/index.html">v3.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/2.x/index.html">v2.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/1.x/index.html">v1.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/0.x/index.html">v0.9.5 branch (outdated)</a>
</li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="evennia.utils.dbserialize.html" title="evennia.utils.dbserialize"
>next</a> |</li>
<li class="right" >
<a href="evennia.utils.containers.html" title="evennia.utils.containers"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="../Evennia-API.html" >API Summary</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="evennia-api.html" >evennia</a> &#187;</li>
<li class="nav-item nav-item-3"><a href="evennia.html" >evennia</a> &#187;</li>
<li class="nav-item nav-item-4"><a href="evennia.utils.html" >evennia.utils</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">evennia.utils.create</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2024, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>