The beast Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The beast Reference Manual

This is the beast Reference Manual, version 1.1.0, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 10:47:48 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

@@@@@@@   @@@@@@@@   @@@@@@    @@@@@@   @@@@@@@
@@@@@@@@  @@@@@@@@  @@@@@@@@  @@@@@@@   @@@@@@@
@@!  @@@  @@!       @@!  @@@  !@@         @@!
!@   @!@  !@!       !@!  @!@  !@!         !@!
@!@!@!@   @!!!:!    @!@!@!@!  !!@@!!      @!!
!!!@!!!!  !!!!!:    !!!@!!!!   !!@!!!     !!!
!!:  !!!  !!:       !!:  !!!       !:!    !!:
:!:  !:!  :!:       :!:  !:!      !:!     :!:
 :: ::::   :: ::::  ::   :::  :::: ::      ::
:: : ::   : :: ::    :   : :  :: : :       :

Beast is a Basic Entity/Aspect/System Toolkit for Common Lisp. It's a thin layer of sugar over CLOS that makes it easy to write flexible objects for video games.

Beast can be installed with Quicklisp:

(ql:quickload :beast)

Check out the Overview for a three-minute description of what this is, or the Usage for a full rundown.

The test suite currently passes in SBCL, CCL, ECL, and ABCL on OS X and Debian. Further testing is welcome.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 beast

Author

Steve Losh <steve@stevelosh.com>

Home Page

https://sjl.bitbucket.io/beast/

License

MIT

Description

Basic Entity/Aspect/System Toolkit

Version

1.1.0

Source

beast.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

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


Next: , Previous: , Up: Modules   [Contents][Index]

3.1 beast/vendor

Parent

beast (system)

Location

vendor/

Components

Previous: , Up: Modules   [Contents][Index]

3.2 beast/src

Dependency

package.lisp (file)

Parent

beast (system)

Location

src/

Component

beast.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

4 Files

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


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 beast.asd

Location

beast.asd

Systems

