This is the cl-fast-ecs Reference Manual, version 0.5.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Jun 15 04:00:20 2025 GMT+0.
The main system appears first, followed by any subsystem dependency.
cl-fast-ecsBlazingly fast Entity-Component-System microframework.
Andrew Kravchuk <awkravchuk@gmail.com>
MIT
0.5.1
alexandria (system).
trivial-garbage (system).
src (module).
Modules are listed depth-first from the system components tree.
cl-fast-ecs/srccl-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.asdcl-fast-ecs/src/package.lispcl-fast-ecs/src/components.lispcl-fast-ecs/src/entities.lispcl-fast-ecs/src/hooks.lispcl-fast-ecs/src/index.lispcl-fast-ecs/src/storage.lispcl-fast-ecs/src/systems.lispcl-fast-ecs/src/components.lisphooks.lisp (file).
index.lisp (file).
src (module).
*component-defined-hook* (special variable).
*component-redefined-hook* (special variable).
*component-storage-grown-hook* (special variable).
defcomponent (macro).
define-component (macro).
delete-component (generic function).
make-component (generic function).
print-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-index (function).
%with-macro-decl (function).
*component-registry* (special variable).
*component-registry-length* (special variable).
cl-fast-ecs/src/entities.lispcomponents.lisp (file).
hooks.lisp (file).
index.lisp (file).
storage.lisp (file).
src (module).
*entity-deleting-hook* (special variable).
*entity-storage-grown-hook* (special variable).
delete-entity (function).
entity-valid-p (function).
make-entity (function).
make-object (compiler macro).
make-object (function).
print-entity (function).
maybe-check-entity (macro).
cl-fast-ecs/src/hooks.lispsrc (module).
adjust-array* (macro).
defhook (macro).
run-hook (function).
cl-fast-ecs/src/index.lispstorage.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.lisphooks.lisp (file).
src (module).
*storage* (special variable).
bind-storage (function).
entity (type).
make-storage (function).
%make-storage (function).
component-soa (structure).
component-soa-allocated (reader).
(setf component-soa-allocated) (writer).
component-soa-count (reader).
(setf component-soa-count) (writer).
component-soa-exists (reader).
(setf component-soa-exists) (writer).
component-soa-max-entity (reader).
(setf component-soa-max-entity) (writer).
component-soa-min-entity (reader).
(setf component-soa-min-entity) (writer).
component-soa-slots (reader).
(setf component-soa-slots) (writer).
copy-storage (function).
make-component-soa (function).
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-allocated (reader).
(setf storage-entities-allocated) (writer).
storage-entities-count (reader).
(setf storage-entities-count) (writer).
storage-p (function).
cl-fast-ecs/src/systems.lispentities.lisp (file).
storage.lisp (file).
src (module).
define-system (macro).
defsystem (macro).
delete-system (function).
run-systems (function).
system-exists-p (function).
%rebuild-entities-bitmap (function).
*system-bitmap-rebuilders* (special variable).
*system-registry* (special variable).
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 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.
ecs
common-lisp.
*component-defined-hook* (special variable).
*component-redefined-hook* (special variable).
*component-storage-grown-hook* (special variable).
*entity-deleting-hook* (special variable).
*entity-storage-grown-hook* (special variable).
*storage* (special variable).
bind-storage (function).
defcomponent (macro).
define-component (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-entity (function).
run-systems (function).
system-exists-p (function).
unhook (macro).
%accessor-decls (function).
%composite-index-accessor-decls (function).
%ctor-decl (function).
%dtor-decl (function).
%index-accessor-decls (function).
%make-storage (function).
%non-unique-error (function).
%rebuild-entities-bitmap (function).
%soa-decl (function).
%update-composite-index (function).
%update-index (function).
%with-macro-decl (function).
*component-registry* (special variable).
*component-registry-length* (special variable).
*system-bitmap-rebuilders* (special variable).
*system-registry* (special variable).
adjust-array* (macro).
binary-search (function).
component-soa (structure).
component-soa-allocated (reader).
(setf component-soa-allocated) (writer).
component-soa-count (reader).
(setf component-soa-count) (writer).
component-soa-exists (reader).
(setf component-soa-exists) (writer).
component-soa-max-entity (reader).
(setf component-soa-max-entity) (writer).
component-soa-min-entity (reader).
(setf component-soa-min-entity) (writer).
component-soa-slots (reader).
(setf component-soa-slots) (writer).
copy-storage (function).
defhook (macro).
index-bucket (macro).
index-delete (macro).
index-enumerate (macro).
index-insert (macro).
index-lookup (macro).
index-lookup-1 (macro).
index-maybe-grow (macro).
make-component-soa (function).
maybe-check-entity (macro).
new-capacity (function).
run-hook (function).
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-allocated (reader).
(setf storage-entities-allocated) (writer).
storage-entities-count (reader).
(setf storage-entities-count) (writer).
storage-p (function).
values-equal (macro).
Definitions are sorted by export status, category, package, and then by lexicographic order.
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‘.
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‘.
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‘.
Called before deleting an entity. An argument for the call is the entity
about to be deleted.
Note: this is a perfect place to delete entity’s children when implementing
parent/child relationships.
See also ‘DELETE-ENTITY‘, ‘HOOK-UP‘.
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‘.
Global storage instance to be used by virtually all library functions.
NOTE: it is not bound to any value initially.
See also ‘BIND-STORAGE‘.
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 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.
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 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;
* 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;
* 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;
* a ‘REPLACE-name‘ function which copies the component slot values from one
given entity to another;
* 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.
An alias for ‘DEFCOMPONENT‘.
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.
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
function has no effect.
Complexity: *O(m)*, where *m* is the number of functions on a given hook.
Binds global variable ‘*STORAGE*‘ to the newly created storage instance.
See also ‘MAKE-STORAGE‘.
Delete 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 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.
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‘.
Creates and returns a new storage instance.
Optional ‘INITIAL-ALLOCATED‘ argument sets the initial count of pre-allocated
entities and defaults to 32.
See also ‘BIND-STORAGE‘.
Prints given ‘ENTITY‘ to the ‘STREAM‘ in a way that is compatible with ‘MAKE-OBJECT‘. To be used in debugging scenarios.
Runs all of the systems registered with ‘DEFSYSTEM‘ with given optional keyword ‘ARGUMENTS‘.
Returns generalized boolean corresponding to system with given ‘NAME‘ (either string, symbol or keyword); that is, either ‘NIL‘ or the actual system function.
Deletes a compionent on 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‘.
Re-creates array with a new size, keeping it simple.
structure-object.
alexandria:array-length
0
simple-bit-vector
cl-fast-ecs:entity
array-dimension-limit
cl-fast-ecs:entity
-1
common-lisp.
alexandria:array-length
0
hash-table
(make-hash-table :test (function eq))
structure-object.
alexandria:array-length
0
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
| Jump to: | %
(
A B C D E F G H I M N P R S U V |
|---|
| Jump to: | %
(
A B C D E F G H I M N P R S U V |
|---|
| Jump to: | *
A C D E M S |
|---|
| Jump to: | *
A C D E M S |
|---|
| Jump to: | C E F H I M P S T |
|---|
| Jump to: | C E F H I M P S T |
|---|