This is the cl-fast-ecs Reference Manual, version 0.9.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Tue Jul 15 03:49:33 2025 GMT+0.
The main system appears first, followed by any subsystem dependency.
cl-fast-ecs
Blazingly fast Entity-Component-System microframework.
Andrew Kravchuk <awkravchuk@gmail.com>
MIT
0.9.0
alexandria
(system).
closer-mop
(system).
global-vars
(system).
trivial-adjust-simple-array
(system).
src
(module).
Modules are listed depth-first from the system components tree.
cl-fast-ecs/src
cl-fast-ecs
(system).
package.lisp
(file).
components.lisp
(file).
entities.lisp
(file).
hooks.lisp
(file).
index.lisp
(file).
storage.lisp
(file).
systems.lisp
(file).
Files are sorted by type and then listed depth-first from the systems components trees.
cl-fast-ecs/cl-fast-ecs.asd
cl-fast-ecs/src/package.lisp
cl-fast-ecs/src/components.lisp
cl-fast-ecs/src/entities.lisp
cl-fast-ecs/src/hooks.lisp
cl-fast-ecs/src/index.lisp
cl-fast-ecs/src/storage.lisp
cl-fast-ecs/src/systems.lisp
cl-fast-ecs/src/components.lisp
hooks.lisp
(file).
index.lisp
(file).
storage.lisp
(file).
src
(module).
assign-component
(generic function).
defcomponent
(macro).
define-component
(macro).
delete-component
(generic function).
make-component
(generic function).
print-component
(generic function).
replace-component
(generic function).
reset-component
(generic function).
%accessor-decls
(function).
%composite-index-accessor-decls
(function).
%ctor-decl
(function).
%dtor-decl
(function).
%index-accessor-decls
(function).
%non-unique-error
(function).
%soa-decl
(function).
%update-composite-index
(function).
%update-generated-slots
(function).
%update-index
(function).
%with-macro-decl
(function).
format-symbol/component
(function).
cl-fast-ecs/src/entities.lisp
components.lisp
(file).
hooks.lisp
(file).
index.lisp
(file).
storage.lisp
(file).
src
(module).
*skip-printing-components*
(special variable).
copy-entity
(function).
defentity
(macro).
define-entity
(macro).
delete-entity
(function).
entity-valid-p
(function).
make-entity
(function).
make-object
(compiler macro).
make-object
(function).
print-entities/picture
(function).
print-entity
(function).
spec-adjoin
(function).
%quasiquotep
(function).
unionf
(macro).
with-checked-entity
(macro).
cl-fast-ecs/src/index.lisp
storage.lisp
(file).
src
(module).
binary-search
(function).
index-bucket
(macro).
index-delete
(macro).
index-enumerate
(macro).
index-insert
(macro).
index-lookup
(macro).
index-lookup-1
(macro).
index-maybe-grow
(macro).
new-capacity
(function).
values-equal
(macro).
cl-fast-ecs/src/storage.lisp
hooks.lisp
(file).
src
(module).
direct-slot-definition-class
(method).
entity
(type).
initialize-instance
(method).
make-storage
(function).
print-object
(method).
shared-initialize
(method).
update-instance-for-redefined-class
(method).
validate-superclass
(method).
%get-storage
(function).
%make-storage
(function).
component-soa
(class).
component-soa-allocated
(reader method).
(setf component-soa-allocated)
(writer method).
component-soa-class
(class).
component-soa-count
(reader method).
(setf component-soa-count)
(writer method).
component-soa-exists
(reader method).
(setf component-soa-exists)
(writer method).
component-soa-max-entity
(reader method).
(setf component-soa-max-entity)
(writer method).
component-soa-min-entity
(reader method).
(setf component-soa-min-entity)
(writer method).
component-soa-slot
(class).
copy-storage
(function).
obsoletep
(reader method).
(setf obsoletep)
(writer method).
slot-composite-index
(reader method).
(setf slot-composite-index)
(writer method).
slot-composite-index-unique
(reader method).
(setf slot-composite-index-unique)
(writer method).
slot-index
(reader method).
(setf slot-index)
(writer method).
slot-index-unique
(reader method).
(setf slot-index-unique)
(writer method).
slot-type
(reader method).
(setf slot-type)
(writer method).
storage
(structure).
storage-component-created-bits
(reader).
(setf storage-component-created-bits)
(writer).
storage-component-removed-bits
(reader).
(setf storage-component-removed-bits)
(writer).
storage-component-storages
(reader).
(setf storage-component-storages)
(writer).
storage-deleted-entities
(reader).
(setf storage-deleted-entities)
(writer).
storage-deleted-entities-count
(reader).
(setf storage-deleted-entities-count)
(writer).
storage-entities-count
(reader).
(setf storage-entities-count)
(writer).
storage-p
(function).
with-storage
(macro).
cl-fast-ecs/src/systems.lisp
entities.lisp
(file).
storage.lisp
(file).
src
(module).
define-system
(macro).
defsystem
(macro).
delete-system
(function).
run-systems
(function).
system-ref
(function).
%append-to-hash-table
(function).
%rebuild-entities-bitmap
(function).
%reorder-systems!
(function).
%unknown-system
(function).
Packages are listed by definition order.
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 boost the performance extra 5-6%, but loose the ability to interactively (re)define components in the storage, add ‘:ECS-RELEASE‘ keyword into ‘*FEATURES*‘ before compiling the library.
ecs
common-lisp
.
trivial-adjust-simple-array
.
*skip-printing-components*
(special variable).
assign-component
(generic function).
copy-entity
(function).
defcomponent
(macro).
defentity
(macro).
define-component
(macro).
define-entity
(macro).
define-system
(macro).
defsystem
(macro).
delete-component
(generic function).
delete-entity
(function).
delete-system
(function).
entity
(type).
entity-valid-p
(function).
hook-up
(macro).
make-component
(generic function).
make-entity
(function).
make-object
(compiler macro).
make-object
(function).
make-storage
(function).
print-component
(generic function).
print-entities/picture
(function).
print-entity
(function).
replace-component
(generic function).
reset-component
(generic function).
run-systems
(function).
spec-adjoin
(function).
system-ref
(function).
unhook
(macro).
%accessor-decls
(function).
%append-to-hash-table
(function).
%composite-index-accessor-decls
(function).
%ctor-decl
(function).
%dtor-decl
(function).
%get-storage
(function).
%index-accessor-decls
(function).
%make-storage
(function).
%non-unique-error
(function).
%quasiquotep
(function).
%rebuild-entities-bitmap
(function).
%reorder-systems!
(function).
%soa-decl
(function).
%unknown-system
(function).
%update-composite-index
(function).
%update-generated-slots
(function).
%update-index
(function).
%with-macro-decl
(function).
binary-search
(function).
component-soa
(class).
component-soa-allocated
(generic reader).
(setf component-soa-allocated)
(generic writer).
component-soa-class
(class).
component-soa-count
(generic reader).
(setf component-soa-count)
(generic writer).
component-soa-exists
(generic reader).
(setf component-soa-exists)
(generic writer).
component-soa-max-entity
(generic reader).
(setf component-soa-max-entity)
(generic writer).
component-soa-min-entity
(generic reader).
(setf component-soa-min-entity)
(generic writer).
component-soa-slot
(class).
copy-storage
(function).
defhook
(macro).
format-symbol/component
(function).
index-bucket
(macro).
index-delete
(macro).
index-enumerate
(macro).
index-insert
(macro).
index-lookup
(macro).
index-lookup-1
(macro).
index-maybe-grow
(macro).
new-capacity
(function).
obsoletep
(generic reader).
(setf obsoletep)
(generic writer).
run-hook
(function).
slot-composite-index
(generic reader).
(setf slot-composite-index)
(generic writer).
slot-composite-index-unique
(generic reader).
(setf slot-composite-index-unique)
(generic writer).
slot-index
(generic reader).
(setf slot-index)
(generic writer).
slot-index-unique
(generic reader).
(setf slot-index-unique)
(generic writer).
slot-type
(generic reader).
(setf slot-type)
(generic writer).
storage
(structure).
storage-component-created-bits
(reader).
(setf storage-component-created-bits)
(writer).
storage-component-removed-bits
(reader).
(setf storage-component-removed-bits)
(writer).
storage-component-storages
(reader).
(setf storage-component-storages)
(writer).
storage-deleted-entities
(reader).
(setf storage-deleted-entities)
(writer).
storage-deleted-entities-count
(reader).
(setf storage-deleted-entities-count)
(writer).
storage-entities-count
(reader).
(setf storage-entities-count)
(writer).
storage-p
(function).
unionf
(macro).
values-equal
(macro).
with-checked-entity
(macro).
with-storage
(macro).
Definitions are sorted by export status, category, package, and then by lexicographic order.
A list of keywords denoting components that should be skipped while printing entities.
Defines component structure with ‘NAME‘ and ‘SLOTS‘, allowing optional
docstring, just like ‘DEFSTRUCT‘.
There’s extra keyword argument ‘:INDEX‘ to the slot definition, which, if set
to symbol, creates a function referencing a hash table-based index for that
slot allowing fast (amort. *O(1)*) lookups in form of "which set of entities
have this exact slot value"; that might come in handy when implementing
parent/child or other entity relationships. The downside of such index is that
component add/delete/update operations take a little bit longer, and addition
can trigger expensive table rehashing.
Additionally, when ‘:UNIQUE‘ is set to ‘T‘, such index ensures that entities
and given slot values map 1 to 1, at least in value’s ‘SXHASH‘ sense. This
might prove valuable when implementing entity names.
The index function always returns entities in strictly ascending order. It also
takes optional keyword arguments ‘START‘ and ‘COUNT‘ allowing to limit the
returned list of entities.
In addition, a ‘WITH-name‘ macro is defined for every index, allowing to
iterate over entities in index without extra consing. Note that deleting
entities from index while iterating with that macro is bad idea as it will lead
to subtle logic errors.
There’s also ‘:GENERATED-FROM‘ argument to the slot definition, which, if set
to the list of slot names, creates a generated slot akin to ‘GENERATED STORED‘
columns found in some relational databases. The value of such slot is
calculated using its default expression, and is automatically recalculated
when any of the slots specified in ‘:GENERATED-FROM‘ list are changed. Setting
its value directly is impossible. A generated column could also be a part of
an index.
The ‘NAME‘ argument could also be a lambda list of form
‘(NAME &KEY FINALIZE COMPOSITE-INDEX)‘. ‘FINALIZE‘ is a designator of function
that’d be called when the entity with the component is deleted. It should take
entity as the first argument and component slot values as keyword arguments
with corresponding names. ‘COMPOSITE-INDEX‘ is lambda list of form
‘(NAME SLOTS &KEY UNIQUE)‘, which defines a composite index, i.e. index
similar to single-slot index described above, but spawning several slots at
once, supplied as ‘SLOTS‘ list. Composite index name cannot be the same as any
slot name.
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‘:
* an internal structure called ‘name-SOA‘ with its required internal machinery;
* a constant ‘+name-COMPONENT-INDEX+‘ to reference component data within a
storage;
* a component data accessors ‘name-slotName‘ and
‘(SETF name-slotName)‘ 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‘, with *O(k)* complexity, where *k* is the
number of slots on the component. Note that trying to construct the component
on an entity which already has that component is not an error, but produces
warning when not in release mode;
* 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, with *O(1)* complexity;
* a component destructor called ‘DELETE-name‘, removing the component being
defined from the given ‘ENTITY‘ in *O(k)* complexity,where *k* is the number
of slots on the component;
* specialization of ‘DELETE-COMPONENT‘ generic on a component being defined;
* a convenience macro ‘WITH-name‘ akin to ‘WITH-SLOTS‘;
* an upsert operator ‘ASSIGN-name‘ which first ensures the component exists
on given entity and then sets its values according to given keyword arguments,
but keeps slots that weren’t specified to their previous values;
* specialization of ‘ASSIGN-COMPONENT‘ generic on a component being defined;
* a ‘REPLACE-name‘ function which copies the component slot values from one
given entity to another;
* a ‘RESET-name‘ function which sets component slot values to their default
values for given entity;
* specialization of ‘RESET-COMPONENT‘ generic on a component being defined;
* a ‘name-COUNT‘ helper function with no arguments which returns the current
count of entities having this component;
* some internal helper macros;
* if ‘:INDEX‘ if set to a symbol for any slot, the function with the name
denoted by that symbol is defined, taking slot value as an argument and
returning the list of entities having such slot value;
* if ‘:UNIQUE‘ is specified and set to ‘T‘ in addition to ‘:INDEX‘, the index
function returns a single entity having given slot value, or raises a condition
if there’s no such entity. If the ‘:MISSING-ERROR-P‘ keyword argument to that
function is ‘NIL‘, no condition is raised, but negative entity is returned
instead.
Also runs hook ‘*COMPONENT-DEFINED-HOOK*‘ or ‘*COMPONENT-REDEFINED-HOOK*‘ when called, depending on circumstances.
Defines a global variable named ‘NAME‘ holding an entity that is initialized
automatically along with the data storage according to specification ‘SPEC‘
structured the same way as for ‘MAKE-OBJECT‘. Supports optional docstring via
‘DOCUMENTATION‘ argument.
NOTE: the variable is created by means of
[global-vars](https://github.com/lmj/global-vars) library and hence cannot be
dynamically bound.
See also: ‘MAKE-STORAGE‘.
An alias for ‘DEFCOMPONENT‘.
An alias for ‘DEFENTITY‘.
An alias for ‘DEFSYSTEM‘.
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. ‘COMPONENTS-NO‘ defines a list of components that should not
appear on entities processed by the system. ‘ARGUMENTS‘ is a two-list of the
keyword arguments the system expects to be passed via ‘RUN-SYSTEMS‘, just like
in ‘FTYPE‘ declaration.
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:
* ‘ENTITY‘ — the entity being processed;
* ‘ComponentName-SlotName‘ for every slot of every component specified.
The forms in ‘BODY‘ are enclosed in block named ‘CURRENT-ENTITY‘, so the
processing could be skipped to the next entity by calling
‘(RETURN-FROM CURRENT-ENTITY)‘.
The ‘INITIALLY‘ form would be evaluated before the entities loop, and the
‘FINALLY‘ form would be evaluated after the loop and its value would be
returned from the system.
The ‘WHEN‘ form is evaluated every entity loop iteration to check if that
entity should be processed or not.
The ‘ENABLE‘ form is evaluated before the entity loop to check if the entire
loop needs to run or not.
The ‘WITH‘ form, having lambda list ‘(VARS &KEY OF-TYPE =)‘, allows to
initialize the local variables once before the loop starts. The ‘VARS‘ and
‘OF-TYPE‘ could be the single symbol or the list, and in latter case the
required ‘=‘ argument should be mutliple values.
‘BEFORE‘ and ‘AFTER‘ lists denote names of systems that need to be run before
and after the system being defined, respectively. If there are cycles in order
graph defined by those arguments, a corresponding error is thrown. When both
‘BEFORE‘ and ‘AFTER‘ are ‘NIL‘, the last defined system would be executed
first.
See also ‘RUN-SYSTEMS‘, ‘DELETE-SYSTEM‘.
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‘.
Unhooks the function ‘FN‘ from the ‘HOOK‘.
If the function wasn’t registered with ‘HOOK-UP‘ on a given hook, this
macro has no effect.
Complexity: *O(m)*, where *m* is the number of functions on a given hook.
Copies all components present in ‘SOURCE‘ entity to ‘DESTINATION‘
entity (freshly created entity by default), overriding any existing data.
Skips components denoted by keywords in optional ‘EXCEPT‘ list.
See also ‘REPLACE-COMPONENT‘.
Deletes given ‘ENTITY‘ and all of its components in the order they’ve been
defined with ‘DEFCOMPONENT‘.
Complexity: amortized *O(m + log p)*, where *m* is the number of defined components, and *p* is the number of deleted & unreclaimed entities so far.
Deletes system identified by ‘NAME‘ (either string, symbol or keyword) that was previously defined with ‘DEFSYSTEM‘. Throws an error if there’s no system with given name.
Return ‘T‘ if entity is valid.
Complexity: *O(1)*.
Creates and returns a new componentless entity.
Note that when no entities were deleted, ‘MAKE-ENTITY‘ returns new ones in
strictly ascending order, i.e. the entities would be processed by systems in
the order they’ve been created. When there are deleted entities, they’d be
reclaimed by ‘MAKE-ENTITY‘.
Complexity: amortized *O(1)*.
See also ‘DELETE-ENTITY‘.
Creates and returns a new object (that is, an entity with a set of
components) 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.
For a technical reasons, the count of component specifiers in ‘SPEC‘ should
not exceed 4000 (which is more than enough for any practical usage).
See also ‘MAKE-ENTITY‘, ‘DELETE-ENTITY‘.
Initializes a new component data storage.
Optional ‘INITIAL-ALLOCATED‘ argument sets the initial count of pre-allocated
entities and defaults to 32.
Note: this triggers initialization of entity variables defined by ‘DEFENTITY‘.
See also ‘*STORAGE*‘.
Prints given list of ‘ENTITIES‘ to the picture identified by ‘FILENAME‘ and
‘FORMAT‘ (defaulting to PNG), and keeps Graphviz source file if ‘KEEP-SOURCE‘
is ‘T‘. Image’s background color could be specified by the string designator
‘BG-COLOR‘.
Entity names would be printed according to ‘NAME-GETTER‘, a function of one
argument that takes an entity and returns any value. Component slot values
would be printed according to ‘VALUE-PRINTER‘, a function of one argument that
takes a value and returns its representation.
To be used in debugging and demo scenarios.
See also ‘*SKIP-PRINTING-COMPONENTS*‘.
Prints given ‘ENTITY‘ to the ‘STREAM‘ in a way that is compatible with
‘MAKE-OBJECT‘. To be used in debugging scenarios.
See also ‘*SKIP-PRINTING-COMPONENTS*‘.
Runs all of the systems registered with ‘DEFSYSTEM‘ with given optional
keyword ‘ARGUMENTS‘.
NOTE: creating or removing components between calls to ‘RUN-SYSTEMS‘ incurs small performance penalty on all affected systems because of recalculation of set of entities the system should process.
Adjoins single non-empty component specification ‘ITEM‘ to object
specification ‘SPEC‘ as if by ‘ADJOIN‘, i.e. if spec already has given
component spec, returns it untouched, otherwise returns the new spec with
given component spec added.
See also ‘MAKE-OBJECT‘.
Returns a system function object with given ‘NAME‘ (either
string, symbol or keyword); returns ‘NIL‘ if there’s no system with such name.
An upsert operator which first ensures the component exists
on a given entity and then sets its values according to given keyword
arguments, but keeps slots that weren’t specified to their previous values.
Not recommended for using in a tight loops such as systems, see ‘DEFCOMPONENT‘ documentation for alternatives.
Deletes a component from a given ‘ENTITY‘ in generic fashion.
Not recommended for using in a tight loops such as systems, see ‘DEFCOMPONENT‘ documentation for alternatives.
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.
Prints component data to the given ‘STREAM‘.
See ‘PRINT-ENTITY‘.
Copies component slot values from given ‘SOURCE-ENTITY‘ to
given ‘DEST-ENTITY‘ in generic fashion.
Not recommended for using in a tight loops such as systems, see ‘DEFCOMPONENT‘ documentation for alternatives.
Resets the values of component slots to their default values
for given ‘ENTITY‘.
Not recommended for using in a tight loops such as systems, see ‘DEFCOMPONENT‘ documentation for alternatives.
component-soa-class
) &rest initargs) ¶sb-mop
.
component-soa-class
) &key &allow-other-keys) ¶component-soa
) added deleted plist &rest rest) ¶component-soa-class
) (super standard-class
)) ¶sb-mop
.
Topologically sort systems according to their BEFORE and AFTER constraints with respect to newly added system, using DFS.
component-soa
)) ¶automatically generated reader method
component-soa
)) ¶automatically generated writer method
component-soa
)) ¶automatically generated reader method
component-soa
)) ¶automatically generated writer method
component-soa
)) ¶automatically generated reader method
component-soa
)) ¶automatically generated writer method
component-soa
)) ¶automatically generated reader method
component-soa
)) ¶automatically generated writer method
component-soa
)) ¶automatically generated reader method
component-soa
)) ¶automatically generated writer method
component-soa-slot
)) ¶automatically generated reader method
component-soa-slot
)) ¶automatically generated writer method
component-soa-slot
)) ¶automatically generated reader method
component-soa-slot
)) ¶automatically generated writer method
component-soa-slot
)) ¶automatically generated reader method
component-soa-slot
)) ¶automatically generated writer method
component-soa-slot
)) ¶automatically generated reader method
component-soa-slot
)) ¶automatically generated writer method
component-soa-slot
)) ¶automatically generated reader method
component-soa-slot
)) ¶automatically generated writer method
component-soa-slot
)) ¶automatically generated reader method
component-soa-slot
)) ¶automatically generated writer method
structure-object
.
alexandria:array-length
0
(simple-array cl-fast-ecs:entity (*))
alexandria:array-length
0
(simple-array (or cl-fast-ecs::component-soa null) (*))
simple-bit-vector
simple-bit-vector
(setf component-soa-allocated)
.
component-soa-allocated
.
(setf component-soa-count)
.
component-soa-count
.
(setf component-soa-exists)
.
component-soa-exists
.
(setf component-soa-max-entity)
.
component-soa-max-entity
.
(setf component-soa-min-entity)
.
component-soa-min-entity
.
update-instance-for-redefined-class
.
alexandria:array-length
cl-fast-ecs::*storage-entities-allocated*
:allocated
simple-bit-vector
(make-array cl-fast-ecs::*storage-entities-allocated* :element-type (quote bit) :initial-element 0)
cl-fast-ecs:entity
array-dimension-limit
cl-fast-ecs:entity
-1
common-lisp
.
alexandria:array-length
0
standard-class
.
standard-direct-slot-definition
.
:slot-type
:slot-index
:slot-index-unique
:slot-composite-index
:slot-composite-index-unique
:obsoletep
Jump to: | %
(
A B C D E F G H I M N O P R S U V W |
---|
Jump to: | %
(
A B C D E F G H I M N O P R S U V W |
---|
Jump to: | *
A C D E M O S |
---|
Jump to: | *
A C D E M O S |
---|
Jump to: | C E F H I M P S T |
---|
Jump to: | C E F H I M P S T |
---|