CmdFX

A lightweight game engine for your terminal.

cmdfx is a lightweight game engine for your terminal, allowing you to create some pretty wild things. It is designed to be simple and easy to use, while still providing a powerful set of features.

It is written in C and is available cross-platform. It is licensed under the MIT license.

🍎 Features

Cross-platform: cmdfx is available on Windows, macOS, and Linux.
Lightweight: cmdfx is designed to be lightweight and fast.
Easy to use: cmdfx is simple to use and easy to learn.
Powerful: cmdfx provides a powerful set of features for creating terminal-based games.

📋 Highlighted Features

For a full method list, check out the documentation.

Events API
- Handle window events such as key presses and window resizing.
- Get the current state of the keyboard.
Canvas API
- Draw characters and shapes on the terminal.
- Set foreground and background colors.
- Clear the screen.
- Get the size of the terminal and the screen.
- ...and much more!
- Sprites API
  - Load and draw sprites on the terminal.
  - Set the color of a sprite.
  - Create Gradients for a sprite.
  - ...and much more!
Builder API
- Easily build 2D arrays of characters and strings.
- Set the color of the text.
- Create gradients of text and colors!
- ...and much more!
Physics Engine
- Create and manage physics objects with the Sprite API.
- Set the velocity and acceleration of a sprite.
- Detect collisions between sprites.
- ...and much more!
Input API
- Get the current state of the keyboard and mouse events.
- Handle key presses and key releases.
- ..and much more!
Cross-Platform Exposure
- Expose platform-specific features and utilities such as setting the title of the terminal.

📦 Installation

You can download the latest release of cmdfx from the releases page.

Install via Script

Use the cross-platform Bash installer to clone, build, and install cmdfx with CMake.

Prerequisites

Linux requires the installation of the ALSA sound library:

sudo apt-get update
sudo apt-get install -y libasound2-dev

If this is not installed, sound support will not be built.

Running the Installer

# default install (includes kotlin/native, tests, docs, full clone)
curl -fsSL https://raw.githubusercontent.com/gmitch215/cmdfx/master/install.sh | bash

# disable kotlin/native and enable shallow (most common use case with c/c++)
curl -fsSL https://raw.githubusercontent.com/gmitch215/cmdfx/master/install.sh | bash -s -- --no-kn --shallow

# include debug statements
curl -fsSL https://raw.githubusercontent.com/gmitch215/cmdfx/master/install.sh | bash -s -- --type Debug

# to disable building tests
curl -fsSL https://raw.githubusercontent.com/gmitch215/cmdfx/master/install.sh | bash -s -- --no-tests

# to disable including documentation
curl -fsSL https://raw.githubusercontent.com/gmitch215/cmdfx/master/install.sh | bash -s -- --no-docs

macOS/Linux (bash/zsh):

curl -fsSL https://raw.githubusercontent.com/gmitch215/cmdfx/master/install.sh -o install-cmdfx.sh
bash install-cmdfx.sh

Windows: run from Git Bash (bundled with Git for Windows) or MSYS2 shell:

curl -fsSL https://raw.githubusercontent.com/gmitch215/cmdfx/master/install.sh -o install-cmdfx.sh
bash install-cmdfx.sh

Defaults after a no-flags run:

MacOS: installs to /usr/local
Linux: installs to /usr
Windows (Git Bash/MSYS): installs to C:/Program Files/cmdfx

Common options:

--branch <name>: install a tag/branch (e.g. v0.3.3)

curl -fsSL https://raw.githubusercontent.com/gmitch215/cmdfx/master/install.sh | bash -s -- --branch v0.3.3

--prefix <path>: change install prefix

curl -fsSL https://raw.githubusercontent.com/gmitch215/cmdfx/master/install.sh | bash -s -- --prefix /custom/path

--type <Release|Debug>: CMake build type

curl -fsSL https://raw.githubusercontent.com/gmitch215/cmdfx/master/install.sh | bash -s -- --type Release

--shallow: faster shallow clone

curl -fsSL https://raw.githubusercontent.com/gmitch215/cmdfx/master/install.sh | bash -s -- --shallow

--no-tests, --no-docs, --no-package, --no-kn: toggle optional components

curl -fsSL https://raw.githubusercontent.com/gmitch215/cmdfx/master/install.sh | bash -s -- --no-tests --no-docs

Run ./install.sh --help for full options.

Use in CMake Projects

cmdfx installs a CMake package with the target cmdfx::cmdfx.

find_package(cmdfx REQUIRED)
add_executable(app main.c)
target_link_libraries(app PRIVATE cmdfx::cmdfx)

If CMake cannot find the package, point it at the install prefix:

