Yotsuba Games
Back to Guide
Guide

AI Integration

PixPipeline officially supports the workflow of "having an AI agent build node graphs to mass-produce pixel-art assets". You need an AI agent that can operate files and run commands (Claude Code or similar).

The ai/ folder

The distribution's ai/ folder contains everything an AI needs.

File Contents
README_ja.txt / README_en.txt Setup instructions for humans
FOR_AI_START_HERE.md The AI's entry point — roles and where to look
node_catalog.json Exact specs of every node (generated from the implementation)
custom_node_catalog.json Specs of the official custom nodes
PROJECT_FILE_SPEC.md The .ppl file format
PROJECT_SECURITY_MODEL.md Safe Open, ResourceBroker, and permission boundaries
PROJECT_SIGNATURES.md Optional detached signatures and publisher signing steps
manual/ This manual (for answering usage questions)
LESSONS.md Lessons learned from AI generation sessions
samples/ Working sample projects
skill/pixelart-author/ A skill for Claude Code

Usage: have it produce assets

  1. Launch your AI agent in the distribution folder
  2. Ask something like: "Read ai/FOR_AI_START_HERE.md, then make me a â—‹â—‹ tile"
  3. The AI writes a .ppl, runs it headless, checks the output, and iterates

Usage: have it teach you the tool

  • Ask with the manual's location attached — "Referring to ai/manual/, how do I use Slope Blur?" — and you get answers that match your installed version

Headless runs (autopilot)

.\app\PixPipeline.exe --headless --project .\projects\foo\foo.ppl
.\app\PixPipeline.exe --headless --project .\projects\foo\foo.ppl --validate-only
.\app\PixPipeline.exe --headless --project .\projects\foo\foo.ppl --require-export --fail-on-node-error
.\app\PixPipeline.exe --headless --project .\projects\foo\foo.ppl `
  --read-root .\projects\foo\assets --write-root .\projects\foo\exports
  • Opens the project, evaluates once, runs the export nodes, and exits
  • Run history is kept in user_data/settings/run_history.json and in the in-app run history dialog (the clock icon in the header)

The run history dialog listing headless runs with status and duration

  • Job files are supported too (parameter overrides, timeouts)
  • Nodes, parameters, connections, and the variant library are strictly validated by default
  • For AI-authored graphs, semantic checks, and CI, add --fail-on-node-error so evaluation failures from ordinary nodes also produce a nonzero exit
  • --capture 12:output=debug.png saves any intermediate image without adding export nodes
  • --user-data <dir> points automated runs at a dedicated user-data location
  • Filesystem access for nodes is granted by the job/CLI's --read-root / --write-root, never by the project itself
  • Native parsers (external fonts etc.) require an explicit --allow-native-parsers. Runs with missing grants record the blocked resource and exit non-zero instead of pretending success
  • .ppl.sig.json is optional; signatures never grant filesystem permissions

Accumulating knowledge

  • Usage lessons from AI sessions accumulate under user_data/ai/ and survive updates
  • Tool bugs and feature requests are filed separately in user_data/ai/AI_FEEDBACK_BACKLOG.md
AI Integration — PixPipeline User Guide