The escalator Reference Manual

Table of Contents

The escalator Reference Manual

This is the escalator Reference Manual, version 0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 11:01:17 2020 GMT+0.

1 Introduction

Escalator

Escalator, aka Entity System for Common Lisp (ESCL), is an experimental object system intended to make it easy to develop high-performance games. ESCL was inspired by this blog post, which outlines the purpose and structure of entity systems and suggests implementations for C++ and SQL. ESCL attempts provide an idiomatic implementation of entity systems for Common Lisp as a high-performance alternative to CLOS.

ESCL is still very experimental, and is not ready for production use. I have not spent much time optimizing it, although it is my hope that it will eventually perform much better than CLOS. My initial micro-benchmarks indicate that ESCL may be up to 50% faster than CLOS for certain kinds of operations. (Note that micro-benchmarks in general are problematic, and mine specifically are probably not very representative, so please take these numbers with a grain of salt.)

Obtaining

For the moment, ESCL isn't stable enough for official releases, so please clone the repository (see above) or download a tarball of master to get the source code. ESCL currently depends on iterate, so be sure to install that too.

Usage

In ESCL, entity systems are made of three types of constructs: components, systems, and entities. While there are some parallels between these constructs and those provided by CLOS and traditional object systems, the differences are fundamental enough that it might help to avoid thinking about entity systems in the context of existing object systems.

Components

(defcomponent component-name (&rest dependencies)
  (&rest fields))

• component-name is a symbol which specifies the name of the component.
• dependencies is a list of names of components upon which this component depends (see discussion below).
• fields is a list of symbols which specify fields in this component. Fields should not be defined multiple times in different components: ESCL does not combine fields the way CLOS automatically combines slots. For each field, defcomponent automatically defines accessor macros under the same names which can be used to access the fields.
• Returns nil. Macro has compile-time side effects.

Systems

(defsystem component-name (entity-var component-var &rest dependency-vars)
  &body body)

• component-name is a symbol which specifies the component for which this system is being defined.
• entity-var will be bound to each entity which has the component named component-name.
• component-var will be bound to the component data for each entity. The macros defined for the fields above can be used on this variable to access the individual fields for this entity.
• dependency-vars will be bound to the dependencies for each entity. If a dependency is only a computation dependency and not a data dependency, that variable can be made nil.
• body is a block of code which will be executed for each entity in the system. (See discussion on the system loop below.)
• Returns nil. Macro has compile-time side effects.

Entities

(make-entity prototype components &rest initargs)

• prototype is used as the initial basis for this entity. Each component associated with prototype is copied into the new entity before adding new components in components. Use nil to specify no prototype.
• components is a list of new components to add to this entity.
• initargs is a plist of values used to initialize fields, similar to the CLOS initargs parameter to make-instance. Each field is automatically defined to have a keyword initarg by the same name.
• Returns the uuid of entity defined. Data for each component is kept in a global table which is not accessible to the user outside the system loop.

System Loop

(system-loop)

• Returns nil. Macro inserts the combined code for add systems which have been defined. The order which systems execute is determined by constructing a total ordering of the components based on their dependencies. (Dependencies execute before systems that depend on them.) Each system iterates over all entities which have the associated component. This is macro is intended to be used in constructing the main loop of the application.

Example

(defcomponent point ()
  (x y z))

(defcomponent velocity (point)
  (vx vy vz))

(defsystem point (entity point)
  (format t "entity ~a at position (~a, ~a, ~a)~%" entity (x point) (y point) (z point)))

(defsystem velocity (entity velocity point)
  (incf (x point) (vx velocity))
  (incf (y point) (vy velocity))
  (incf (z point) (vz velocity)))

