🎭 PixelGlass — Roblox Studio Frame Oracle

🧭 The Story Behind PixelGlass

There is a peculiar moment that every Roblox Studio scripter knows too well. You launch a playtest, the game boots, everything looks right in the viewport — and then the automation layer asks for a screenshot, and you receive… a rectangle of pure magenta. Nothing else. A flat, unapologetic slab of #FF00FF staring back at you like a joke the engine refuses to explain.

PixelGlass was born from that exact frustration. Not as a patch, not as a workaround duct-taped onto another tool — but as a frame oracle: a component whose entire job is to know where the real pixels live and hand them back, faithfully, frame after frame, playtest after playtest.

While the sibling project focuses on the very specific case of capturing the macOS window by ID during a playtest, PixelGlass generalizes the philosophy into a cross-platform frame acquisition layer. It exists for the tinkerer who asks: "If the engine gives me magenta, what short of the engine can give me the truth?"

The answer, in PixelGlass, is a small orchestration daemon combined with a lightweight client that speaks to headless and windowed runtimes alike.

🎯 What PixelGlass Actually Does

PixelGlass is a frame capture and verification toolkit for automated workflows that need to observe a running graphical application — most notably Roblox Studio playtests, but also any long-lived windowed process where naive capture returns blank or corrupted buffers.

It works by:

1. Enumerating real surfaces — instead of asking the renderer for a buffer it may refuse to produce, PixelGlass enumerates observable windows and surfaces at the OS compositor level.
2. Verifying liveness — a frame that is 100% a single color, all-black, all-white, or matching a known sentinel is flagged as suspect and re-acquired through an alternate path.
3. Normalizing output — every frame lands as a predictable PNG / raw buffer / base64 payload ready for downstream MCP-style consumption.
4. Persisting evidence — optional frame journals let you replay what the oracle saw, with timestamps and checksums, for later debugging.

Think of it as a pixel sentinel standing between your automation and the renderer, refusing to accept the polite magenta lie.

🚀 Capabilities

• 🖼️ Multi-source frame acquisition — compositor-level, window-handle, offscreen buffer, and hybrid fallback chains
• 🔍 Sentinel-color detection — configurable palette of colors that trigger re-capture (magenta by default, obviously)
• 🧩 Device matrix generator — produce a grid of frames across many simulated device profiles in a single call
• 🖥️ Responsive capture UI — a compact control panel that adapts cleanly from phone to ultrawide displays
• 🌍 Multilingual support — interface and diagnostics available in fourteen languages out of the box
• 🕰️ Frame journals — deterministic, replayable frame logs with checksums and metadata
• 🔒 Local-only by default — nothing leaves your machine unless you explicitly export it
• 🧠 Heuristic re-acquire engine — decides how to retry based on what failed the first time
• ⚡ Low-latency pipeline — sub-frame capture cadence suitable for streaming diagnostics
• 🛠️ Plugin surface — write your own acquisition strategies in a few dozen lines
• 🧪 Simulation harness — test capture logic without a live game running
• 📦 Self-contained releases — portable archives with no external dependencies beyond a modern runtime

🌟 Why People Reach for PixelGlass

Most capture tooling assumes the source is cooperative. PixelGlass assumes the opposite: it assumes the renderer will, at the worst possible moment, decide not to cooperate. The design leans into that pessimism and turns it into reliability.

• Predictable under pressure — when a playtest is mid-frame and the compositor is busy, PixelGlass queues intelligently instead of hammering the source.
• Diagnostic-first — every failure comes with a reason code, not just a stack trace.
• Extensible without ceremony — add a new acquisition strategy as a small module, register it, done.
• Respectful of resources — captures are batched and deduplicated; identical frames are not stored twice.

If the sibling project is a scalpel, PixelGlass is a well-organized field kit — a set of instruments, each with a clear purpose, arranged so you can reach for the right one without thinking.

🧰 Architecture at a Glance

PixelGlass is split into three cooperating layers, each independently useful:

1. The Oracle Core (Rust / native)

The heart of the system. Talks to OS-level compositor APIs, manages window handles, and produces the raw frame bytes. Handles sentinel detection at the earliest possible stage, before any expensive encoding happens.

2. The Bridge (Node.js / Python)

A thin translation layer that exposes the Oracle Core to higher-level automation. Speaks JSON-RPC over a local socket, so unrelated processes can request frames without embedding native code.

3. The Control Panel (Web / Electron)

A responsive interface for humans. Configure capture profiles, watch live frame health, inspect journals, and export device matrices as PNG contact sheets.

Each layer can be run alone. You can embed the Oracle Core in your own binary, drive the Bridge from a script, or just use the panel for manual diagnostics.

📐 Design Principles

• Truth over convenience. If a frame looks wrong, say so loudly rather than silently forwarding it.
• No silent fallbacks. Every alternate acquisition path is logged and attributed.
• Composable, not monolithic. Small pieces, clear contracts, replaceable parts.
• Deterministic output. Same input, same bytes, same checksum — every time.
• Local first. Network is opt-in, never implicit.
• Documented failure. Error codes are part of the public API, not an afterthought.

🧪 Sentinel Color Detection — A Closer Look

The signature feature. When a frame is requested, PixelGlass computes a uniformity score across the buffer. If the score crosses a threshold and the dominant color matches an entry in the sentinel list, the frame is marked suspect and the oracle re-acquires through the next strategy in the chain.

Default sentinels:

You can add your own sentinels via the configuration file — anything from a game's UI accent color to a custom debug palette.

🗺️ Device Matrix Generation

One of the most requested features in the sibling project is the device matrix — a grid of frames representing many device profiles. PixelGlass takes that idea and expands it:

• Define profiles as small YAML documents — dimensions, pixel density, safe-area insets, and optional style hints.
• Request the entire matrix in a single call; receive a contact sheet plus per-profile frames.
• Each cell is verified against sentinels independently, so a single bad profile does not poison the whole sheet.
• Export as PNG sheet, individual frames, or a machine-readable manifest with checksums.

The result is a diagnostic artifact you can hand to a designer, drop into a report, or diff against yesterday's run.

🌍 Multilingual Support

The Bridge and the Control Panel ship with translated strings for:

German, Spanish, French, Italian, Portuguese (Brazilian and European), Dutch, Polish, Swedish, Japanese, Korean, Simplified Chinese, Traditional Chinese, and Turkish.

Translations are stored as plain JSON and are trivially editable. If your language is missing, adding it takes minutes — and yes, we genuinely welcome that pull request.

🛡️ 24/7 Support Model

Support for PixelGlass runs on a continuous rotation:

• A status channel updated whenever a release changes behavior.
• Issue triage on a rolling basis, with priority tags for regressions.
• A knowledge base of common failure modes and their resolutions.
• Community discussions for open-ended questions and feature brainstorming.

No question is too small. A magenta rectangle has humbled all of us at least once.

🧑‍💻 Who PixelGlass Is For

• Automation engineers who need reliable frames from a stubborn renderer.
• QA teams verifying that a build actually renders what it claims to render.
• Tooling authors building on top of the MCP ecosystem.
• Curious developers who want to understand what their compositor is really doing.
• Educators demonstrating capture pipelines in a controlled, observable way.

If you have ever written a comment that just says # why is this magenta, PixelGlass was built with you in mind.

🔐 S