dream-loop: AI Dreams Up Target Screenshot, Then Review Agent Iterates 3D Scene to Pixel-Perfect Match

Project Overview

dream-loop

is an Agent Skill — not a library or framework — that codifies a "visual convergence" workflow into rules an agent can execute, backed by two helper scripts. Its core idea: replace vague aesthetic instructions with a concrete target frame generated by an image model, then use an independent review subagent to score each iteration against that target until the 3D scene matches pixel-for-pixel.

Core Workflow: Target Frame as Spec

The process starts by having the image model produce a target screenshot that looks like an actual engine render (not concept art). This frame is saved as .dream-loop/target.png and becomes the sole acceptance criterion. If the user provides a reference image, it is used directly; otherwise the agent generates one. If the agent lacks image-generation capability, it must stop and ask the user for an image or API access rather than guessing.

A key detail: the prompt to the image model must request an "in-engine screenshot" style, avoiding terms like "concept art" that would produce an artistic interpretation instead of a pixel-alignment target. For existing projects, the current render is fed as a baseline so the model produces an improved version rather than a completely different style, preventing drift.

Review Subagent Scoring

Each iteration follows a seven-step loop: implement → self-test → capture screenshot → submit screenshot + target to a fresh-context subagent → process every feedback item → self-test again → evaluate exit conditions.

The review subagent receives four inputs: latest screenshot, target image, previous screenshot and verdict (if any), and a fixed scoring rubric. It scores four dimensions for a total of 10 points:

Composition (0–3) : camera, framing, layout, position and size of major elements.

Lighting (0–3) : color palette, exposure, shadows, contrast, atmosphere, reflections, bloom; overall brightness must match target.

Materials (0–3) : surface texture, roughness, transparency, wetness; no blocky, plastic, overly smooth, or fake appearance unless target shows it.

Details (0–1) : pixel-level scrutiny; not a single pixel should differ.

The review must output decimal scores, list every gap preventing a perfect score ("even a huge list is fine"), and for each gap state exactly what causes the visual impression and what concrete code change will fix it. Vague comments like "this tree looks fake" are forbidden. The review must also stay consistent with prior verdicts but never inflate scores to look good — regressions receive lower scores.

Asset Acquisition Chain

Visual fidelity requires correct assets. The assets-3d.md document enforces a strict four-level fallback chain, explicitly forbidding skipping levels to save time or complexity:

Download ready-made assets — only if user explicitly permits.

Image-to-3D generation — recommended via fal.ai (models tripo3d/h3.1 for large pieces, fal-ai/trellis for small ones) when a Fal key is present.

Blender modeling — uses Blender's Python API if Blender is installed locally.

Procedural code generation — last resort; write code to create geometry and use image generation for textures and normals.

Level 4 is repeatedly emphasized as a last resort, only when it is the sole remaining option or genuinely yields the closest match to the target frame.

Stagnation Detection & Exit Conditions

The loop defines four exit states:

Score ≥ 8 and acceptable framerate — deliver latest screenshot, ask user if they want to continue.

Score ≥ 8 but framerate insufficient — apply lossless optimizations first, then minimal-visual-impact optimizations; re-submit to review to confirm no visual regression.

Approaching stagnation — best score hasn't risen by ≥ 1 point for two consecutive rounds, or review flags the same issue twice. Stop incremental tweaks, step back, redesign the whole scene/approach targeting structural causes (wrong assets, wrong placement, lighting overhaul, camera completely off). Instruction: "don't make small changes, aim for one drastic improvement."

Already stagnant — after a major redesign, review gives same or lower score. Stop burning tokens, hand back to user for judgment on whether current result is sufficient or where it visibly diverges from target.

This design separates "keep trying" from "admit the direction is wrong," a common failure mode in agent loops that otherwise just iterate until token budget expires.

Module Responsibilities

Skill Entry : Detect trigger words and tier, route Plus/Pro, define working directory and contracts.

Pro Workflow : Direct-execution loop: implement, self-test, capture, review, rework, exit decision.

Plus Workflow : Orchestration loop: main agent dispatches subagents to implement, only self-tests and fixes bugs; fixed 3 rounds.

Review Scorecard : Four-dimension 10-point rubric with mandatory actionable feedback.

Asset Decision Doc : Four-level fallback chain with explicit gate conditions for each level.

Fal Integration Recipes : Two verified endpoints, pricing tiers, failure classification and recovery rules.

Queue Helper : Offline pre-check, concurrent submission, state recovery, GLB validation, credential sanitization, idempotency protection.

Preview Service : Static hosting + POST /__capture endpoint to receive browser-captured PNGs, stores latest.png for next-round comparison.

Data Flow: Main Loop & Asset Sub-chain

The main loop handles visual convergence; the asset sub-chain handles material provenance. Both are coupled through the same target frame.

The main loop (Pro workflow) proceeds: user request → image generation creates target frame → lock .dream-loop/target.png → first implementation (layout, materials, lighting, animation together) → self-test (bugs only) → capture via POST /__capture → independent review scores → process feedback checklist → exit decision → if not met, loop back to self-test.

The asset sub-chain (image-to-3D path) extracts clean per-asset reference images from the target frame, selects fallback tier, runs offline pre-check ( fal-batch.mjs check — no API key, no network, no file changes), submits concurrently via Fal's async queue ( queue.fal.run returning request_id and three URLs), collects results (status check, download without credentials), validates GLB 2.0, atomically writes to models/*.glb, then imports into scene and corrects orientation (download success ≠ visual acceptance).

Both chains share the target frame: main loop uses it as overall acceptance standard; asset chain uses it as source for asset decomposition, ensuring aesthetic consistency.

Summary & Use Cases

dream-loop

turns visual convergence into an auditable process: an image-generated target frame replaces fuzzy aesthetic directions, and an independent reviewer turns gaps into an executable checklist. It suits teams building 3D scene demos, game prototypes, or product showcase pages where the output must closely match a reference image, provided the agent has image generation, vision input, and subagent capabilities (e.g., Codex with GPT-6 Astra, or Claude Fable 5.1). The author tested with glm-5.3 and demonstrated a working isometric voxel-style scene with realistic shading, reflective wet floors, and character controls.

References

Project repo: https://github.com/achimala/dream-loop
Official docs: https://github.com/achimala/dream-loop/blob/main/SKILL.md
Fal tripo3d API: https://fal.ai/models/tripo3d/h3.1/image-to-3d/api