The escalator Reference Manual

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

The escalator Reference Manual

This is the escalator Reference Manual, version 0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 04:30:26 2022 GMT+0.

Table of Contents


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))

Systems

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

Entities

(make-entity prototype components &rest initargs)

System Loop

(system-loop)

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.


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

2.1 escalator

An experimental object system for high-performance games.

Author

Elliott Slaughter <elliottslaughter@gmail.com>

License

MIT

Version

0.0

Dependency

iterate (system).

Source

escalator.asd.

Child Component

src (module).


3 Modules

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


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

3.1 escalator/src

Source

escalator.asd.

Parent Component

escalator (system).

Child Components

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   [Contents][Index]

4.1.1 escalator/escalator.asd

Source

escalator.asd.

Parent Component

escalator (system).

ASDF Systems

escalator.

Packages

escalator-asd.


4.1.2 escalator/src/package.lisp

Source

escalator.asd.

Parent Component

src (module).

Packages

escalator.


4.1.3 escalator/src/entity.lisp

Dependency

package.lisp (file).

Source

escalator.asd.

Parent Component

src (module).

Public Interface
Internals

5 Packages

Packages are listed by definition order.


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

5.1 escalator-asd

Source

escalator.asd.

Use List
  • asdf/interface.
  • common-lisp.

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

5.2 escalator

Source

package.lisp.

Nickname

escl

Use List
  • common-lisp.
  • iterate.
Public Interface
Internals

6 Definitions

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


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

6.1 Public Interface


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.

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.

Macro: system-loop ()
Package

escalator.

Source

entity.lisp.


Previous: , Up: Public Interface   [Contents][Index]

6.1.2 Ordinary functions

Function: entity-component (entity component)

Returns the component instance for entity or nil.

Package

escalator.

Source

entity.lisp.

Function: (setf entity-component) (entity component)
Package

escalator.

Source

entity.lisp.

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.


6.2 Internals


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

6.2.1 Special variables

Special Variable: *component-data*
Package

escalator.

Source

entity.lisp.

Special Variable: *component-meta*
Package

escalator.

Source

entity.lisp.

Special Variable: *system-code*
Package

escalator.

Source

entity.lisp.


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

6.2.2 Ordinary functions

Function: component-data (component)
Package

escalator.

Source

entity.lisp.

Function: (setf component-data) (component)
Package

escalator.

Source

entity.lisp.

Function: component-meta (component)
Package

escalator.

Source

entity.lisp.

Function: (setf component-meta) (component)
Package

escalator.

Source

entity.lisp.

Function: contains-circularity-p (graph)
Package

escalator.

Source

entity.lisp.

Function: dependency-index (component dependency)
Package

escalator.

Source

entity.lisp.

Function: field-index (component field)
Package

escalator.

Source

entity.lisp.

Function: next-uuid ()
Package

escalator.

Source

entity.lisp.

Function: print-table (table)
Package

escalator.

Source

entity.lisp.

Function: system-code (component)
Package

escalator.

Source

entity.lisp.

Function: (setf system-code) (component)
Package

escalator.

Source

entity.lisp.

Function: total-order (graph)
Package

escalator.

Source

entity.lisp.


Appendix A Indexes


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

A.1 Concepts


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

A.2 Functions

Jump to:   (  
C   D   E   F   M   N   P   S   T  
Index Entry  Section

(
(setf component-data): Private ordinary functions
(setf component-meta): Private ordinary functions
(setf entity-component): Public ordinary functions
(setf system-code): Private ordinary functions

C
component-data: Private ordinary functions
component-meta: Private ordinary functions
contains-circularity-p: Private ordinary functions

D
defcomponent: Public macros
defsystem: Public macros
dependency-index: Private ordinary functions

E
entity-component: Public ordinary functions

F
field-index: Private ordinary functions
Function, (setf component-data): Private ordinary functions
Function, (setf component-meta): Private ordinary functions
Function, (setf entity-component): Public ordinary functions
Function, (setf system-code): Private ordinary functions
Function, component-data: Private ordinary functions
Function, component-meta: Private ordinary functions
Function, contains-circularity-p: Private ordinary functions
Function, dependency-index: Private ordinary functions
Function, entity-component: Public ordinary functions
Function, field-index: Private ordinary functions
Function, make-entity: Public ordinary functions
Function, next-uuid: Private ordinary functions
Function, print-table: Private ordinary functions
Function, system-code: Private ordinary functions
Function, total-order: Private ordinary functions

M
Macro, defcomponent: Public macros
Macro, defsystem: Public macros
Macro, system-loop: Public macros
make-entity: Public ordinary functions

N
next-uuid: Private ordinary functions

P
print-table: Private ordinary functions

S
system-code: Private ordinary functions
system-loop: Public macros

T
total-order: Private ordinary functions

Jump to:   (  
C   D   E   F   M   N   P   S   T