hchen272/pixweft

Showcase

Explore different art directions with PixWeft.

Choose your game's style, camera, canvas, palette, and map structure. PixWeft works with TileMaps, freely placed scenes, layered backgrounds, reusable modules, or a mixture.

Versions

Native integrations are developed and tested on Windows. Pixelorama includes its own Godot 4.6.2 runtime, separate from your game's engine.

Skills

Start with $pixweft, or call a specialist directly:

Use the full workflow for a new game or just one skill for a small task. See workflow examples.

Install in Codex

From the plugin directory:

npm ci --ignore-scripts
codex plugin marketplace add .
codex plugin add pixweft@pixweft-local

Open a new conversation and use $pixweft or a specialist. If Codex creates a separate plugin copy, run npm ci --ignore-scripts in that copy too. Keep the package's skills/, shared/, and supporting files together.

Set up a game workspace

Initialize configuration in your game directory:

node scripts/cli.mjs project_init --project /absolute/path/to/game

This creates .pixel-game/project.json for project choices. Put local application paths and connection settings in the ignored .pixel-game/project.local.json:

{
  "tools": {
    "godot_path": "/absolute/path/to/godot-console-executable",
    "pixelorama_path": "/absolute/path/to/Pixelorama.exe",
    "pixelorama_url": "http://127.0.0.1:32124",
    "pixelorama_token": "YOUR_LOCAL_RANDOM_SECRET"
  }
}

You can also use GODOT_PATH, PIXELORAMA_PATH, PIXEL_GAME_PIXELORAMA_URL, and PIXEL_GAME_PIXELORAMA_TOKEN. Set PIXEL_GAME_PROJECT_ROOT to select a game workspace for MCP calls.

Check your setup:

node scripts/cli.mjs doctor --project /absolute/path/to/game

The existing .pixel-game/ and PIXEL_GAME_ names are kept for compatibility.

Artwork workflow

Before generating artwork, PixWeft asks whether you have style reference images. It reuses references or an answer you've already provided; you can also proceed from a written brief.

• Static art: generate an image → directly import into Pixelorama.
• Animation: generate a multi-frame reference sprite sheet → import its frames into Pixelorama.

This covers characters, buildings, props, tiles, UI, portraits, and other game images. Generated pixels stay as imported by default. PixWeft can inspect the result and point out issues; pixel adjustments happen when you request them.

Image generation uses Codex's available image tool or a configured provider. The image_prompt tool prepares the prompt, including reference roles, canvas, scale, transparency, anchors, and animation layout. Editable sources and exports stay linked for later work in Pixelorama and Godot.

Godot and Pixelorama tools

Godot: create and inspect scenes, edit properties, inspect resources, update project settings, and run input/state/screenshot sequences. Operations run in separate engine processes. See the Godot bridge.

Pixelorama: import and export sheets, save and reopen editable .pxo files, preview PNGs, and work with pixels, layers, frames, FPS, and palettes. Follow Pixelorama setup to build and enable the local extension and configure its token and allowed game folders.

Build the extension pack with:

npm run build:pixelorama -- --godot <executable>

MCP entrypoints: project_init, project_inspect, toolchain_doctor, image_prompt, godot_operation, godot_runtime, pixelorama_operation, and run_status.

The CLI uses the same entrypoints. For example:

node scripts/cli.mjs godot_operation --project /absolute/path/to/game --args request.json

With request.json:

{"operation":"scene_inspect","args":{"scene_path":"res://main.tscn"}}

Godot builds use the standard export CLI through game-build. See the bridge documentation for supported operations.

Development

npm run validate
npm test

Checks cover package structure, MCP communication, project isolation, asset measurements, and native application workflows. Native tests can be enabled with local application paths; see validation and the integration lab.

Credits

The skill structure and discussion-to-review approach were inspired by Academic Research Skills. See sources and dependencies. Original plugin code is MIT licensed.

Contact

Have questions, feedback, or ideas? Feel free to reach out at hongliangchen103@gmail.com.