john/McRogueFace
1
0
Fork 0
Code Issues 32 Pull requests Projects Releases Wiki Activity

[Major Feature] True headless execution without X11/GPU dependencies #157

New issue
Closed
opened 2025-12-07 04:36:42 +00:00 by john · 3 comments
john commented 2025-12-07 04:36:42 +00:00
Owner
Copy link

Problem Statement

McRogueFace cannot execute on servers without X11, even with --headless mode. The current headless implementation avoids creating a window but still requires the full graphics stack:

HeadlessRenderer → sf::RenderTexture → SFML Graphics → OpenGL → X11

This prevents use cases like:

  • Running simulations on cloud servers (AWS, GCP, etc.)
  • CI/CD pipelines without Xvfb
  • Docker containers without GPU passthrough
  • Headless game servers for multiplayer scenarios
  • Batch processing / overnight simulation runs

Root Cause Analysis

SFML's architecture is the fundamental blocker. sf::RenderTexture::create() unconditionally initializes an OpenGL context, which on Linux requires X11 libraries and a display.

Current Dependencies

From CMakeLists.txt:

  • sfml-graphics (requires OpenGL)
  • sfml-window (requires X11/udev on Linux)
  • sfml-system (no graphics deps - safe)
  • sfml-audio (already disabled in headless)
  • OpenGL::GL (required by ImGui-SFML)

SFML Type Pervasiveness

  • 311 occurrences of sf:: types across codebase
  • Core interface: UIDrawable::render(sf::Vector2f, sf::RenderTarget&)
  • Types everywhere: sf::Vector2f, sf::Color, sf::FloatRect, sf::Font, sf::Texture

Requirements

  1. Must work without X11 - executable runs on headless Linux servers
  2. Must preserve screenshot capability - simulations need visual output
  3. Must not break existing functionality - current graphical mode unchanged
  4. Should minimize API changes - Python scripts shouldn't need modification

Potential Approaches

Option A: Software Rasterizer Backend

Replace OpenGL with a CPU-based renderer (Cairo, Skia, or custom).

Pros:

  • Full rendering capability including screenshots
  • No GPU/X11 required

Cons:

  • Massive undertaking - essentially reimplementing SFML Graphics
  • Performance implications for complex scenes
  • Need to handle fonts, textures, shaders differently

Option B: Conditional Compilation (Dual Binary)

Build two versions: mcrogueface (full) and mcrogueface-headless (minimal).

Pros:

  • Clean separation
  • Headless binary much smaller

Cons:

  • Two binaries to maintain
  • Preprocessor complexity throughout codebase
  • Still need rendering solution for screenshots

Option C: Abstract Renderer Interface + Pluggable Backends

Create RenderBackend abstraction with multiple implementations:

  • SFMLBackend - current behavior (requires X11)
  • SoftwareBackend - CPU rendering (no X11)
  • NullBackend - no rendering (fastest, no screenshots)

Pros:

  • Maximum flexibility
  • Clean architecture
  • Could add other backends later (Vulkan, etc.)

Cons:

  • Largest refactor (~100+ files)
  • Need to abstract all SFML types or keep sfml-system

Option D: Offscreen Mesa/OSMesa

Use Mesa's software OpenGL implementation.

Pros:

  • Minimal code changes
  • Full OpenGL compatibility

Cons:

  • Additional runtime dependency
  • Performance overhead
  • May not work in all environments

Option E: Wait for SFML 3.x

SFML 3.0 may have better headless support.

Pros:

  • Upstream solution

Cons:

  • Unknown timeline
  • Unknown if it actually solves this
  • Would require SFML upgrade anyway

Recommended Path

Option C (Abstract Renderer) with Option A (Software Rasterizer) as the headless backend.

This is the most future-proof approach but also the largest undertaking. It would:

  1. Define abstract RenderTarget interface (or wrapper around sf::RenderTarget)
  2. Create SoftwareRenderer using a library like:
    • stb_truetype + stb_image_write (minimal deps, C)
    • Cairo (mature, 2D focused)
    • Blend2D (modern, fast CPU 2D)
  3. Implement font rendering, texture loading, primitive drawing
  4. Wire up to existing HeadlessRenderer pathway

