Add README.

1 files changed, 104 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..b8fc85c
--- /dev/null
+++ b/README
@@ -0,0 +1,104 @@
+-*- 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 windows
+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
+
+Catbird is available under the terms of the GNU General Public
+License, version 3 or later.