Eagle

A Crystal-native 2D/3D game engine: library, engine and viewer in one shard, compiling to a single executable. Inspired by LÖVE (immediate-mode drawing, load/update/draw) and Godot (scene tree, nodes, signals, action map).

Only two native dependencies: SDL2 and the platform's OpenGL 3.3. Everything else (PNG/QOI/BMP/WAV codecs, TrueType fonts, audio mixer, physics, particles, UI, 3D renderer with shadows) is written in Crystal.

See it running in the browser, along with every other example, at joeyrobert.github.io/eagle.cr.

require "eagle"
include Eagle

class Game < App
  @player = Sprite2D.new(Texture.new(Image.circle(32, Color::YELLOW)), Window.center)

  def load
    Input.map "left", Key::A, Key::Left, Input.axis(GamepadAxis::LeftX, -1)
    Input.map "right", Key::D, Key::Right, Input.axis(GamepadAxis::LeftX, 1)
    SceneTree.root.add(@player)
  end

  def update(dt : Float32)
    @player.x += Input.axis("left", "right") * 250 * dt
  end

  def draw(g : Graphics)
    g.print("Hello, Eagle!", 10, 10)
  end
end

Eagle.run(Game, title: "My Game", width: 960, height: 540)

Features

Getting started

brew install sdl2            # macOS (Linux: libsdl2-dev; Windows: SDL2 dev libs on the lib path)
git clone https://github.com/joeyrobert/eagle.cr && cd eagle.cr
shards build                 # builds bin/eagle
bin/eagle examples           # list examples
bin/eagle examples asteroids # run one
bin/eagle new mygame && cd mygame && shards install && ../bin/eagle run

Add to an existing project's shard.yml:

dependencies:
  eagle:
    github: joeyrobert/eagle.cr

Examples

examples/ contains complete, self-contained programs (no external assets):

• Games (2D): chess (full rules + alpha-beta AI), checkers (1 or 2 players, AI), breakout, asteroids, platformer, snake, roguelike
• Games (3D): coinrush3d
• Feature tests: smoke, sandbox2d, physics, physics3d, ui, interactions, embedded, flythrough3d, spatial_audio3d

Every example supports EAGLE_FRAMES=60 EAGLE_SCREENSHOT=out.png for automated verification.

Web and exports

bin/eagle export web examples/breakout/main.cr    # WebAssembly + WebGL2 bundle in dist/web/breakout/
bin/eagle export exe examples/breakout/main.cr    # single release executable (embed assets with Eagle.embed_assets)
bin/eagle export app examples/breakout/main.cr    # macOS .app
script/build-site.sh                              # marketing + docs site with every example playable in the browser

Web builds need brew install lld; Crystal's wasm libraries are fetched automatically.

Testing

crystal spec                 # ~210 specs incl. GPU-backed pixel tests (hidden window)
EAGLE_NO_GPU=1 crystal spec  # skip GPU specs (CI without a display)

Documentation

• docs/guide.md: concepts and API tour
• docs/plans/: architecture, roadmap, findings
• crystal docs: API reference

License

Eagle is licensed under the GNU Lesser General Public License v3.0 or later. See COPYING.LESSER and COPYING for the full text.