beast (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.2 beast/vendor/quickutils-package.lisp

Parent

vendor (module)

Location

vendor/quickutils-package.lisp

Packages

beast.quickutils

Internal Definitions

*utilities* (special variable)


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.3 beast/vendor/quickutils.lisp

Dependency

quickutils-package.lisp (file)

Parent

vendor (module)

Location

vendor/quickutils.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.4 beast/package.lisp

Dependency

vendor (module)

Parent

beast (system)

Location

package.lisp

Packages

beast


Previous: , Up: Lisp files   [Contents][Index]

4.1.5 beast/src/beast.lisp

Parent

src (module)

Location

src/beast.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

5.1 beast.quickutils

Package that contains Quickutil utility functions.

Source

quickutils-package.lisp (file)

Use List

common-lisp

Used By List

beast

Exported Definitions
Internal Definitions

Previous: , Up: Packages   [Contents][Index]

5.2 beast

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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

beast.lisp (file)

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

beast.lisp (file)

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

beast.lisp (file)

Macro: with-gensyms NAMES &body FORMS

Binds each variable named by a symbol in ‘names‘ to a unique symbol around ‘forms‘. Each of ‘names‘ must either be either a symbol, or of the form:

(symbol string-designator)

Bare symbols appearing in ‘names‘ are equivalent to:

(symbol symbol)

The string-designator is used as the argument to ‘gensym‘ when constructing the unique symbol the named variable will be bound to.

Package

beast.quickutils

Source

quickutils.lisp (file)

Macro: with-unique-names NAMES &body FORMS

Binds each variable named by a symbol in ‘names‘ to a unique symbol around ‘forms‘. Each of ‘names‘ must either be either a symbol, or of the form:

(symbol string-designator)

Bare symbols appearing in ‘names‘ are equivalent to:

(symbol symbol)

The string-designator is used as the argument to ‘gensym‘ when constructing the unique symbol the named variable will be bound to.

Package

beast.quickutils

Source

quickutils.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.2 Functions

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

beast.lisp (file)

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

beast.lisp (file)

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

beast.lisp (file)

Function: ensure-keyword X

Ensure that a keyword is returned for the string designator ‘x‘.

Package

beast.quickutils

Source

quickutils.lisp (file)

Function: ensure-list LIST

If ‘list‘ is a list, it is returned. Otherwise returns the list designated by ‘list‘.

Package

beast.quickutils

Source

quickutils.lisp (file)

Function: hash-table-key-exists-p HASH-TABLE KEY

Does ‘key‘ exist in ‘hash-table‘?

Package

beast.quickutils

Source

quickutils.lisp (file)

Function: hash-table-values TABLE

Returns a list containing the values of hash table ‘table‘.

Package

beast.quickutils

Source

quickutils.lisp (file)

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

beast.lisp (file)

Function: map-product FUNCTION LIST &rest MORE-LISTS

Returns a list containing the results of calling ‘function‘ with one argument from ‘list‘, and one from each of ‘more-lists‘ for each combination of arguments. In other words, returns the product of ‘list‘ and ‘more-lists‘ using ‘function‘.

Example:

(map-product ’list ’(1 2) ’(3 4) ’(5 6))
=> ((1 3 5) (1 3 6) (1 4 5) (1 4 6)
(2 3 5) (2 3 6) (2 4 5) (2 4 6))

Package

beast.quickutils

Source

quickutils.lisp (file)

Function: symb &rest ARGS

Receives any number of objects, concatenates all into one string with ‘#’mkstr‘ and converts them to symbol.

Extracted from _On Lisp_, chapter 4.

See also: ‘symbolicate‘

Package

beast.quickutils

Source

quickutils.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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

beast.lisp (file)

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

beast.lisp (file)

Methods
Method: entity-destroyed (ENTITY entity)
Generic Function: entity-id OBJECT
Package

beast

Methods
Method: entity-id (ENTITY entity)

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

Source

beast.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

6.1.4 Classes

Class: entity ()

A single entity in the game world.

Package

beast

Source

beast.lisp (file)

Direct superclasses

standard-object (class)

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 (generic function)

Slot: %beast/aspects

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

Allocation

:class


Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Special variables

Special Variable: *aspect-index*
Package

beast

Source

beast.lisp (file)

Special Variable: *entity-id-counter*
Package

beast

Source

beast.lisp (file)

Special Variable: *entity-index*
Package

beast

Source

beast.lisp (file)

Special Variable: *system-index*
Package

beast

Source

beast.lisp (file)

Special Variable: *systems*
Package

beast

Source

beast.lisp (file)

Special Variable: *utilities*
Package

beast.quickutils

Source

quickutils-package.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Compiler macros

Compiler Macro: curry FUNCTION &rest ARGUMENTS
Package

beast.quickutils

Source

quickutils.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.3 Functions

Function: all-entities ()

Return a list of all entities.

Package

beast

Source

beast.lisp (file)

Function: build-system-runner NAME ARITY TYPE-SPECIFIERS
Package

beast

Source

beast.lisp (file)

Function: build-system-runner-1 NAME TYPE-SPECIFIERS
Package

beast

Source

beast.lisp (file)

Function: build-system-runner-2 NAME TYPE-SPECIFIERS
Package

beast

Source

beast.lisp (file)

Function: build-system-runner-n NAME
Package

beast

Source

beast.lisp (file)

Function: curry FUNCTION &rest ARGUMENTS

Returns a function that applies ‘arguments‘ and the arguments it is called with to ‘function‘.

Package

beast.quickutils

Source

quickutils.lisp (file)

Function: ensure-function FUNCTION-DESIGNATOR

Returns the function designated by ‘function-designator‘:
if ‘function-designator‘ is a function, it is returned, otherwise it must be a function name and its ‘fdefinition‘ is returned.

Package

beast.quickutils

Source

quickutils.lisp (file)

Function: entity-satisfies-system-type-specifier-p ENTITY SPECIFIER
Package

beast

Source

beast.lisp (file)

Function: get-entity ID

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

Package

beast

Source

beast.lisp (file)

Function: index-entity ENTITY

Insert ‘entity‘ into the entity index.

Package

beast

Source

beast.lisp (file)

Function: index-entity-aspects ENTITY

Insert ‘entity‘ into appropriate aspect indexes.

Package

beast

Source

beast.lisp (file)

Function: index-entity-systems ENTITY

Insert ‘entity‘ into appropriate system indexes.

Package

beast

Source

beast.lisp (file)

Function: initialize-aspect-index NAME
Package

beast

Source

beast.lisp (file)

Function: initialize-system-index NAME FUNCTION ARGLIST
Package

beast

Source

beast.lisp (file)

Function: make-gensym-list LENGTH &optional X

Returns a list of ‘length‘ gensyms, each generated as if with a call to ‘make-gensym‘, using the second (optional, defaulting to ‘"G"‘) argument.

Package

beast.quickutils

Source

quickutils.lisp (file)

Function: maphash-values FUNCTION TABLE

Like ‘maphash‘, but calls ‘function‘ with each value in the hash table ‘table‘.

Package

beast.quickutils

Source

quickutils.lisp (file)

Function: mappend FUNCTION &rest LISTS

Applies ‘function‘ to respective element(s) of each ‘list‘, appending all the all the result list to a single list. ‘function‘ must return a list.

Package

beast.quickutils

Source

quickutils.lisp (file)

Function: mkstr &rest ARGS

Receives any number of objects (string, symbol, keyword, char, number), extracts all printed representations, and concatenates them all into one string.

Extracted from _On Lisp_, chapter 4.

Package

beast.quickutils

Source

quickutils.lisp (file)

Function: rebuild-system-index ARGLIST
Package

beast

Source

beast.lisp (file)

Function: unindex-entity ID

Remove ‘entity‘ from the entity-level index.

Package

beast

Source

beast.lisp (file)

Function: unindex-entity-aspects ID

Remove ‘entity‘ from the aspect indexes.

Package

beast

Source

beast.lisp (file)

Function: unindex-entity-systems ID

Remove ‘entity‘ from the system indexes.

Package

beast

Source

beast.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.4 Types

Type: string-designator ()

A string designator type. A string designator is either a string, a symbol, or a character.

Package

beast.quickutils

Source

quickutils.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   B   F   L   M  
Index Entry  Section

B
beast.asd: The beast<dot>asd file
beast/package.lisp: The beast/package<dot>lisp file
beast/src: The beast/src module
beast/src/beast.lisp: The beast/src/beast<dot>lisp file
beast/vendor: The beast/vendor module
beast/vendor/quickutils-package.lisp: The beast/vendor/quickutils-package<dot>lisp file
beast/vendor/quickutils.lisp: The beast/vendor/quickutils<dot>lisp file

F
File, Lisp, beast.asd: The beast<dot>asd file
File, Lisp, beast/package.lisp: The beast/package<dot>lisp file
File, Lisp, beast/src/beast.lisp: The beast/src/beast<dot>lisp file
File, Lisp, beast/vendor/quickutils-package.lisp: The beast/vendor/quickutils-package<dot>lisp file
File, Lisp, beast/vendor/quickutils.lisp: The beast/vendor/quickutils<dot>lisp file

L
Lisp File, beast.asd: The beast<dot>asd file
Lisp File, beast/package.lisp: The beast/package<dot>lisp file
Lisp File, beast/src/beast.lisp: The beast/src/beast<dot>lisp file
Lisp File, beast/vendor/quickutils-package.lisp: The beast/vendor/quickutils-package<dot>lisp file
Lisp File, beast/vendor/quickutils.lisp: The beast/vendor/quickutils<dot>lisp file

M
Module, beast/src: The beast/src module
Module, beast/vendor: The beast/vendor module

Jump to:   B   F   L   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

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

A
all-entities: Internal functions

B
build-system-runner: Internal functions
build-system-runner-1: Internal functions
build-system-runner-2: Internal functions
build-system-runner-n: Internal functions

C
clear-entities: Exported functions
Compiler Macro, curry: Internal compiler macros
create-entity: Exported functions
curry: Internal compiler macros
curry: Internal functions

D
define-aspect: Exported macros
define-entity: Exported macros
define-system: Exported macros
destroy-entity: Exported functions

E
ensure-function: Internal functions
ensure-keyword: Exported functions
ensure-list: Exported functions
entity-created: Exported generic functions
entity-created: Exported generic functions
entity-destroyed: Exported generic functions
entity-destroyed: Exported generic functions
entity-id: Exported generic functions
entity-id: Exported generic functions
entity-satisfies-system-type-specifier-p: Internal functions

F
Function, all-entities: Internal functions
Function, build-system-runner: Internal functions
Function, build-system-runner-1: Internal functions
Function, build-system-runner-2: Internal functions
Function, build-system-runner-n: Internal functions
Function, clear-entities: Exported functions
Function, create-entity: Exported functions
Function, curry: Internal functions
Function, destroy-entity: Exported functions
Function, ensure-function: Internal functions
Function, ensure-keyword: Exported functions
Function, ensure-list: Exported functions
Function, entity-satisfies-system-type-specifier-p: Internal functions
Function, get-entity: Internal functions
Function, hash-table-key-exists-p: Exported functions
Function, hash-table-values: Exported functions
Function, index-entity: Internal functions
Function, index-entity-aspects: Internal functions
Function, index-entity-systems: Internal functions
Function, initialize-aspect-index: Internal functions
Function, initialize-system-index: Internal functions
Function, make-gensym-list: Internal functions
Function, map-entities: Exported functions
Function, map-product: Exported functions
Function, maphash-values: Internal functions
Function, mappend: Internal functions
Function, mkstr: Internal functions
Function, rebuild-system-index: Internal functions
Function, symb: Exported functions
Function, unindex-entity: Internal functions
Function, unindex-entity-aspects: Internal functions
Function, unindex-entity-systems: Internal functions

G
Generic Function, entity-created: Exported generic functions
Generic Function, entity-destroyed: Exported generic functions
Generic Function, entity-id: Exported generic functions
get-entity: Internal functions

H
hash-table-key-exists-p: Exported functions
hash-table-values: Exported functions

I
index-entity: Internal functions
index-entity-aspects: Internal functions
index-entity-systems: Internal functions
initialize-aspect-index: Internal functions
initialize-system-index: Internal functions

M
Macro, define-aspect: Exported macros
Macro, define-entity: Exported macros
Macro, define-system: Exported macros
Macro, with-gensyms: Exported macros
Macro, with-unique-names: Exported macros
make-gensym-list: Internal functions
map-entities: Exported functions
map-product: Exported functions
maphash-values: Internal functions
mappend: Internal functions
Method, entity-created: Exported generic functions
Method, entity-destroyed: Exported generic functions
Method, entity-id: Exported generic functions
mkstr: Internal functions

R
rebuild-system-index: Internal functions

S
symb: Exported functions

U
unindex-entity: Internal functions
unindex-entity-aspects: Internal functions
unindex-entity-systems: Internal functions

W
with-gensyms: Exported macros
with-unique-names: Exported macros

Jump to:   A   B   C   D   E   F   G   H   I   M   R   S   U   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   %   *  
I   S  
Index Entry  Section

%
%beast/aspects: Exported classes

*
*aspect-index*: Internal special variables
*entity-id-counter*: Internal special variables
*entity-index*: Internal special variables
*system-index*: Internal special variables
*systems*: Internal special variables
*utilities*: Internal special variables

I
id: Exported classes

S
Slot, %beast/aspects: Exported classes
Slot, id: Exported classes
Special Variable, *aspect-index*: Internal special variables
Special Variable, *entity-id-counter*: Internal special variables
Special Variable, *entity-index*: Internal special variables
Special Variable, *system-index*: Internal special variables
Special Variable, *systems*: Internal special variables
Special Variable, *utilities*: Internal special variables

Jump to:   %   *  
I   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   B   C   E   P   S   T  
Index Entry  Section

B
beast: The beast system
beast: The beast package
beast.quickutils: The beast<dot>quickutils package

C
Class, entity: Exported classes

E
entity: Exported classes

P
Package, beast: The beast package
Package, beast.quickutils: The beast<dot>quickutils package

S
string-designator: Internal types
System, beast: The beast system

T
Type, string-designator: Internal types

Jump to:   B   C   E   P   S   T