How gmitch215/cmdfx works
Project Type and Purpose
• CmdFX is a cross-platform C library (game engine) for drawing and animating in the terminal.
• It exposes a public API (Canvas, Sprites, Physics, Events, Builder) and handles platform-specific details under the hood.
• It’s designed for embedding in C (or Kotlin/Native) programs, with samples and tests illustrating usage.
File Structure
Top-level directories and their responsibilities:
• /cmdfx/...
– Public headers (API): core, animation, canvas, builder, costumes, device, events, scenes, sprites, util, physics, ui.
• src/common/...
– Core engine implementations, platform-agnostic logic for animation, canvas drawing, physics calculations, UI widgets, event dispatching.
• src/{linux, macos, posix, windows}/core and physics
– Platform adapters implementing low-level terminal I/O, screen management, device queries, and any platform-specific physics hooks (if needed).
• cmake, CMakeLists.txt
– Build system: generates static/shared libraries, exports a Config.cmake, sets up installation targets.
• samples/
– Example applications demonstrating each API facet.
• test/
– Automated unit tests (test/src/core, test/src/physics) and manual smoke tests (test/src/manual).
• docs/
– Doxygen configuration and doc generator scripts.
README for Insights
• Confirms cross-platform support (Windows, macOS, Linux)
• Highlights subsystems: Events API, Canvas API (with Sprite extensions), Builder API, Physics Engine, Input API, and platform utilities.
• Points to samples and contributing guidelines.
Main Components & Their Relationships
[A] Consumer Applications
• Samples, User Code (integates via #include <cmdfx.h>)
→ calls
[B] Public API Layer (Headers)
• cmdfx.h orchestrates everything
• Sub-APIs: Canvas, Sprites, Builder, Events, Physics, UI, Device
→ invokes
[C] Core Engine Modules (src/common)
• Animation Engine, Canvas Renderer, Event Dispatcher, Physics Solver, UI Widgets, Utility functions
→ delegates low-level work to
[D] Platform Abstraction Interfaces
• Abstract interfaces declared in include/cmdfx/core/device.h, screen.h, util.h
→ implemented by
[E] Platform-Specific Modules
• src/linux/core/device.c & screen.c
• src/macos/core/device.c & screen.c
• src/windows/core/...
• src/posix/... (fallback)
→ make system calls / ANSI escape sequences / WinAPI calls to drive the terminal
[F] Build & Packaging
• CMake and cmake/Config.cmake.in generate library artifacts and export a Config module for downstream Kotlin/Native usage
→ enables
[G] Documentation Generator & CI
• docs/Doxyfile.in → doxygen.sh
• .github/workflows/build.yml & release.yml
[H] Testing
• test/src/core & test/src/physics → unit test executables
• test/src/manual → interactive/manual validation scripts
Architectural Patterns & Design Principles
• Layered Architecture: Clear separation between Public API, Core Logic, and Platform Drivers.
• Abstraction & Portability: Define interfaces in common headers, implement per-platform under src/{linux, windows, …}.
• Modularity: Each domain (animation, physics, UI) is a self-contained module under both include/ and src/common/.
• Testability: Core logic sits in src/common so it can be tested without depending on platform code.
• Build-Time Configuration: CMake orchestrates discovery of platform code and generation of a cross-platform library.