Entities

An entity is an association list whose keys are CHICKEN keywords (#:type, #:x, #:vx, etc.). For example, the platformer's player after plist->alist looks like:

((#:type    . player)
 (#:x       . 100)   (#:y      . 50)
 (#:width   . 16)    (#:height . 16)
 (#:vx      . 0)     (#:vy     . 0)
 (#:gravity? . #t)   (#:on-ground? . #f)
 (#:tile-id . 1)     (#:tags   . (player)))

The engine defines a handful of shared keys (#:type, #:x, #:y, #:width, #:height, #:vx, #:vy, #:tile-id, #:tags, and a few more per subsystem) that the built-in pipelines read and write. Your game is free to add any other keys it needs — they're just data and the engine ignores what it doesn't know.

There is also a minimal constructor for the positional fields, which sets #:type to 'none:

(make-entity x y w h)
;; → ((#:type . none) (#:x . x) (#:y . y) (#:width . w) (#:height . h))

In practice most entities are built via plist->alist (for ad-hoc inline data) or via instantiate-prefab (for data-file-driven composition).

Since an entity is a regular alist, you can inspect it the usual way at the REPL: (entity-ref e #:vx), (assq #:tags e), (length e).

All entity operations are pure and immutable: every call returns a fresh alist; your input is never mutated. The full surface is small.

Hand-writing a long plist for every enemy gets old fast. The (downstroke prefabs) module loads a data file that declares reusable mixins (named bundles of keys) and prefabs (named entities built by combining mixins and inline overrides).

A prefab data file is a single sexp with mixins, prefabs, and an optional group-prefabs section. Here is the animation demo's file (demo/assets/animation-prefabs.scm):

((mixins)
 (prefabs
  (timed-frames animated  #:type timed-frames  #:anim-name walk
                #:animations ((#:name walk #:frames ((28 10) (29 1000)))))
  (std-frames   animated  #:type std-frames    #:anim-name attack
                #:animations ((#:name attack #:frames (28 29) #:duration 10)))))

Each prefab entry has the shape (name mixin-name ... #:k v #:k v ...). Before the first keyword, identifiers name mixins to pull in; from the first keyword onward you write inline fields.

The engine ships a small mixin table via (engine-mixins):

(engine-mixins)
;; → ((physics-body #:vx 0 #:vy 0 #:ay 0 #:gravity? #t #:solid? #t #:on-ground? #f)
;;    (has-facing   #:facing 1)
;;    (animated     #:anim-name idle #:anim-frame 0 #:anim-tick 0
;;                  #:tile-id 0 #:animations #t))

User-defined mixins go in the (mixins ...) section of the data file and take precedence if they share a name with an engine mixin.

Each frame the engine runs a sequence of per-entity pipeline steps (acceleration, gravity, velocity-x, tile-collisions-x, velocity-y, tile-collisions-y, on-solid, tweens, animation, entity-collisions, …). An individual entity can opt out of any of these by listing the step's symbol in its #:skip-pipelines key:

(entity-set player #:skip-pipelines '(gravity velocity-x))
;; → player now ignores gravity and horizontal motion integration

The predicate is entity-skips-pipeline?:

(entity-skips-pipeline? player 'gravity)  ; → #t / #f

Every built-in step is defined with the define-pipeline macro ((downstroke entity)), which wraps the body in the skip check. The macro has two shapes:

(define-pipeline (identifier name) (scene entity dt)
  body)

(define-pipeline (identifier name) (scene entity dt)
    guard: guard-expr
  body)

• identifier is the procedure name (e.g. apply-gravity).
• name is the symbol users put into #:skip-pipelines (e.g. gravity).
• guard-expr, when given, must evaluate truthy for the body to run; otherwise the entity is returned unchanged.

Example from physics.scm:

(define-pipeline (apply-gravity gravity) (scene entity dt)
    guard: (entity-ref entity #:gravity? #f)
  (entity-set entity #:vy (+ (entity-ref entity #:vy) *gravity*)))

Reading the shape: the procedure is apply-gravity; adding gravity to #:skip-pipelines disables it on one entity; guard: means the step is skipped entity-wide when #:gravity? is false.

For the full list of built-in step symbols, see physics.org.

Good for one-offs, tiny demos, prototypes, and scripts where pulling in a data file is overkill. The getting-started and scaling demos do this exclusively:

(plist->alist
 (list #:type   'box
       #:x (/ +width+ 2) #:y (/ +height+ 2)
       #:width  +box-size+ #:height +box-size+
       #:vx 0 #:vy 0
       #:color '(255 200 0)))

Scaling demo — run with bin/demo-scaling, source in demo/scaling.scm. Getting-started demo — run with bin/demo-getting-started, source in demo/getting-started.scm.

When several entities share fields, lift them into mixins and let prefabs stamp them out:

;; assets/actors.scm
((mixins
  (enemy-defaults #:solid? #t #:tags (enemy) #:hp 3))
 (prefabs
  (grunt   physics-body has-facing enemy-defaults #:type grunt
           #:tile-id 50 #:width 16 #:height 16)
  (brute   physics-body has-facing enemy-defaults #:type brute
           #:tile-id 51 #:width 32 #:height 32 #:hp 8)))

(define reg (load-prefabs "assets/actors.scm" (engine-mixins) '()))
(define g   (instantiate-prefab reg 'grunt 100 100 16 16))
(define b   (instantiate-prefab reg 'brute 200 100 32 32))

physics-body, has-facing, animated are engine mixins — see (engine-mixins) above. Inline fields (e.g. #:hp 8 on brute) override values from mixins.

Animation demo (prefab + load-prefabs) — run with bin/demo-animation, source in demo/animation.scm. Platformer demo (hand-built player via plist->alist) — run with bin/demo-platformer, source in demo/platformer.scm.

User mixins live in the same data file's (mixins ...) section; if the name collides with an engine mixin, the user version wins:

((mixins
  ;; Overrides the engine's physics-body: no gravity for this game.
  (physics-body  #:vx 0 #:vy 0 #:gravity? #f #:solid? #t)
  ;; A brand-new mixin:
  (stompable     #:stompable? #t #:stomp-hp 1))
 (prefabs
  (slime  physics-body stompable #:type slime #:tile-id 70)))

No engine change is needed — mixin names are resolved at load-prefabs time.

When you have per-entity logic that should honor #:skip-pipelines, reach for define-pipeline instead of writing a plain function. A minimal example:

(import (downstroke entity))

;; A decay step. Users can skip it with #:skip-pipelines '(decay).
(define-pipeline (apply-decay decay) (scene entity dt)
    guard: (entity-ref entity #:decays? #f)
  (entity-update entity #:hp (lambda (hp) (max 0 (- hp 1))) 0))

Call it like any other step: (apply-decay scene entity dt). Wiring it into the frame is the engine's job; see physics.org for how built-in steps are composed and how to provide a custom engine-update if you need a different order.