1cl-fast-ecs

https://img.shields.io/gitlab/pipeline-status/lockie/cl-fast-ecs?label=tests&style=flat&extension=.png 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://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%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 documentation page for more details.

1.1Features

• 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).

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:

• SBCL
• CCL
• ECL
• ABCL
• CLISP
• ACL

1.3Usage

  (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)))

1.4Games made using cl-fast-ecs

• Thoughtbound
• Mana Break
• Cycle of Evil
• make your own!

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.

1.7Copyright

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

1.8License

MIT