Quickdocs

cl-fast-ecs

2025-06-22

Blazingly fast Entity-Component-System microframework.

Upstream URL

gitlab.com/lockie/cl-fast-ecs

Author

Andrew Kravchuk <awkravchuk@gmail.com>

License

MIT

README

Provided Systems

1cl-fast-ecs

https://img.shields.io/gitlab/pipeline-status/lockie/cl-fast-ecs?label=tests&style=flat&extension=.png https://gitlab.com/lockie/cl-fast-ecs/badges/main/coverage.svg https://img.shields.io/gitlab/last-commit/lockie/cl-fast-ecs?ref=develop&style=flat&extension=.png https://img.shields.io/gitlab/v/tag/lockie/cl-fast-ecs?label=version&style=flat&extension=.png https://api.quickdocs.org/badge/cl-fast-ecs.svg https://packages.guix.gnu.org/packages/cl-fast-ecs/badges/latest-version.svg https://img.shields.io/gitlab/license/lockie/cl-fast-ecs?color=blue&style=flat&extension=.png https://img.shields.io/mastodon/follow/109994839335624904?color=858AFA&domain=https%3A%2F%2Ffunctional.cafe&label=follow&logo=mastodon&style=flat&extension=.png

NOTE: this software is of alpha quiality, 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.

See the documentation page for more details. There's also a series of tutorials on how to use this library: part 1, part 2.

1.1Features

GC-friendly, configurable high water mark for component storage size.
Ability to interactively redefine components and systems on the fly.
Ability to interactively add new components and systems on the fly.
Native Lisp, no C/C++ code.
Mininal external dependencies (alexandria, closer-mop, global-vars and trivial-adjust-simple-array).

1.2Installation

Just execute the following in your Lisp (assuming you have Quicklisp installed):

  (ql:quickload :cl-fast-ecs)

There's also a package for Guix package manager, you can use the following shell command to install it:

  guix install cl-fast-ecs

Currently tested to work on following Lisp compilers:

...although you might want to avoid CLISP and ABCL since those two always employ boxing for array elements, which kind of defeats the purpose of Struct-of-Arrays pattern used for performant data storage by this library.

1.3Usage

  (ql:quickload :cl-fast-ecs)
  (use-package :cl-fast-ecs)

  (defcomponent coordinate
    "Location information"
    (x 0.0 :type single-float :documentation "X coordinate")
    (y 0.0 :type single-float :documentation "Y coordinate"))

  (defcomponent velocity
    (x 0.0 :type single-float)
    (y 0.0 :type single-float))

  (defsystem move
    (:components-ro (velocity)
     :components-rw (coordinate))
    "Moves objects according to their velocity."
    (incf coordinate-x velocity-x)
    (incf coordinate-y velocity-y))

  (defsystem print
    (:components-ro (coordinate))
    (format t "entity ~a: (~a, ~a)~%" entity coordinate-x coordinate-y))

  (make-storage)

  (let ((entity0 (make-entity)))
    (make-coordinate entity0 :x 0.0 :y 0.0)
    (make-velocity entity0 :x 0.5 :y 0.5)
    (make-object '((:coordinate :x 1.0 :y 1.0)
                   (:velocity :x 0.1 :y 0.1)))
    (dotimes (i 3)
      (run-systems)))

1.4Games made using cl-fast-ecs

1.5Related projects

beast is a thin layer of sugar over CLOS.
cl-ecs offers defcomponent / defsys macros, similar to the ones found in this project, and uses hash tables for component storage.
lisp butts game engine (sic) rolls its own CLOS-based ECS implementation.

1.6Contributing

Merge requests are welcome, just please submit them against the develop branch. For major changes, please open an issue first to discuss what you would like to change.