The cl-fast-ecs Reference Manual

This is the cl-fast-ecs Reference Manual, version 0.2.2, generated automatically by Declt version 4.0 beta 2 "William Riker" on Fri Sep 15 03:53:04 2023 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 cl-fast-ecs

Blazingly fast Entity-Component-System microframework.

Author

Andrew Kravchuk <>

Home Page

https://gitlab.com/lockie/cl-fast-ecs

License

MIT

Version

0.2.2

Dependencies
  • alexandria (system).
  • trivial-garbage (system).
Source

cl-fast-ecs.asd.

Child Component

src (module).


3 Modules

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


3.1 cl-fast-ecs/src

Source

cl-fast-ecs.asd.

Parent Component

cl-fast-ecs (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 cl-fast-ecs/cl-fast-ecs.asd

Source

cl-fast-ecs.asd.

Parent Component

cl-fast-ecs (system).

ASDF Systems

cl-fast-ecs.


4.1.2 cl-fast-ecs/src/package.lisp

Source

cl-fast-ecs.asd.

Parent Component

src (module).

Packages

cl-fast-ecs.


4.1.3 cl-fast-ecs/src/components.lisp

Dependency

hooks.lisp (file).

Source

cl-fast-ecs.asd.

Parent Component

src (module).

Public Interface
Internals

4.1.4 cl-fast-ecs/src/entities.lisp

Dependencies
Source

cl-fast-ecs.asd.

Parent Component

src (module).

Public Interface
Internals

4.1.5 cl-fast-ecs/src/hooks.lisp

Source

cl-fast-ecs.asd.

Parent Component

src (module).

Public Interface
Internals

4.1.7 cl-fast-ecs/src/systems.lisp

Dependencies
Source

cl-fast-ecs.asd.

Parent Component

src (module).

Public Interface
Internals

5 Packages

Packages are listed by definition order.


5.1 cl-fast-ecs

**NOTE: this software is of alpha quality, and the API is
subject to change.**

‘cl-fast-ecs‘ is a Common Lisp library providing an
implementation of the Entity-Component-System pattern, primarily focused
on speed and interactive development.

ECS is an architectural data-oriented design pattern that allows for the effective processing of a large number of in-game objects while keeping the code and data separated. This provides flexibility in the way that game objects are built at runtime.

NOTE: to get the maximum performance, but loose the ability to interactively redefine components in the storage, add ‘:ECS-UNSAFE‘ keyword into ‘*FEATURES*‘ before loading the library.

Source

package.lisp.

Nickname

ecs

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 Special variables

Special Variable: *component-defined-hook*

Called when a new component is defined with ‘DEFCOMPONENT‘ macro. Arguments for the call are the index in the component registry and the constructor function for component storage (not to be called directly by user).

See ‘HOOK-UP‘.

Package

cl-fast-ecs.

Source

components.lisp.

Special Variable: *component-redefined-hook*

Called when an existing component is redefined with ‘DEFCOMPONENT‘ macro. Arguments for the call are the index in the component registry and the constructor function for component storage (not to be called directly by user).

See ‘HOOK-UP‘.

Package

cl-fast-ecs.

Source

components.lisp.

Special Variable: *component-storage-grown-hook*

Called after the component storate capacity is increased due to the component being added to the new entity. Arguments for the call are the index in the component registry and the new storage capacity.

Note: this is a good place to call for a full GC cycle to collect old storage arrays.

See ‘HOOK-UP‘.

Package

cl-fast-ecs.

Source

components.lisp.

Special Variable: *entity-storage-grown-hook*

Called after the entity storate capacity is increased due to new entity being added. Argument for the call is the new storage capacity.

Note: this is a good place to call for a full GC cycle to collect old storage arrays.

See ‘HOOK-UP‘.

Package

cl-fast-ecs.

Source

entities.lisp.


6.1.2 Macros

Macro: defcomponent (name &rest slots)

Defines component structure with ‘NAME‘ and ‘SLOTS‘, allowing optional docstring, just like ‘DEFSTRUCT‘. To be called from a top-level. Allows redefinition of component with the same ‘NAME‘ but different set of ‘SLOT‘s; all necessary storage will be properly reallocated.

This macro defines a following set of operations for given ‘NAME‘ *name*:

* an internal structure called ‘name-SOA‘ with its required internal machinery; * a constant ‘+name-COMPONENT-INDEX‘ to access component data within a storage; * a component data accessors ‘name-slotName-AREF‘ and
‘(SETF name-slotName-AREF)‘ for every slot on a component, with *O(1)* complexity (their usage is discouraged though because of poor caching performance, in favour of defining a new system with ‘DEFSYSTEM‘);
* a component constructor aptly named ‘MAKE-name‘, which adds the component being defined to the given ‘ENTITY‘ within given ‘STORAGE‘, with *O(k)* complexity, where *k* is the number of slots on the component;
* specialization of ‘MAKE-COMPONENT‘ generic on a component being defined; * a predicate called ‘HAS-name-P‘ testing whether given ‘ENTITY‘ has the component being defined within given ‘STORAGE‘, with *O(1)* complexity;
* a component destructor called ‘DELETE-name‘, removing the component being defined from the given ‘ENTITY‘ within given ‘STORAGE‘ in *O(k)* complexity, where *k* is the number of slots on the component;
* a convenience macro ‘WITH-name‘ akin to ‘WITH-SLOTS‘;
* some internal helper macros.

Also runs hook ‘*COMPONENT-DEFINED-HOOK*‘ or ‘*COMPONENT-REDEFINED-HOOK*‘ when called, depending on circumstances.

Package

cl-fast-ecs.

Source

components.lisp.

Macro: defsystem (name (&key components-ro components-rw) &body body)

Defines a system with a given ‘NAME‘ and component sets ‘COMPONENTS-RO‘ and ‘COMPONENTS-RW‘ with read-only and read-write access to component slots, respectively. Can be called from a top-level or embedded into other
form. Allows redefinition of system with the same ‘NAME‘ but different ‘BODY‘ or set of components.

Note that requested components should be defined with ‘DEFCOMPONENT‘ before defining the system.

The ‘BODY‘ of forms (with optional docstring) would be run for every entity containing all of the components from the given set, having the following bindings:

* ‘STORAGE‘ — storage being acted upon;
* ‘ENTITY‘ — the entity being processed;
* ‘ComponentName-SlotName‘ for every slot of every component specified.

See also ‘RUN-SYSTEMS‘.

Package

cl-fast-ecs.

Source

systems.lisp.

Macro: hook-up (hook fn)

Hooks up the function ‘FN‘ on the ‘HOOK‘.

Complexity: *O(m)*, where *m* is the number of functions on a given hook.

See also ‘UNHOOK‘.

Package

cl-fast-ecs.

Source

hooks.lisp.

Macro: unhook (hook fn)

Unhooks the function ‘FN‘ from the ‘HOOK‘.

If the function wasn’t registered with ‘HOOK-UP‘ on a given hook, this function has no effect.

Complexity: *O(m)*, where *m* is the number of functions on a given hook.

Package

cl-fast-ecs.

Source

hooks.lisp.


6.1.3 Compiler macros

Compiler Macro: make-object (storage spec)
Package

cl-fast-ecs.

Source

entities.lisp.


6.1.4 Ordinary functions

Function: delete-entity (storage entity)

Delete given ‘ENTITY‘ from given ‘STORAGE‘.

Complexity: *O(m)*, where *m* is the number of defined components.

Package

cl-fast-ecs.

Source

entities.lisp.

Function: entity-valid-p (entity)

Return ‘T‘ if entity is valid.

Complexity: *O(1)*.

Package

cl-fast-ecs.

Source

entities.lisp.

Function: make-entity (storage)

Creates and returns a new componentless entity in given ‘STORAGE‘.

Complexity: amortized *O(1)*.

See also ‘DELETE-ENTITY‘.

Package

cl-fast-ecs.

Source

entities.lisp.

Function: make-object (storage spec)

Creates and returns a new object (that is, an entity with a set of components) in a given ‘STORAGE‘ following specification ‘SPEC‘ structured as follows:

“‘
’((:component-name1 :component-slot1 "value1" :component-slot2 2.0) (:component-name2 :component-slot 42)
;; ...
)
“‘

Complexity: *O(m)*, where *m* is the number of components in the given ‘SPEC‘.

Not recommended for using in a tight loops such as systems, see ‘DEFCOMPONENT‘ documentation for alternatives.

See also ‘MAKE-ENTITY‘, ‘DELETE-ENTITY‘.

Package

cl-fast-ecs.

Source

entities.lisp.

Function: make-storage (&key initial-allocated)

Creates and returns a new storage instance.

Package

cl-fast-ecs.

Source

storage.lisp.

Function: run-systems (storage)

Runs all of the systems registered with ‘DEFSYSTEM‘ with given ‘STORAGE‘.

Package

cl-fast-ecs.

Source

systems.lisp.


6.1.5 Generic functions

Generic Function: make-component (index storage entity &key &allow-other-keys)

Create a component on a given ‘ENTITY‘ in generic fashion.

Not recommended for using in a tight loops such as systems, see ‘DEFCOMPONENT‘ documentation for alternatives.

Package

cl-fast-ecs.

Source

components.lisp.


6.1.6 Types

Type: entity ()

An entity type, basically just a ‘FIXNUM‘.

Package

cl-fast-ecs.

Source

storage.lisp.


6.2 Internals


6.2.1 Special variables

Special Variable: *component-registry*
Package

cl-fast-ecs.

Source

components.lisp.

Special Variable: *component-registry-length*
Package

cl-fast-ecs.

Source

components.lisp.

Special Variable: *initial-dirty-bits*
Package

cl-fast-ecs.

Source

systems.lisp.

Special Variable: *system-registry*
Package

cl-fast-ecs.

Source

systems.lisp.


6.2.2 Macros

Macro: %defsoa (name documentation &rest slots)
Package

cl-fast-ecs.

Source

components.lisp.

Macro: adjust-array* (array size &key element-type initial-element)

Re-creates array with a new size, keeping it simple.

Package

cl-fast-ecs.

Source

hooks.lisp.

Macro: array-pop (array count)
Package

cl-fast-ecs.

Source

entities.lisp.

Macro: array-push-extend (new-element array count type)

Add element to the end of simple array, growing the array as needed. Very much like using the manual fill pointer.

Package

cl-fast-ecs.

Source

entities.lisp.

Macro: defhook (name &key documentation)
Package

cl-fast-ecs.

Source

hooks.lisp.

Macro: maybe-check-entity (storage entity)
Package

cl-fast-ecs.

Source

entities.lisp.


6.2.3 Ordinary functions

Function: %accessor-decls (name index-var-name slot-names slot-types slot-docs)
Package

cl-fast-ecs.

Source

components.lisp.

Function: %make-storage (&key entities-count entities-allocated deleted-entities deleted-entities-count component-storages component-dirty-bits)
Package

cl-fast-ecs.

Source

storage.lisp.

Function: %rebuild-entities-bitmap (storage entities-bitmap component-indices)
Package

cl-fast-ecs.

Source

systems.lisp.

Reader: component-soa-allocated (instance)
Writer: (setf component-soa-allocated) (instance)
Package

cl-fast-ecs.

Source

storage.lisp.

Target Slot

allocated.

Reader: component-soa-exists (instance)
Writer: (setf component-soa-exists) (instance)
Package

cl-fast-ecs.

Source

storage.lisp.

Target Slot

exists.

Reader: component-soa-max-entity (instance)
Writer: (setf component-soa-max-entity) (instance)
Package

cl-fast-ecs.

Source

storage.lisp.

Target Slot

max-entity.

Reader: component-soa-min-entity (instance)
Writer: (setf component-soa-min-entity) (instance)
Package

cl-fast-ecs.

Source

storage.lisp.

Target Slot

min-entity.

Function: copy-storage (instance)
Package

cl-fast-ecs.

Source

storage.lisp.

Function: make-component-soa (&key exists min-entity max-entity allocated)
Package

cl-fast-ecs.

Source

storage.lisp.

Function: new-capacity (current-capacity)
Package

cl-fast-ecs.

Source

entities.lisp.

Function: run-hook (hook &rest args)
Package

cl-fast-ecs.

Source

hooks.lisp.

Reader: storage-component-dirty-bits (instance)
Writer: (setf storage-component-dirty-bits) (instance)
Package

cl-fast-ecs.

Source

storage.lisp.

Target Slot

component-dirty-bits.

Reader: storage-component-storages (instance)
Writer: (setf storage-component-storages) (instance)
Package

cl-fast-ecs.

Source

storage.lisp.

Target Slot

component-storages.

Reader: storage-deleted-entities (instance)
Writer: (setf storage-deleted-entities) (instance)
Package

cl-fast-ecs.

Source

storage.lisp.

Target Slot

deleted-entities.

Reader: storage-deleted-entities-count (instance)
Writer: (setf storage-deleted-entities-count) (instance)
Package

cl-fast-ecs.

Source

storage.lisp.

Target Slot

deleted-entities-count.

Reader: storage-entities-allocated (instance)
Writer: (setf storage-entities-allocated) (instance)
Package

cl-fast-ecs.

Source

storage.lisp.

Target Slot

entities-allocated.

Reader: storage-entities-count (instance)
Writer: (setf storage-entities-count) (instance)
Package

cl-fast-ecs.

Source

storage.lisp.

Target Slot

entities-count.

Function: storage-p (object)
Package

cl-fast-ecs.

Source

storage.lisp.


6.2.4 Structures

Structure: component-soa
Package

cl-fast-ecs.

Source

storage.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: exists
Type

simple-bit-vector

Readers

component-soa-exists.

Writers

(setf component-soa-exists).

Slot: min-entity
Type

cl-fast-ecs:entity

Initform

array-dimension-limit

Readers

component-soa-min-entity.

Writers

(setf component-soa-min-entity).

Slot: max-entity
Type

cl-fast-ecs:entity

Initform

-1

Readers

component-soa-max-entity.

Writers

(setf component-soa-max-entity).

Slot: allocated
Type

alexandria:array-length

Initform

0

Readers

component-soa-allocated.

Writers

(setf component-soa-allocated).

Structure: storage
Package

cl-fast-ecs.

Source

storage.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: entities-count
Type

alexandria:array-length

Initform

0

Readers

storage-entities-count.

Writers

(setf storage-entities-count).

Slot: entities-allocated
Type

alexandria:array-length

Initform

0

Readers

storage-entities-allocated.

Writers

(setf storage-entities-allocated).

Slot: deleted-entities
Type

(simple-array cl-fast-ecs:entity (*))

Readers

storage-deleted-entities.

Writers

(setf storage-deleted-entities).

Slot: deleted-entities-count
Type

alexandria:array-length

Initform

0

Readers

storage-deleted-entities-count.

Writers

(setf storage-deleted-entities-count).

Slot: component-storages
Type

(simple-array cl-fast-ecs::component-soa (*))

Readers

storage-component-storages.

Writers

(setf storage-component-storages).

Slot: component-dirty-bits
Type

simple-bit-vector

Readers

storage-component-dirty-bits.

Writers

(setf storage-component-dirty-bits).


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   %   (  
A   C   D   E   F   G   H   M   N   R   S   U  
Index Entry  Section

%
%accessor-decls: Private ordinary functions
%defsoa: Private macros
%make-storage: Private ordinary functions
%rebuild-entities-bitmap: Private ordinary functions

(
(setf component-soa-allocated): Private ordinary functions
(setf component-soa-exists): Private ordinary functions
(setf component-soa-max-entity): Private ordinary functions
(setf component-soa-min-entity): Private ordinary functions
(setf storage-component-dirty-bits): Private ordinary functions
(setf storage-component-storages): Private ordinary functions
(setf storage-deleted-entities): Private ordinary functions
(setf storage-deleted-entities-count): Private ordinary functions
(setf storage-entities-allocated): Private ordinary functions
(setf storage-entities-count): Private ordinary functions

A
adjust-array*: Private macros
array-pop: Private macros
array-push-extend: Private macros

C
Compiler Macro, make-object: Public compiler macros
component-soa-allocated: Private ordinary functions
component-soa-exists: Private ordinary functions
component-soa-max-entity: Private ordinary functions
component-soa-min-entity: Private ordinary functions
copy-storage: Private ordinary functions

D
defcomponent: Public macros
defhook: Private macros
defsystem: Public macros
delete-entity: Public ordinary functions

E
entity-valid-p: Public ordinary functions

F
Function, %accessor-decls: Private ordinary functions
Function, %make-storage: Private ordinary functions
Function, %rebuild-entities-bitmap: Private ordinary functions
Function, (setf component-soa-allocated): Private ordinary functions
Function, (setf component-soa-exists): Private ordinary functions
Function, (setf component-soa-max-entity): Private ordinary functions
Function, (setf component-soa-min-entity): Private ordinary functions
Function, (setf storage-component-dirty-bits): Private ordinary functions
Function, (setf storage-component-storages): Private ordinary functions
Function, (setf storage-deleted-entities): Private ordinary functions
Function, (setf storage-deleted-entities-count): Private ordinary functions
Function, (setf storage-entities-allocated): Private ordinary functions
Function, (setf storage-entities-count): Private ordinary functions
Function, component-soa-allocated: Private ordinary functions
Function, component-soa-exists: Private ordinary functions
Function, component-soa-max-entity: Private ordinary functions
Function, component-soa-min-entity: Private ordinary functions
Function, copy-storage: Private ordinary functions
Function, delete-entity: Public ordinary functions
Function, entity-valid-p: Public ordinary functions
Function, make-component-soa: Private ordinary functions
Function, make-entity: Public ordinary functions
Function, make-object: Public ordinary functions
Function, make-storage: Public ordinary functions
Function, new-capacity: Private ordinary functions
Function, run-hook: Private ordinary functions
Function, run-systems: Public ordinary functions
Function, storage-component-dirty-bits: Private ordinary functions
Function, storage-component-storages: Private ordinary functions
Function, storage-deleted-entities: Private ordinary functions
Function, storage-deleted-entities-count: Private ordinary functions
Function, storage-entities-allocated: Private ordinary functions
Function, storage-entities-count: Private ordinary functions
Function, storage-p: Private ordinary functions

G
Generic Function, make-component: Public generic functions

H
hook-up: Public macros

M
Macro, %defsoa: Private macros
Macro, adjust-array*: Private macros
Macro, array-pop: Private macros
Macro, array-push-extend: Private macros
Macro, defcomponent: Public macros
Macro, defhook: Private macros
Macro, defsystem: Public macros
Macro, hook-up: Public macros
Macro, maybe-check-entity: Private macros
Macro, unhook: Public macros
make-component: Public generic functions
make-component-soa: Private ordinary functions
make-entity: Public ordinary functions
make-object: Public compiler macros
make-object: Public ordinary functions
make-storage: Public ordinary functions
maybe-check-entity: Private macros

N
new-capacity: Private ordinary functions

R
run-hook: Private ordinary functions
run-systems: Public ordinary functions

S
storage-component-dirty-bits: Private ordinary functions
storage-component-storages: Private ordinary functions
storage-deleted-entities: Private ordinary functions
storage-deleted-entities-count: Private ordinary functions
storage-entities-allocated: Private ordinary functions
storage-entities-count: Private ordinary functions
storage-p: Private ordinary functions

U
unhook: Public macros


A.3 Variables

Jump to:   *  
A   C   D   E   M   S  
Index Entry  Section

*
*component-defined-hook*: Public special variables
*component-redefined-hook*: Public special variables
*component-registry*: Private special variables
*component-registry-length*: Private special variables
*component-storage-grown-hook*: Public special variables
*entity-storage-grown-hook*: Public special variables
*initial-dirty-bits*: Private special variables
*system-registry*: Private special variables

A
allocated: Private structures

C
component-dirty-bits: Private structures
component-storages: Private structures

D
deleted-entities: Private structures
deleted-entities-count: Private structures

E
entities-allocated: Private structures
entities-count: Private structures
exists: Private structures

M
max-entity: Private structures
min-entity: Private structures

S
Slot, allocated: Private structures
Slot, component-dirty-bits: Private structures
Slot, component-storages: Private structures
Slot, deleted-entities: Private structures
Slot, deleted-entities-count: Private structures
Slot, entities-allocated: Private structures
Slot, entities-count: Private structures
Slot, exists: Private structures
Slot, max-entity: Private structures
Slot, min-entity: Private structures
Special Variable, *component-defined-hook*: Public special variables
Special Variable, *component-redefined-hook*: Public special variables
Special Variable, *component-registry*: Private special variables
Special Variable, *component-registry-length*: Private special variables
Special Variable, *component-storage-grown-hook*: Public special variables
Special Variable, *entity-storage-grown-hook*: Public special variables
Special Variable, *initial-dirty-bits*: Private special variables
Special Variable, *system-registry*: Private special variables