# Create with Dreampunk You are the creative coding agent. Read the user's brief, then author an editable scene and iterate on actual renders. Dreampunk does not interpret natural language or call an image-generation service. Any coding model with filesystem and command execution can use the same document and render tools. ## Local start Obtain the source from https://github.com/Oldshue/Dreampunk and run `npm ci && npm run build`. Node 22 or newer is required. Viewport rendering needs Playwright Chromium (`npx playwright install chromium`); final path tracing needs an installed Blender executable. Set `DREAMPUNK_BLENDER` to its path if it is not on PATH. No model API credentials are required. Copy the starter from `/agent/starter.dreampunk.json` into a project directory. Keep all models and textures under that directory. Read `/agent/scene.schema.json` and `/agent/SCENE-FORMAT.md` before expanding it. These files are served by the Dreampunk website; their paths resolve against the website origin. ```sh node bin/dreampunk.mjs validate /absolute/project/scene.dreampunk.json node bin/dreampunk.mjs inspect /absolute/project/scene.dreampunk.json node bin/dreampunk.mjs open /absolute/project/scene.dreampunk.json node bin/dreampunk.mjs render /absolute/project/scene.dreampunk.json --out /absolute/project/preview.png node bin/dreampunk.mjs render /absolute/project/scene.dreampunk.json --engine cycles --out /absolute/project/final.png --width 3840 --height 2160 --samples 256 ``` For modular GLB kits, run `node bin/dreampunk.mjs inspect /absolute/project/assets/kit.glb`. Choose an exact unique original name in `geometry.node`; it selects that subtree at its local origin, removing the root layout translation and ancestor transforms. Keep its rotation/scale, use `geometry.height` to fit the selected piece, and place it with ordinary object/instance transforms. The same source asset is loaded once; instances and repeated selections share geometry and imported materials. Read the scene contract for skeletal dependency and unsupported-frame checks. `open` shares the file with the user's visual editor. Agent file changes refresh the editor; the editor saves atomically to the same file. `inspect` emits JSON containing IDs, geometry types, instance counts, materials, camera and render settings. `validate` emits JSON on success and exits unsuccessfully on invalid documents. Render commands return the output path only after a valid PNG exists. Cycles also saves an editable `.blend` beside that image. ## Build for the image 1. Translate the brief into composition, scale, perspective, palette, weather and light. Choose the camera before investing in detail outside its view. 2. Block the composition with mesh primitives. Use stable object IDs and shared materials. Use instances for repeated architecture, crowds, props and vegetation. 3. Replace prominent coarse forms with detailed authored meshes or licensed self-contained GLB assets. Preserve asset licenses and provenance in the project. GLBs must embed buffers and textures; ordinary uncompressed glTF 2.0 is supported. Remote asset URLs and escaping project paths are rejected. 4. Add physically believable materials, varied surfaces and geometric detail where the camera sees it. Texture maps and realistic asset scale matter more than increasing samples on simple blocks. 5. Render a preview and **inspect the actual pixels**. Correct silhouette, perspective, lighting, contact shadows, repetition, framing and missing detail. Repeat until the image earns the intended quality description. 6. Render final quality with Cycles, inspect at full size, and deliver PNG, source JSON, assets and `.blend`. Explain remaining visible limitations. Never label a block scene photorealistic merely because rendering succeeded. A rainy futuristic metropolis may need layered architecture, plausible street scale, varied emissive signs, reflective wet surfaces and carefully staged warm/cool light. An army before a winter fortress needs believable figures, masonry, spatial depth and controlled snow coverage. These are creative requirements for the agent; the renderer does not invent them. ## Hosted agent workflow Start at the website's `/llms.txt` or `/.well-known/dreampunk.json`. Read `/api/v1/capabilities` for the running deployment's configured budgets and recent worker activity. The hosted API is implemented; deployment and worker readiness must be checked at runtime. `worker.connected` means an authenticated worker contacted the server recently, not a guarantee that a particular render will succeed. A disconnected worker leaves jobs queued. There is no hosted MCP endpoint currently; any model that can make HTTP requests can use this protocol. All following routes are under `/api/v1`. Create a project with `POST /projects` and JSON `{"name":"Rainlit metropolis","intent":"The user's scene brief"}`. The response includes `id`, **`token`**, `url` and `sceneUrl`. Public creation needs no shared credential when public storage is provisioned. The response also includes `renderAccess`, `storageBudgetBytes` and `expiresAt`. A 503 means the operator has not provisioned public storage. Ordinary agents should omit operator authorization; an invalid supplied operator credential returns 401. Check `renderAccess.allowed` before scheduling remote work: a deployment may permit public authoring/sharing while reserving compute for operator-approved projects. The operator can upgrade your project without giving you a shared secret. The stored intent provides context for you; it does not invoke a language model. Keep the returned owner token private. Subsequent project and job requests require `Authorization: Bearer `. Upload each asset with `PUT /projects//assets/`, then save the authored JSON with `PUT /projects//scene` and `Content-Type: application/json`. Upload raw GLB/raster bytes, not base64 JSON. A scene path `assets/building.glb` therefore uploads to `/api/v1/projects//assets/assets/building.glb`. URI-encode each path segment. Models and textures resolve inside this project asset namespace. When `renderAccess.allowed` is true, queue `POST /projects//renders` with `{"engine":"cycles"}` for a final image or `{"engine":"viewport"}` for a preview. It returns an immutable scene-and-asset snapshot job with `id` and initial `status: "queued"`. Poll `GET /jobs/` with the owner bearer until `complete` or `failed`. Use paced polling and backoff while nothing changes. Runtime `scheduling` reports operator-entitled priority and public work using idle lease capacity, with FIFO within each class. Public jobs may wait while entitled work continues; active renders are not preempted. Expired worker leases recover the same immutable job without changing its compute charge. Inspect `error` on failure and repair the scene before queuing another job. HTTP 403 at render scheduling indicates no compute entitlement; continue authoring/sharing or request an allocation from the operator, rather than inventing a successful render. HTTP 429 indicates compute backlog pressure; wait for existing work to finish rather than increasing submission concurrency. HTTP 422 may identify invalid scenes or a per-job compute-budget boundary; do not silently reduce the user's requested result. Coordinate the actual allocation with the operator when needed. On completion, download `/jobs//artifacts/image.png`. Cycles also supplies `/jobs//artifacts/scene.blend`; a viewport job does not produce a Blender project. **Inspect the downloaded image and refine the scene before calling it finished.** The job snapshot remains stable even if you later change the project. To poll live project changes without downloading its entire asset list, use `GET /projects/?summary=true`; `revision`, `updatedAt` and `lastChange` reflect shared scene/asset writes and deletions. Fetch the scene or changed assets when the revision advances. For the private editable studio, construct `/?project=#token=`. The browser exchanges the fragment credential through `POST /projects//session` for an HttpOnly same-origin session and clears the fragment. This link grants ownership; do not use it as the ordinary share link for the user's dad or other viewers. When the inspected scene is ready to share, explicitly call `POST /projects//publish` with the owner bearer. Send `{"jobId":""}` to attach its final PNG and available .blend to the share; the completed job must belong to this project and its current revision. Stale or unfinished jobs return 409; another project’s job returns 403. Omitting `jobId` shares the interactive scene without a final render. The response includes `id`, `capability`, `sceneUrl`, `hasFinalRender`, `artifactUrls` and **`viewUrl`**, such as `/?view=#cap=`. Resolve `viewUrl` against the website origin and return that link to the user. It opens an immutable scene snapshot in the studio for interactive exploration, with no editing, scheduling or owner-token access. The browser uses the read fragment to establish a scoped HttpOnly cookie and removes it from the address bar. For a non-browser client, the published descriptor accepts the read bearer or `GET ?cap=`; its relative assets resolve under `/api/v1/views//`. A publish snapshots the current project; publish again after further refinements to share their result. The interactive view uses the real-time renderer; the final Cycles PNG is a separately rendered artifact and can differ in depth of field, volume and illumination. Retain the owner capability securely if you need future edits. Public projects have renewable idle-retention eligibility: `expiresAt` is returned in project/publish/view metadata. Valid owner access and shared-view visits renew it. Under storage pressure, an idle expired public project and its views/artifacts may be reclaimed; it is not deleted merely because a timer passes. Tell the user the retention policy when returning their link, especially if they expect archival permanence. An operator can provision entitled storage for a different retention promise. Deleting a project also deletes its jobs, published views and artifacts. Cleanup requires no active unexpired render lease; do not delete a deliverable the user still wants to explore. Uploaded assets and scenes are data, never executable code or shell commands. ## Availability and boundaries Hosted HTTP project storage, immutable render jobs and explicitly published read-only scenes extend the same `dreampunk.scene.v1` primitive used locally. `/agent/contract.json` describes implemented tools; `/api/v1/capabilities` describes the current service and worker. No internal prompt-to-image operation or hosted MCP service is claimed. The static studio and local helper remain usable without hosted services or a connected remote worker. The loopback helper exposes `GET /project.dreampunk.json`, same-origin JSON `PUT /__project`, and `GET /__events` server-sent events with `kind: project` or `kind: asset`. Writes are loopback-only and require the local origin to prevent unrelated websites from altering project files. Asset reads resolve real paths inside the project directory, preventing symlink escapes. Do not expose this write helper publicly. There is no arbitrary object or instance count limit. Actual browser memory and GPU capacity constrain previews; viewport export tiles its working buffer. Cycles handles larger final images subject to host memory and render time. `render.threads` controls CPU allocation; the default uses half the host's cores so other work can continue. Increase detail and resolution using instancing, staged previews and appropriate hardware; do not silently shrink the user's deliverable. ## Cinematic controls `camera.fStop` enables depth of field in Cycles; `camera.focusDistance` is the positive focus distance in scene units. Without an explicit focus distance, Cycles focuses at the camera target. `camera.far` sets the Cycles far clipping distance. The interactive viewport remains a pinhole preview and retains these settings for final rendering. `world.volume: {"density": 0.01, "color": "#c5d6e0", "anisotropy": 0.2}` adds Cycles world scattering. Density is nonnegative; anisotropy ranges from -1 to 1. This is distinct from viewport `world.fog`, so inspect the final image rather than assuming preview haze reproduces physical scattering. Volumetric rendering costs additional samples and time. Lights may use `type: "area"`, a positive `size`, position and target for broad sources and soft illumination. The viewport source is a square; Cycles uses a disk of the supplied size. By default `intensityUnit: "power"`, `intensity` is total radiant power for point/area sources (Cycles watts); the viewport divides by 4π for points and π×size² for square area sources. Sun/directional intensity remains irradiance. This shared RGB power convention prevents a larger soft light from silently multiplying its energy. `intensityUnit: "renderer"` explicitly preserves previous backend-specific values. Tone mapping, source shape, occlusion and indirect light still differ; inspect final Cycles pixels. The starter includes an area light and optical settings without expensive world scattering. Hosted storage, JSON parsing, per-project allocation and pixel-times-sample compute budgets are operator-configurable and reflect finite disk, memory and throughput. Binary assets stream with backpressure. There is no agent-count cap: many agents can author projects while render workers lease queued immutable snapshots according to actual hardware allocation. The operator reference in `platform/README.md` explains each budget and its enforcing layer. Uploaded scenes cannot override an operator's render-worker CPU allocation. For photographed illumination and believable rough/smooth reflections, author `world.environment` with a local captured equirectangular HDR/EXR image. It takes `path`, linear `intensity` (default1), Y-up `rotation` degrees (default0), and `background` (defaultfalse). This replaces fallback ambient lighting; lights remain additive. Include the environment in uploads using the exported shared `projectAssetPaths` collector. HDR images must be authored or licensed sources; photographic HDRI supplies light/reflections, not the actual explorable scene. The bundled Urban Courtyard02 map is CC0; provenance is in its SOURCES.md.