1ce97acb6755

--- a/beast/reference/index.html	Thu Aug 11 04:57:15 2016 +0000
+++ b/beast/reference/index.html	Fri Aug 12 02:18:53 2016 +0000
@@ -33,7 +33,6 @@
 </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="#get-entity-function">GET-ENTITY (function)</a></li>
 <li><a href="#map-entities-function">MAP-ENTITIES (function)</a></li>
 </ul>
 </li>
@@ -44,21 +43,62 @@
 </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>(CREATE-ENTITY CLASS &amp;REST INITARGS)
+<div class="codehilite"><pre>(CREATE-ENTITY 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>(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>(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>(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>(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>(DEFINE-SYSTEM NAME-AND-OPTIONS
     ARGLIST
@@ -67,41 +107,78 @@
 </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>(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>(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>
 <h4 id="slot-id">Slot <code>ID</code></h4>
 <ul>
 <li>Allocation: <code>:INSTANCE</code></li>
 <li>Initform: <code>(INCF BEAST::*ENTITY-ID-COUNTER*)</code></li>
 <li>Reader: <code>ENTITY-ID</code></li>
 </ul>
+<p>The unique ID of the entity.  This may go away in the future.</p>
 <h4 id="slot-beastaspects">Slot <code>%BEAST/ASPECTS</code></h4>
 <ul>
 <li>Allocation: <code>:CLASS</code></li>
 <li>Initform: <code>NIL</code></li>
 </ul>
+<p>A list of the aspects this entity class inherits.  <strong>Don't touch this.</strong></p>
 <h3 id="entity-created-generic-function"><code>ENTITY-CREATED</code> (generic function)</h3>
 <div class="codehilite"><pre>(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>(ENTITY-DESTROYED ENTITY)
 </pre></div>
 
 
-<h3 id="get-entity-function"><code>GET-ENTITY</code> (function)</h3>
-<div class="codehilite"><pre>(GET-ENTITY ID)
+<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>(MAP-ENTITIES FUNCTION &amp;OPTIONAL (TYPE 'ENTITY))
 </pre></div>
 
 
-<h3 id="map-entities-function"><code>MAP-ENTITIES</code> (function)</h3>
-<div class="codehilite"><pre>(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>