-*- org -*-

#+TITLE The Catbird Game Engine

* About

Catbird is a game engine written in Guile Scheme that is built on top
of the Chickadee game toolkit.  It uses an object-oriented, scene tree
architecture similar to Godot.  Catbird encourages a live coding
approach to game development, allowing for almost all aspects of the
game, and even the engine itself, to be modified at runtime.

* Features

** Scene node tree
** State machine abstraction
** Input bindings
** General purpose 2D game objects (sprites, text, etc.)
** Automatic asset reloading
** In-engine REPL and command console

* Key Abstractions

** Nodes

Nodes encapsulate the state of an object in the game world.  Nodes can
be rendered, updated, and run asynchronous scripts.  Complex game
behavior is created by composing simpler nodes.  For example, a text
box could be implemented as the composition of a background sprite
with a text label over it.  Nodes can have up to one parent node and
zero or more child nodes, forming a tree structure.

** Modes

Modes encapsulate pieces of a game's state machine and serve as the
input handling layer.  There are 2 types of modes: major and minor.
Major modes are considered mutually incompatible with each other and
are used to represent different states within a game scene.  For
example, map traversal in an RPG could be represented by a major mode
for moving the player character around the map and another major mode
for interacting with objects/talking to NPCs.  Minor modes implement
smaller, composable pieces of game logic.  For example, text field
editing controls could be contained within a minor mode and composed
with every major mode that has the player type something.  All modes
have an input map, which translates keyboard/mouse/controller input
events to calls to their respective event handlers.

** Scenes

Scenes are a special type of node that encapsulate a coarse chunk of a
game's state machine.  For example, an RPG could be divided into
several scenes: world map, inventory, and battle.  Modes are attached
to scenes to form a playable game.  Scenes always have one active
major mode and zero or more minor modes.

** Cameras

Cameras provide a view into a scene.  They have a projection,
position, and orientation.  A 2D camera uses an orthographic
projection.  A 3D camera uses a perspective projection.  The same
scene can be rendered using multiple cameras, if desired, such as in a
split-screen multiplayer game.

** Regions

Regions represent a sub-section of the game window, creating a
viewport to which a game scene can be rendered.  Regions can be
associated with one scene and one camera.  When both a scene and
camera are present, the scene is rendered to the region's viewport
from the perspective of the camera.  In a typical case, one region
that covers the entire window is all that's needed.  A split-screen
multiplayer game, however, could divide the window into two regions
and render the same scene using different cameras.

** Assets

Assets are containers for non-Scheme data that is loaded from the file
system, such as an images or audio files.  Assets are lazy loaded when
they are first dereferenced or can be manually eager loaded.  When in
development mode, the files associated with assets are watched for
changes and automatically reloaded when they change.

* Building

If using Guix, life is easy.  Run =guix shell= to launch a shell that
has all the dependencies needed to build Catbird.

If not using Guix, install these dependencies some other way:

- Guile >= 3.0
- Chickadee >= 0.9.0

To build:

#+BEGIN_SRC sh
  ./bootstrap
  ./configure
  make -j${nproc}
#+END_SRC

* License

Apache 2.0