The beast Reference Manual

This is the beast Reference Manual, version 1.2.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed May 15 03:24:15 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 beast

Basic Entity/Aspect/System Toolkit

Author

Steve Losh <>

Home Page

https://docs.stevelosh.com/beast/

License

MIT

Version

1.2.0

Source

beast.asd.

Child Component

src (module).


3 Modules

Modules are listed depth-first from the system components tree.


3.1 beast/src

Source

beast.asd.

Parent Component

beast (system).

Child Components

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


4.1 Lisp


4.1.1 beast/beast.asd

Source

beast.asd.

Parent Component

beast (system).

ASDF Systems

beast.


4.1.2 beast/src/package.lisp

Source

beast.asd.

Parent Component

src (module).

Packages

beast.


4.1.3 beast/src/main.lisp

Dependency

package.lisp (file).

Source

beast.asd.

Parent Component

src (module).

Public Interface
Internals

5 Packages

Packages are listed by definition order.


5.1 beast

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


6.1 Public Interface


6.1.1 Macros

Macro: define-aspect (name &rest fields)

Define an aspect class.

‘name‘ should be a symbol that will become the name of the class.

‘fields‘ 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.

Field names will have the aspect name and a slash prepended to them to create the slot names. ‘:initarg‘ and ‘:accessor‘ slot options will also be automatically generated.

Example:

(define-aspect edible
energy
(taste :initform nil))
=>
(defclass edible ()
((edible/energy :initarg :edible/energy
:accessor edible/energy)
(edible/taste :initarg :edible/taste
:accessor edible/taste
:initform nil)))

Package

beast.

Source

main.lisp.

Macro: define-entity (name aspects &rest slots)

Define an entity class.

‘name‘ should be a symbol that will become the name of the class.

‘aspects‘ should be a list of the aspects this entity should inherit from.

‘slots‘ can be zero or more extra CLOS slot definitions.

Examples:

(define-entity potion (drinkable))

(define-entity cheese (edible visible)
(flavor :accessor cheese-flavor :initarg :flavor))

Package

beast.

Source

main.lisp.

Macro: define-system (name-and-options arglist &body body)

Define a system.

‘name-and-options‘ 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.

‘arglist‘ should be a list of system arguments. Each argument should be a list of the argument name and zero or more aspect/entity classes.

Defining a system ‘foo‘ defines two functions:

* ‘foo‘ runs ‘body‘ on a single entity and should only be used for debugging, tracing, or disassembling.
* ‘run-foo‘ should be called to run the system on all applicable entities.

Available system options:

* ‘:inline‘: 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 ‘nil‘.

Examples:

(define-system age ((entity lifetime))
(when (> (incf (lifetime/age entity))
(lifetime/lifespan entity))
(destroy-entity entity)))

Package

beast.

Source

main.lisp.


6.1.2 Ordinary functions

Function: all-entities ()

Return a list of all entities.

Normally you should run code on entities using systems, but this function can be handy for debugging purposes.

Package

beast.

Source

main.lisp.

Function: clear-entities ()

Destroy all entities.

‘destroy-entity‘ will be called for each entity.

Returns a list of all the destroyed entites.

Package

beast.

Source

main.lisp.

Function: create-entity (class &rest initargs)

Create an entity of the given entity class and return it.

‘initargs‘ will be passed along to ‘make-instance‘.

The ‘entity-created‘ generic function will be called just before returning the entity.

Package

beast.

Source

main.lisp.

Function: destroy-entity (entity)

Destroy ‘entity‘ and return it.

The ‘entity-destroyed‘ generic function will be called after the entity has been destroyed and unindexed.

Package

beast.

Source

main.lisp.

Function: map-entities (function &optional type)

Map ‘function‘ over all entities that are subtypes of ‘type‘.

Normally you should run code on entities using systems, but this function can be handy for debugging purposes.

Package

beast.

Source

main.lisp.


6.1.3 Generic functions

Generic Function: entity-created (entity)

Called after an entity has been created and indexed.

The default method does nothing, but users can implement their own auxillary methods to run code when entities are created.

Package

beast.

Source

main.lisp.

Methods
Method: entity-created ((entity entity))
Generic Function: entity-destroyed (entity)

Called after an entity has been destroyed and unindexed.

The default method does nothing, but users can implement their own auxillary methods to run code when entities are destroyed.

Package

beast.

Source

main.lisp.

Methods
Method: entity-destroyed ((entity entity))
Generic Reader: entity-id (object)
Package

beast.

Methods
Reader Method: entity-id ((entity entity))

The unique ID of the entity. This may go away in the future.

Source

main.lisp.

Target Slot

id.


6.1.4 Standalone methods

Method: print-object ((e entity) stream)
Source

main.lisp.


6.1.5 Classes

Class: entity

A single entity in the game world.