Scope Estimate

This is a Major Feature requiring:

  • Significant architectural changes
  • New dependencies evaluation
  • Extensive testing across both modes
  • Documentation updates

Not suitable for near-term v1.0 timeline. Should be planned as a post-1.0 enhancement or parallel long-term effort.

Workaround (Current)

For immediate needs, use virtual framebuffer:

xvfb-run -a ./mcrogueface --headless --exec script.py

Or in Docker:

RUN apt-get install -y xvfb
CMD ["xvfb-run", "-a", "./mcrogueface", "--headless", "--exec", "simulation.py"]

Related

  • #153 - Simulation/step mode (works but still needs X11)
  • HeadlessRenderer implementation (src/HeadlessRenderer.h/cpp)

References

## Problem Statement McRogueFace cannot execute on servers without X11, even with `--headless` mode. The current headless implementation avoids creating a window but still requires the full graphics stack: ``` HeadlessRenderer → sf::RenderTexture → SFML Graphics → OpenGL → X11 ``` This prevents use cases like: - Running simulations on cloud servers (AWS, GCP, etc.) - CI/CD pipelines without Xvfb - Docker containers without GPU passthrough - Headless game servers for multiplayer scenarios - Batch processing / overnight simulation runs ## Root Cause Analysis **SFML's architecture is the fundamental blocker.** `sf::RenderTexture::create()` unconditionally initializes an OpenGL context, which on Linux requires X11 libraries and a display. ### Current Dependencies From `CMakeLists.txt`: - `sfml-graphics` (requires OpenGL) - `sfml-window` (requires X11/udev on Linux) - `sfml-system` (no graphics deps - safe) - `sfml-audio` (already disabled in headless) - `OpenGL::GL` (required by ImGui-SFML) ### SFML Type Pervasiveness - **311 occurrences** of `sf::` types across codebase - Core interface: `UIDrawable::render(sf::Vector2f, sf::RenderTarget&)` - Types everywhere: `sf::Vector2f`, `sf::Color`, `sf::FloatRect`, `sf::Font`, `sf::Texture` ## Requirements 1. **Must work without X11** - executable runs on headless Linux servers 2. **Must preserve screenshot capability** - simulations need visual output 3. **Must not break existing functionality** - current graphical mode unchanged 4. **Should minimize API changes** - Python scripts shouldn't need modification ## Potential Approaches ### Option A: Software Rasterizer Backend Replace OpenGL with a CPU-based renderer (Cairo, Skia, or custom). **Pros:** - Full rendering capability including screenshots - No GPU/X11 required **Cons:** - Massive undertaking - essentially reimplementing SFML Graphics - Performance implications for complex scenes - Need to handle fonts, textures, shaders differently ### Option B: Conditional Compilation (Dual Binary) Build two versions: `mcrogueface` (full) and `mcrogueface-headless` (minimal). **Pros:** - Clean separation - Headless binary much smaller **Cons:** - Two binaries to maintain - Preprocessor complexity throughout codebase - Still need rendering solution for screenshots ### Option C: Abstract Renderer Interface + Pluggable Backends Create `RenderBackend` abstraction with multiple implementations: - `SFMLBackend` - current behavior (requires X11) - `SoftwareBackend` - CPU rendering (no X11) - `NullBackend` - no rendering (fastest, no screenshots) **Pros:** - Maximum flexibility - Clean architecture - Could add other backends later (Vulkan, etc.) **Cons:** - Largest refactor (~100+ files) - Need to abstract all SFML types or keep sfml-system ### Option D: Offscreen Mesa/OSMesa Use Mesa's software OpenGL implementation. **Pros:** - Minimal code changes - Full OpenGL compatibility **Cons:** - Additional runtime dependency - Performance overhead - May not work in all environments ### Option E: Wait for SFML 3.x SFML 3.0 may have better headless support. **Pros:** - Upstream solution **Cons:** - Unknown timeline - Unknown if it actually solves this - Would require SFML upgrade anyway ## Recommended Path **Option C (Abstract Renderer) with Option A (Software Rasterizer) as the headless backend.** This is the most future-proof approach but also the largest undertaking. It would: 1. Define abstract `RenderTarget` interface (or wrapper around sf::RenderTarget) 2. Create `SoftwareRenderer` using a library like: - **stb_truetype + stb_image_write** (minimal deps, C) - **Cairo** (mature, 2D focused) - **Blend2D** (modern, fast CPU 2D) 3. Implement font rendering, texture loading, primitive drawing 4. Wire up to existing `HeadlessRenderer` pathway ## Scope Estimate This is a **Major Feature** requiring: - Significant architectural changes - New dependencies evaluation - Extensive testing across both modes - Documentation updates Not suitable for near-term v1.0 timeline. Should be planned as a post-1.0 enhancement or parallel long-term effort. ## Workaround (Current) For immediate needs, use virtual framebuffer: ```bash xvfb-run -a ./mcrogueface --headless --exec script.py ``` Or in Docker: ```dockerfile RUN apt-get install -y xvfb CMD ["xvfb-run", "-a", "./mcrogueface", "--headless", "--exec", "simulation.py"] ``` ## Related - #153 - Simulation/step mode (works but still needs X11) - HeadlessRenderer implementation (`src/HeadlessRenderer.h/cpp`) ## References - [SFML and headless rendering discussion](https://en.sfml-dev.org/forums/index.php?topic=27691.0) - [Cairo Graphics](https://www.cairographics.org/) - [Blend2D](https://blend2d.com/) - [OSMesa](https://docs.mesa3d.org/osmesa.html)
john commented 2025-12-07 04:50:40 +00:00
Author
Owner
Copy link