cmake -S . -B build -DCMAKE_PREFIX_PATH="/usr/local"   # macOS
cmake -S . -B build -DCMAKE_PREFIX_PATH="/usr"         # Linux
cmake -S . -B build -DCMAKE_PREFIX_PATH="C:/Program Files/cmdfx"  # Windows

GitHub Actions

Install cmdfx via the script, then build your project with CMake using the exported package.

name: Build with cmdfx

on: [push, pull_request]

jobs:
  build:
  runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        include:
          - os: ubuntu-latest
            cmake_prefix: /usr
          - os: macos-latest
            cmake_prefix: /usr/local
          - os: windows-latest
            cmake_prefix: 'C:/Program Files/cmdfx'
    steps:
      - uses: actions/checkout@v6
      - name: Install Linux Dependencies
        if: startsWith(matrix.os, 'ubuntu')
        shell: bash
        run: |
          sudo apt-get update
          sudo apt-get install -y libasound2-dev
      - name: Install cmdfx
        shell: bash
        run: |
          curl -fsSL https://raw.githubusercontent.com/gmitch215/cmdfx/master/install.sh | bash
      - name: Configure
        shell: bash
        run: |
          cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH="${{ matrix.cmake_prefix }}"
      - name: Build
        shell: bash
        run: cmake --build build

Kotlin/Native

If you are using Kotlin/Native, you can add cmdfx as a dependency in your build.gradle.kts file:

plugins {
    kotlin("multiplatform") version "<version>"
}

repositories {
    maven("https://repo.calcugames.xyz/repository/maven-releases/")
}

kotlin {
    // Define your targets here
    macosArm64()
    mingwX64()

    sourceSets {
        // for example, if you are using macOS arm64
        macosArm64Main.dependencies {
            implementation("dev.gmitch215.cmdfx:cmdfx-macosarm64:<version>@klib")
        }

        // or, if you are using windows
        mingwX64Main.dependencies {
            implementation("dev.gmitch215.cmdfx:cmdfx-mingwx64:<version>@klib")
        }
    }
}

🚀 Examples

#include <cmdfx.h>

int main() {
    // Set character at position (4, 4) to 'X'
    Canvas_setChar(4, 4, 'X');

    // Draw Circle with '#' at position (10, 10) with radius 5
    Canvas_fillCircle(10, 10, 5, '#');

    // Set Foreground to Red, then draw a line from (0, 0) to (10, 0)
    Canvas_setForeground(0xFF0000);
    Canvas_hLine(0, 0, 10);
}

#include <cmdfx.h>

int main() {
    // (path, z-index)
    CmdFX_Sprite* mySprite = Sprite_loadFromFile("sprite.txt", 0);
    Sprite_setForegroundAll(mySprite, 0xFF0000); // Set Color to Red

    // Draw Sprite at position (5, 5)
    Sprite_draw(5, 5, mySprite);

    // Move Sprite to position (10, 10)
    Sprite_moveTo(mySprite, 10, 10);

    // (width, height, char, ansi, z-index)
    CmdFX_Sprite* background = Sprite_createFilled(10, 10, '#', 0, 0);

    // Set Gradient to Foreground with Red, Green, and Gold
    Sprite_setForegroundGradientAll(background, GRADIENT_ANGLE_45, 0xFF0000, 0x00FF00, 0xFFD700);
}

#include <stdio.h>
#include <cmdfx.h>

// Detect when the terminal window is resized
int onResize(CmdFX_Event* event) {
    // Get payload data
    CmdFX_ResizeEvent* resizeEvent = (CmdFX_ResizeEvent*) event->data;

    // Print the previous and new size of the terminal
    printf("Terminal resized from %dx%d to %dx%d\n", resizeEvent->prevWidth, resizeEvent->prevHeight, resizeEvent->newWidth, resizeEvent->newHeight);

    return 0;
}

int main() {
    int r = 0;

    Canvas_clearScreen();
    addCmdFXEventListener(CMDFX_EVENT_RESIZE, onResize);

    while (1) {
        // Do nothing while we wait for an event
    }
}

More examples can be found in the samples directory.

📝 Contributing

If you would like to contribute to cmdfx, please see the contributing guidelines. All contributions are welcome!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

CmdFX

🍎 Features

📋 Highlighted Features

📦 Installation

Install via Script

Prerequisites

Running the Installer

Use in CMake Projects

GitHub Actions

Kotlin/Native

🚀 Examples

📝 Contributing

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

CmdFX

🍎 Features

📋 Highlighted Features

📦 Installation

Install via Script

Prerequisites

Running the Installer

Use in CMake Projects

GitHub Actions

Kotlin/Native

🚀 Examples

📝 Contributing