flock-cli

A Rails-like command-line tool for the Flock game engine: scaffold a project, generate components/systems/plugins, run it with hot reload, build it (native or WebAssembly), and bundle its assets.

Namespace Flock::Cli. Pure Crystal standard library — no third-party dependencies.

Prerequisites

• Crystal >= 1.16.0 on your PATH (build/run/dev shell out to crystal build).
• The Flock ecosystem checkout — a directory that contains flock/ (plus flock-collision/, flock-tilemap/, flock-ldtk/ if you use those features). The CLI locates it, in order, via:
  1. flock new --flock-path PATH,
  2. the FLOCK_PATH environment variable,
  3. otherwise the parent-of-parent of the flock binary (so a checkout laid out as .../native-wgpu/{flock,flock-cli,…} just works).
• SDL3 + a GPU runtime to actually run a game (required by the engine, not by the CLI).
• Web target only: the project must provide web/build.sh / web/dev.sh (the wesh WASM toolchain). Native projects don't have these and the CLI says so if you ask for --target web.

Install

cd flock-cli
shards build          # -> bin/flock

Put bin/flock on your PATH (or call it directly). No shards install is needed — there are no dependencies.

flock version         # flock 0.1.0
flock help

Quick start

flock new mygame --2d
cd mygame
flock g component Velocity dx:f32 dy:f32
flock g entity Player Velocity
flock g system Movement --schedule update
flock dev             # builds, runs, and rebuilds+restarts on every save

Commands

Every command except new must run inside a project — the directory the CLI marks with .flock/config.json. Outside one you get not a flock project (missing ./.flock/config.json).

dev — hot reload

• Native (default): polls src/**/*.cr and assets/**/*; on any add/edit/delete it rebuilds and restarts the game. A failing build keeps the watcher alive. Ctrl-C stops the child gracefully (SIGTERM, then SIGKILL after a short grace period).
• Web (--target web): delegates to the project's web/dev.sh (the wesh WASM dev loop).

run — argument splitting

Args before a literal -- are the CLI's; everything after goes to the game:

flock run --release -- --level 3 --debug   # --release builds; --level/--debug reach the game

Generators

flock g TYPE NAME [args…] — destroy takes the same types. Names accept player-health, player_health, or PlayerHealth: files are snake_case, types are CamelCase.

Field types (component, resource)

name:type pairs; a bare name defaults to Float32.

flock g component Position x:f32 y:f32
flock g component Target who:entity range:f32

entity fields have no default, so they are ordered first in the generated initialize.

System schedules

--schedule accepts first, update (default), fixed / fixedupdate, render, last.

Generated project layout

NAME/
  .flock/config.json      # {name, dim, features, flock_path} — marks a flock project
  shard.yml               # Flock shards as relative-path deps; no `shards install`
  .gitignore
  README.md
  src/
    NAME.cr               # entry: requires the stack, builds the App, applies Registry, runs
    registry.cr           # PLUGINS / STARTUPS / SYSTEMS + apply
    components/.keep.cr    # each dir seeded so `require "./dir/*"` resolves
    entities/.keep.cr
    systems/.keep.cr
    resources/.keep.cr
    plugins/.keep.cr
  assets/
    .gitkeep
    world.ldtk            # only with --ldtk (a starter 8x6 IntGrid level)

The entry src/NAME.cr opens a 960×540 window and installs a starter scene that matches the chosen features (2D sprite, 3D cube, 2D/3D collision floor + falling boxes, or a framed LDtk level). Shards are referenced by relative path, so the tree is portable and needs no shards install.

End-to-end examples

Physics project, ship a release build, bundle assets:

flock new arena --2d --collision
cd arena
flock run                 # build + run once (floor + falling boxes)
flock build --release     # -> bin/arena
flock pack assets -o arena.flkpack

LDtk 2D project, then a web build:

flock new platformer --ldtk   # writes assets/world.ldtk
cd platformer
flock dev                      # native hot reload
flock build --target web       # requires web/build.sh (wesh)

License

MIT — see LICENSE.