Package

beast.

Source

main.lisp.

Direct methods
Direct slots
Slot: id

The unique ID of the entity. This may go away in the future.

Initform

(incf beast::*entity-id-counter*)

Readers

entity-id.

Writers

This slot is read-only.

Slot: %beast/aspects

A list of the aspects this entity class inherits. **Don’t touch this.**

Allocation

:class


6.2 Internals


6.2.1 Special variables

Special Variable: *aspect-index*
Package

beast.

Source

main.lisp.

Special Variable: *entity-id-counter*
Package

beast.

Source

main.lisp.

Special Variable: *entity-index*
Package

beast.

Source

main.lisp.

Special Variable: *system-index*
Package

beast.

Source

main.lisp.

Special Variable: *systems*
Package

beast.

Source

main.lisp.


6.2.2 Ordinary functions

Function: build-system-runner (name type-specifiers)
Package

beast.

Source

main.lisp.

Function: entity-satisfies-system-type-specifier-p (entity specifier)
Package

beast.

Source

main.lisp.

Function: get-entity (id)

Return the entity with the given ‘id‘, or ‘nil‘ if it is unknown.

Package

beast.

Source

main.lisp.

Function: index-entity (entity)

Insert ‘entity‘ into the entity index.

Package

beast.

Source

main.lisp.

Function: index-entity-aspects (entity)

Insert ‘entity‘ into appropriate aspect indexes.

Package

beast.

Source

main.lisp.

Function: index-entity-systems (entity)

Insert ‘entity‘ into appropriate system indexes.

Package

beast.

Source

main.lisp.

Function: initialize-aspect-index (name)
Package

beast.

Source

main.lisp.

Function: initialize-system-index (name function arglist)
Package

beast.

Source

main.lisp.

Function: rebuild-system-index (arglist)
Package

beast.

Source

main.lisp.

Function: symb (&rest args)
Package

beast.

Source

main.lisp.

Function: unindex-entity (id)

Remove ‘entity‘ from the entity-level index.

Package

beast.

Source

main.lisp.

Function: unindex-entity-aspects (id)

Remove ‘entity‘ from the aspect indexes.

Package

beast.

Source

main.lisp.

Function: unindex-entity-systems (id)

Remove ‘entity‘ from the system indexes.

Package

beast.

Source

main.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   B   C   D   E   F   G   I   M   P   R   S   U  
Index Entry  Section

A
all-entities: Public ordinary functions

B
build-system-runner: Private ordinary functions

C
clear-entities: Public ordinary functions
create-entity: Public ordinary functions

D
define-aspect: Public macros
define-entity: Public macros
define-system: Public macros
destroy-entity: Public ordinary functions

E
entity-created: Public generic functions
entity-created: Public generic functions
entity-destroyed: Public generic functions
entity-destroyed: Public generic functions
entity-id: Public generic functions
entity-id: Public generic functions
entity-satisfies-system-type-specifier-p: Private ordinary functions

F
Function, all-entities: Public ordinary functions
Function, build-system-runner: Private ordinary functions
Function, clear-entities: Public ordinary functions
Function, create-entity: Public ordinary functions
Function, destroy-entity: Public ordinary functions
Function, entity-satisfies-system-type-specifier-p: Private ordinary functions
Function, get-entity: Private ordinary functions
Function, index-entity: Private ordinary functions
Function, index-entity-aspects: Private ordinary functions
Function, index-entity-systems: Private ordinary functions
Function, initialize-aspect-index: Private ordinary functions
Function, initialize-system-index: Private ordinary functions
Function, map-entities: Public ordinary functions
Function, rebuild-system-index: Private ordinary functions
Function, symb: Private ordinary functions
Function, unindex-entity: Private ordinary functions
Function, unindex-entity-aspects: Private ordinary functions
Function, unindex-entity-systems: Private ordinary functions

G
Generic Function, entity-created: Public generic functions
Generic Function, entity-destroyed: Public generic functions
Generic Function, entity-id: Public generic functions
get-entity: Private ordinary functions

I
index-entity: Private ordinary functions
index-entity-aspects: Private ordinary functions
index-entity-systems: Private ordinary functions
initialize-aspect-index: Private ordinary functions
initialize-system-index: Private ordinary functions

M
Macro, define-aspect: Public macros
Macro, define-entity: Public macros
Macro, define-system: Public macros
map-entities: Public ordinary functions
Method, entity-created: Public generic functions
Method, entity-destroyed: Public generic functions
Method, entity-id: Public generic functions
Method, print-object: Public standalone methods

P
print-object: Public standalone methods

R
rebuild-system-index: Private ordinary functions

S
symb: Private ordinary functions

U
unindex-entity: Private ordinary functions
unindex-entity-aspects: Private ordinary functions
unindex-entity-systems: Private ordinary functions