hg.stevelosh.com > docs.stevelosh.com

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8"/>
        <title> API Reference / beast</title>
        <link rel="stylesheet" href="../_dmedia/tango.css"/>
        <link rel="stylesheet/less" type="text/css" href="../_dmedia/style.less"/>
        <script src="../_dmedia/less.js" type="text/javascript">
        </script>
    </head>
    <body class="content">
        <div class="wrap">
            <header><h1><a href="..">beast</a></h1></header>
                <div class="markdown">
<h1 id="api-reference"><a href="">API Reference</a></h1><p>The following is a list of all user-facing parts of Beast.</p>
<p>If there are backwards-incompatible changes to anything listed here, they will
be noted in the changelog and the author will feel bad.</p>
<p>Anything not listed here is subject to change at any time with no warning, so
don't touch it.</p>
<div class="toc">
<ul>
<li><a href="#package-beast">Package BEAST</a><ul>
<li><a href="#clear-entities-function">CLEAR-ENTITIES (function)</a></li>
<li><a href="#create-entity-function">CREATE-ENTITY (function)</a></li>
<li><a href="#define-aspect-macro">DEFINE-ASPECT (macro)</a></li>
<li><a href="#define-entity-macro">DEFINE-ENTITY (macro)</a></li>
<li><a href="#define-system-macro">DEFINE-SYSTEM (macro)</a></li>
<li><a href="#destroy-entity-function">DESTROY-ENTITY (function)</a></li>
<li><a href="#entity-class">ENTITY (class)</a></li>
<li><a href="#entity-created-generic-function">ENTITY-CREATED (generic function)</a></li>
<li><a href="#entity-destroyed-generic-function">ENTITY-DESTROYED (generic function)</a></li>
<li><a href="#map-entities-function">MAP-ENTITIES (function)</a></li>
</ul>
</li>
</ul></div>
<h2 id="package-beast">Package <code>BEAST</code></h2>
<h3 id="clear-entities-function"><code>CLEAR-ENTITIES</code> (function)</h3>
<div class="codehilite"><pre><span/>(CLEAR-ENTITIES)
</pre></div>


<p>Destroy all entities.</p>
<p><code>destroy-entity</code> will be called for each entity.</p>
<p>Returns a list of all the destroyed entites.</p>
<h3 id="create-entity-function"><code>CREATE-ENTITY</code> (function)</h3>
<div class="codehilite"><pre><span/>(CREATE-ENTITY CLASS &amp;REST INITARGS)
</pre></div>


<p>Create an entity of the given entity class and return it.</p>
<p><code>initargs</code> will be passed along to <code>make-instance</code>.</p>
<p>The <code>entity-created</code> generic function will be called just before returning the
  entity.</p>
<h3 id="define-aspect-macro"><code>DEFINE-ASPECT</code> (macro)</h3>
<div class="codehilite"><pre><span/>(DEFINE-ASPECT NAME &amp;REST FIELDS)
</pre></div>


<p>Define an aspect class.</p>
<p><code>name</code> should be a symbol that will become the name of the class.</p>
<p><code>fields</code> should be zero or more field definitions.  Each field definition can
  be a symbol (the field name), or a list of the field name and extra CLOS slot
  options.</p>
<p>Field names will have the aspect name and a slash prepended to them to create
  the slot names.  <code>:initarg</code> and <code>:accessor</code> slot options will also be
  automatically generated.</p>
<p>Example:</p>
<div class="codehilite"><pre><span/>(define-aspect edible
  energy
  (taste :initform nil))
=&gt;
(defclass edible ()
  ((edible/energy :initarg :edible/energy
                  :accessor edible/energy)
   (edible/taste :initarg :edible/taste
                 :accessor edible/taste
                 :initform nil)))
</pre></div>


<h3 id="define-entity-macro"><code>DEFINE-ENTITY</code> (macro)</h3>
<div class="codehilite"><pre><span/>(DEFINE-ENTITY NAME ASPECTS &amp;REST SLOTS)
</pre></div>