(make-entity nil '(point) :x 1 :y 2 :z 3)
(make-entity nil '(point velocity) :x 4 :y 5 :z 6 :vx -1 :vy -2 :vz -3)

(loop repeat 10 do (system-loop))

Output:

entity 1 at position (1, 2, 3)
entity 2 at position (4, 5, 6)
entity 1 at position (1, 2, 3)
entity 2 at position (3, 3, 3)
entity 1 at position (1, 2, 3)
entity 2 at position (2, 1, 0)
entity 1 at position (1, 2, 3)
entity 2 at position (1, -1, -3)
entity 1 at position (1, 2, 3)
entity 2 at position (0, -3, -6)
entity 1 at position (1, 2, 3)
entity 2 at position (-1, -5, -9)
entity 1 at position (1, 2, 3)
entity 2 at position (-2, -7, -12)
entity 1 at position (1, 2, 3)
entity 2 at position (-3, -9, -15)
entity 1 at position (1, 2, 3)
entity 2 at position (-4, -11, -18)
entity 1 at position (1, 2, 3)
entity 2 at position (-5, -13, -21)

2 Systems

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

2.1 escalator

Author

Elliott Slaughter <elliottslaughter@gmail.com>

License

MIT

Description

An experimental object system for high-performance games.

Version

0.0

Dependency

iterate

Source

escalator.asd (file)

Component

src (module)

3 Modules

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

3.1 escalator/src

Parent

escalator (system)

Location

src/

Components

• package.lisp (file)
• entity.lisp (file)

4 Files

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

4.1 Lisp

4.1.1 escalator.asd

Location

escalator.asd

Systems

escalator (system)

Packages

escalator-asd

4.1.2 escalator/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

escalator

4.1.3 escalator/src/entity.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/entity.lisp

Exported Definitions

• defcomponent (macro)
• defsystem (macro)
• entity-component (function)
• (setf entity-component) (function)
• make-entity (function)
• system-loop (macro)

Internal Definitions

• *component-data* (special variable)
• *component-meta* (special variable)
• *system-code* (special variable)
• component-data (function)
• (setf component-data) (function)
• component-meta (function)
• (setf component-meta) (function)
• contains-circularity-p (function)
• dependency-index (function)
• field-index (function)
• next-uuid (function)
• print-table (function)
• system-code (function)
• (setf system-code) (function)
• total-order (function)

5 Packages

Packages are listed by definition order.

5.1 escalator-asd

Source

escalator.asd

Use List

• asdf/interface
• common-lisp

5.2 escalator

Source

package.lisp (file)

Nickname

escl

Use List

• iterate
• common-lisp

Exported Definitions

• defcomponent (macro)
• defsystem (macro)
• entity-component (function)
• (setf entity-component) (function)
• make-entity (function)
• system-loop (macro)

Internal Definitions

• *component-data* (special variable)
• *component-meta* (special variable)
• *system-code* (special variable)
• component-data (function)
• (setf component-data) (function)
• component-meta (function)
• (setf component-meta) (function)
• contains-circularity-p (function)
• dependency-index (function)
• field-index (function)
• next-uuid (function)
• print-table (function)
• system-code (function)
• (setf system-code) (function)
• total-order (function)

6 Definitions

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

6.1 Exported definitions

6.1.1 Macros

Macro: defcomponent NAME (&rest DEPENDENCIES) (&rest FIELDS)

Defines a new component with the given dependencies and fields.

Internal:
* Error if name isn’t a non-nil symbol.
* Error if dependencies contains a non-symbol or nil.
* Error if fields contains a non-symbol or nil.
* Error if dependency doesn’t exist.
* Error if dependencies include self.
* Error if dependencies cause cycle in component precendence list. * Warn on redefinition of component.
* Warn if field hides a previously defined field for any component. * Adds component entry to *component-meta*
(name -> deps * fields * initargs * size).
* Defines macros for each field accessor.
* Initializes global hash-table for component in *component-data*.

Package

escalator

Source

entity.lisp (file)

Macro: defsystem NAME (ENTITY COMPONENT &rest DEPENDENCIES) &body BODY

Defines a system for the given component.

Internal:
* Error if name, entity, and component aren’t non-nil symbols. * Error if dependencies aren’t symbols (nil allowed).
* Error if name doesn’t refer to a defined component.
* Error if number of dependencies doesn’t match component. * Warns on redefinition of system.
* Stores code to operate on component data.

Package

escalator

Source

entity.lisp (file)

Macro: system-loop ()

Package

escalator

Source

entity.lisp (file)

6.1.2 Functions

Function: entity-component ENTITY COMPONENT

Returns the component instance for entity or nil.

Package

escalator

Source

entity.lisp (file)

Writer

(setf entity-component) (function)

Function: (setf entity-component) VALUE ENTITY COMPONENT

Package

escalator

Source

entity.lisp (file)

Reader

entity-component (function)

Function: make-entity PROTOTYPE COMPONENTS &rest INITARGS

Instantiates an entity from the given prototype (shallow copy) and additionally associated with the specified components.

Internal:
* Error if any component doesn’t exist.
* Enforce uniqueness of components by pushing into a new list. * Shallow copy prototype components.
* Instantiate new components (overwrite if they already exist). * Copy references to dependencies (error if it doesn’t exist).

Package

escalator

Source

entity.lisp (file)

6.2 Internal definitions

6.2.1 Special variables

Special Variable: *component-data*

Package

escalator

Source

entity.lisp (file)

Special Variable: *component-meta*

Package

escalator

Source

entity.lisp (file)

Special Variable: *system-code*

Package

escalator

Source

entity.lisp (file)

6.2.2 Functions

Function: component-data COMPONENT

Function: (setf component-data) VALUE COMPONENT

Package

escalator

Source

entity.lisp (file)

Function: component-meta COMPONENT

Function: (setf component-meta) VALUE COMPONENT

Package

escalator

Source

entity.lisp (file)

Function: contains-circularity-p GRAPH

Package

escalator

Source

entity.lisp (file)

Function: dependency-index COMPONENT DEPENDENCY

Package

escalator

Source

entity.lisp (file)

Function: field-index COMPONENT FIELD

Package

escalator

Source

entity.lisp (file)

Function: next-uuid ()

Package

escalator

Source

entity.lisp (file)

Function: print-table TABLE

Package

escalator

Source

entity.lisp (file)

Function: system-code COMPONENT

Function: (setf system-code) VALUE COMPONENT

Package

escalator

Source

entity.lisp (file)

Function: total-order GRAPH

Package

escalator

Source

entity.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types