Blazingly fast Entity-Component-System microframework.

cl-fast-ecs

#+HTML: <p align="center"><img src="https://gitlab.com/lockie/cl-fast-ecs/-/raw/main/logo.svg" width="64px" /></p>

* cl-fast-ecs
[[https://gitlab.com/lockie/cl-fast-ecs/-/pipelines/main/latest][https://img.shields.io/gitlab/pipeline-status/lockie/cl-fast-ecs?label=tests&style=flat&extension=.png]] [[https://gitlab.com/lockie/cl-fast-ecs/-/commits/develop][https://img.shields.io/gitlab/last-commit/lockie/cl-fast-ecs?ref=develop&style=flat&extension=.png]] [[https://gitlab.com/lockie/cl-fast-ecs/-/tags][https://img.shields.io/gitlab/v/tag/lockie/cl-fast-ecs?label=version&style=flat&extension=.png]] [[https://quickdocs.org/cl-fast-ecs?tab=systems][https://api.quickdocs.org/badge/cl-fast-ecs.svg]] [[https://gitlab.com/lockie/cl-fast-ecs/-/blob/main/LICENSE][https://img.shields.io/gitlab/license/lockie/cl-fast-ecs?color=blue&style=flat&extension=.png]] [[https://functional.cafe/@awkravchuk][https://img.shields.io/mastodon/follow/109994839335624904?color=858AFA&domain=https%3A%2F%2Ffunctional.cafe&label=follow%20on%20mastodon&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 [[https://lockie.gitlab.io/cl-fast-ecs][documentation page]] for more details.

** Features
+ 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= and =trivial-garbage=).

** Installation
Just execute the following in your Lisp (assuming you have [[https://quicklisp.org][Quicklisp]] installed):
#+begin_src lisp
  (ql:quickload :cl-fast-ecs)
#+end_src

There's also a [[https://packages.guix.gnu.org/packages/cl-fast-ecs][package]] for Guix package manager, you can use the following shell command to install it:
#+begin_src shell
  guix install cl-fast-ecs
#+end_src

Currently tested to work on following Lisp compilers:
+ [[https://sbcl.org][SBCL]]
+ [[https://ccl.clozure.com][CCL]]
+ [[https://common-lisp.net/project/ecl][ECL]]
+ [[https://abcl.org][ABCL]]
+ [[https://gitlab.com/gnu-clisp/clisp][CLISP]]
+ [[https://franz.com/products/allegro-common-lisp][ACL]]

** Usage
#+begin_src lisp
  (ql:quickload :cl-fast-ecs)
  (use-package :cl-fast-ecs)

  (defcomponent position
    "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 (position))
    "Moves objects according to their velocity."
    (incf position-x velocity-x)
    (incf position-y velocity-y))

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

  (bind-storage)

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

** Games made using cl-fast-ecs
+ [[https://awkravchuk.itch.io/thoughtbound][Thoughtbound]]
+ [[https://awkravchuk.itch.io/mana-break][Mana Break]]
+ [[https://awkravchuk.itch.io/cycle-of-evil][Cycle of Evil]]
+ [[https://gitlab.com/lockie/cl-fast-ecs/-/issues/new][make your own!]]

** Related projects
+ [[https://github.com/sjl/beast][beast]] is a thin layer of sugar over CLOS.
+ [[https://github.com/bit-phlippers/cl-ecs][cl-ecs]] offers ~defcomponent~ / ~defsys~ macros, similar to the ones found in this project, and uses hash tables for component storage.
+ [[https://github.com/koto-bank/lbge][lisp butts game engine]] (sic) rolls its own CLOS-based ECS implementation.

** Contributing
Merge requests are welcome, just please submit them against the =develop= branch. For major changes, please [[https://gitlab.com/lockie/cl-fast-ecs/-/issues/new][open an issue]] first to discuss what you would like to change.

** Copyright
Copyright (C) 2023–2024 Andrew Kravchuk (awkravchuk@gmail.com).

** License
[[https://choosealicense.com/licenses/mit][MIT]]


cl-fast-ecs

Upstream URL

Author

License

cl-fast-ecs

Version:

License:

Authors:

Dependencies:

cl-fast-ecs/tests

License:

Authors:

Dependencies:

Dependencies (4)

Dependents (0)