<p>Define an entity class.</p>
<p><code>name</code> should be a symbol that will become the name of the class.</p>
<p><code>aspects</code> should be a list of the aspects this entity should inherit from.</p>
<p><code>slots</code> can be zero or more extra CLOS slot definitions.</p>
<p>Examples:</p>
<div class="codehilite"><pre><span/>(define-entity potion (drinkable))

(define-entity cheese (edible visible)
  (flavor :accessor cheese-flavor :initarg :flavor))
</pre></div>


<h3 id="define-system-macro"><code>DEFINE-SYSTEM</code> (macro)</h3>
<div class="codehilite"><pre><span/>(DEFINE-SYSTEM NAME-AND-OPTIONS
    ARGLIST
  &amp;BODY
  BODY)
</pre></div>


<p>Define a system.</p>
<p><code>name-and-options</code> should be a list of the system name (a symbol) and any
  system options.  A bare symbol can be used if no options are needed.</p>
<p><code>arglist</code> should be a list of system arguments.  Each argument should be
  a list of the argument name and zero or more aspect/entity classes.</p>
<p>Defining a system <code>foo</code> defines two functions:</p>
<ul>
<li><code>foo</code> runs <code>body</code> on a single entity and should only be used for debugging,
    tracing, or disassembling.</li>
<li><code>run-foo</code> should be called to run the system on all applicable entities.</li>
</ul>
<p>Available system options:</p>
<ul>
<li><code>:inline</code>: when true, try to inline the system function into the
    system-running function to avoid the overhead of a function call for every
    entity.  Defaults to <code>nil</code>.</li>
</ul>
<p>Examples:</p>
<div class="codehilite"><pre><span/>(define-system age ((entity lifetime))
  (when (&gt; (incf (lifetime/age entity))
           (lifetime/lifespan entity))
    (destroy-entity entity)))
</pre></div>


<h3 id="destroy-entity-function"><code>DESTROY-ENTITY</code> (function)</h3>
<div class="codehilite"><pre><span/>(DESTROY-ENTITY ENTITY)
</pre></div>


<p>Destroy <code>entity</code> and return it.</p>
<p>The <code>entity-destroyed</code> generic function will be called after the entity has
  been destroyed and unindexed.</p>
<h3 id="entity-class"><code>ENTITY</code> (class)</h3>
<p>A single entity in the game world.</p>
<h3 id="entity-created-generic-function"><code>ENTITY-CREATED</code> (generic function)</h3>
<div class="codehilite"><pre><span/>(ENTITY-CREATED ENTITY)
</pre></div>


<p>Called after an entity has been created and indexed.</p>
<p>The default method does nothing, but users can implement their own auxillary
  methods to run code when entities are created.</p>
<h3 id="entity-destroyed-generic-function"><code>ENTITY-DESTROYED</code> (generic function)</h3>
<div class="codehilite"><pre><span/>(ENTITY-DESTROYED ENTITY)
</pre></div>


<p>Called after an entity has been destroyed and unindexed.</p>
<p>The default method does nothing, but users can implement their own auxillary
  methods to run code when entities are destroyed.</p>
<h3 id="map-entities-function"><code>MAP-ENTITIES</code> (function)</h3>
<div class="codehilite"><pre><span/>(MAP-ENTITIES FUNCTION &amp;OPTIONAL (TYPE 'ENTITY))
</pre></div>


<p>Map <code>function</code> over all entities that are subtypes of <code>type</code>.</p>
<p>Normally you should run code on entities using systems, but this function can
  be handy for debugging purposes.</p>
                </div>
            <footer><p><i>Made with Lisp and love by <a href="http://stevelosh.com/">Steve Losh</a> in Reykjavík, Iceland.</i></p>
<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-15328874-3', 'auto');
  ga('send', 'pageview');

</script></footer>
        </div>
    </body>
</html>
author	Steve Losh <steve@stevelosh.com>
date	Thu, 13 Jun 2024 13:05:28 -0400
parents	4fd427fcd0a2
children	(none)