Note: libtcod-headless Already Exists

The project already maintains a fork of libtcod without SDL dependencies: https://github.com/jmccardle/libtcod-headless

This means libtcod is not a blocker for true headless execution. The dependency situation is simpler than initially assessed:

Dependency Headless Status
libtcod-headless ✅ Ready (no SDL)
SFML ❌ Needs abstraction
CPython ✅ Works as-is
ImGui-SFML ❌ Tied to SFML

SFML is the sole blocker. The renderer abstraction work is the critical path for headless support.

This also has implications for future WASM/Emscripten builds — libtcod-headless should cross-compile cleanly without SDL concerns.

## Note: libtcod-headless Already Exists The project already maintains a fork of libtcod without SDL dependencies: https://github.com/jmccardle/libtcod-headless This means libtcod is **not a blocker** for true headless execution. The dependency situation is simpler than initially assessed: | Dependency | Headless Status | |------------|-----------------| | libtcod-headless | ✅ Ready (no SDL) | | SFML | ❌ Needs abstraction | | CPython | ✅ Works as-is | | ImGui-SFML | ❌ Tied to SFML | **SFML is the sole blocker.** The renderer abstraction work is the critical path for headless support. This also has implications for future WASM/Emscripten builds — libtcod-headless should cross-compile cleanly without SDL concerns.
john commented 2026-01-31 02:52:08 +00:00
Author
Owner
Copy link

Cross-Reference: Emscripten Research

Research on #158 (Emscripten) confirms that renderer abstraction is shared prerequisite work.

See docs/EMSCRIPTEN_RESEARCH.md on branch emscripten-mcrogueface for:

  • Detailed SFML usage inventory (1,276 occurrences across 78 files)
  • File-by-file abstraction difficulty ratings
  • Phased implementation plan

The HeadlessRenderer pattern already demonstrates the correct abstraction approach. A true headless backend (Option C from this issue) would:

  1. Implement same RenderBackend interface as SFML backend
  2. Use CPU-based rasterization (Cairo, Blend2D, or custom)
  3. Share the sf::RenderTarget* pointer pattern already in place

Both #157 and #158 benefit from the same Phase 3 work: Render Backend Interface.

