The escalator Reference Manual

Table of Contents

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

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.


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

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)

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


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

3 Modules

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


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

3.1 escalator/src

Parent

escalator (system)

Location

src/

Components

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 escalator.asd

Location

escalator.asd

Systems

escalator (system)

Packages

escalator-asd


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

4.1.2 escalator/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

escalator


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

4.1.3 escalator/src/entity.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/entity.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 escalator-asd

Source

escalator.asd

Use List

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

5.2 escalator

Source

package.lisp (file)

Nickname

escl

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


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

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)


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

6.2 Internal definitions


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

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)


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

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)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   E   F   L   M  
Index Entry  Section

E
escalator.asd: The escalator․asd file
escalator/src: The escalator/src module
escalator/src/entity.lisp: The escalator/src/entity․lisp file
escalator/src/package.lisp: The escalator/src/package․lisp file

F
File, Lisp, escalator.asd: The escalator․asd file
File, Lisp, escalator/src/entity.lisp: The escalator/src/entity․lisp file
File, Lisp, escalator/src/package.lisp: The escalator/src/package․lisp file

L
Lisp File, escalator.asd: The escalator․asd file
Lisp File, escalator/src/entity.lisp: The escalator/src/entity․lisp file
Lisp File, escalator/src/package.lisp: The escalator/src/package․lisp file

M
Module, escalator/src: The escalator/src module

Jump to:   E   F   L   M  

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): Internal functions
(setf component-meta): Internal functions
(setf entity-component): Exported functions
(setf system-code): Internal functions

C
component-data: Internal functions
component-meta: Internal functions
contains-circularity-p: Internal functions

D
defcomponent: Exported macros
defsystem: Exported macros
dependency-index: Internal functions

E
entity-component: Exported functions

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

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

N
next-uuid: Internal functions

P
print-table: Internal functions

S
system-code: Internal functions
system-loop: Exported macros

T
total-order: Internal functions

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

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

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*component-data*: Internal special variables
*component-meta*: Internal special variables
*system-code*: Internal special variables

S
Special Variable, *component-data*: Internal special variables
Special Variable, *component-meta*: Internal special variables
Special Variable, *system-code*: Internal special variables

Jump to:   *  
S  

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

A.4 Data types

Jump to:   E   P   S  
Index Entry  Section

E
escalator: The escalator system
escalator: The escalator package
escalator-asd: The escalator-asd package

P
Package, escalator: The escalator package
Package, escalator-asd: The escalator-asd package

S
System, escalator: The escalator system

Jump to:   E   P   S