## Cross-Reference: Emscripten Research Research on #158 (Emscripten) confirms that **renderer abstraction is shared prerequisite work**. See `docs/EMSCRIPTEN_RESEARCH.md` on branch `emscripten-mcrogueface` for: - Detailed SFML usage inventory (1,276 occurrences across 78 files) - File-by-file abstraction difficulty ratings - Phased implementation plan The `HeadlessRenderer` pattern already demonstrates the correct abstraction approach. A true headless backend (Option C from this issue) would: 1. Implement same `RenderBackend` interface as SFML backend 2. Use CPU-based rasterization (Cairo, Blend2D, or custom) 3. Share the `sf::RenderTarget*` pointer pattern already in place Both #157 and #158 benefit from the same Phase 3 work: **Render Backend Interface**.
john commented 2026-02-07 19:25:03 +00:00
Author
Owner
Copy link

Implemented across multiple commits: 7621ae3 and 4c70aee added MCRF_HEADLESS compile-time option, src/platform/HeadlessTypes.h provides no-op type stubs, and GLContext_Headless.cpp handles headless GL context. make from project root builds the standard target; headless builds use -DMCRF_HEADLESS=ON. The --headless --exec mode runs without a display server and is used extensively in CI/testing (50+ test files).

Implemented across multiple commits: `7621ae3` and `4c70aee` added `MCRF_HEADLESS` compile-time option, `src/platform/HeadlessTypes.h` provides no-op type stubs, and `GLContext_Headless.cpp` handles headless GL context. `make` from project root builds the standard target; headless builds use `-DMCRF_HEADLESS=ON`. The `--headless --exec` mode runs without a display server and is used extensively in CI/testing (50+ test files).
john closed this issue 2026-02-07 19:25:15 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
master
threedee
emscripten-mcrogueface
rogueliketutorial25
alpha_presentable
alpha_streamline_2
alpha_streamline_1
interpreter_mode
grid_entity_integration
reprs_and_member_names
break_up_ui_h
standardize_font_handling
standardize_vector_handling
standardize_color_handling
standardize_texture_handling
raii_pyobjects
rebase-for-7DRL_Feb-2024
engjam_uicollection
engjam_ui_overhaul
0.2.3-prerelease-7drl2026-emscripten
Labels
Clear labels   
Alpha Release Requirement

This issue is a blocker to 0.1 Alpha release of McRogueFace.

  
Bugfix

   
Demo Target

Functionality to demonstrate; Depends on new features, but this issue isn't for writing them.

  
Documentation

   
Major Feature

Significant time and effort required.

  
Minor Feature

Some effort required to create or overhaul functionality.

  
priority:tier1-active

Current development focus - critical path to v1.0

  
priority:tier2-foundation

Important foundation work - not blocking v1.0

  
priority:tier3-future

Future features - deferred until after v1.0

  
priority:tier4-deferred

   
Refactoring & Cleanup

no new functionality, just improving the codebase.

  
system:animation

Animation and property interpolation

  
system:documentation

Documentation infrastructure

  
system:grid

Grid system and spatial containers

  
system:input

Input handling and events

  
system:performance

Performance optimization and profiling

  
system:procgen

Procedural Generation (Noise, BSP, Heightmap)

  
system:python-binding

Python/C++ binding layer

  
system:rendering

Rendering pipeline and visuals

  
system:ui-hierarchy

UI component hierarchy and composition

  
Tiny Feature

quick and easy - a few lines or with little interconnection around the codebase

  
workflow:blocked

Blocked by other work - waiting on dependencies

  
workflow:needs-benchmark

Needs performance testing and benchmarks

  
workflow:needs-documentation

Needs documentation before or after implementation

No labels
Alpha Release Requirement
Bugfix
Demo Target
Documentation
Major Feature
Minor Feature
priority:tier1-active
priority:tier2-foundation
priority:tier3-future
priority:tier4-deferred
Refactoring & Cleanup
system:animation
system:documentation
system:grid
system:input
system:performance
system:procgen
system:python-binding
system:rendering
system:ui-hierarchy
Tiny Feature
workflow:blocked
workflow:needs-benchmark
workflow:needs-documentation
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
#158 [Major Feature] WebAssembly/Emscripten build target for browser deployment
john/McRogueFace
Reference
john/McRogueFace#157
No description provided.