@pixelvibing/cli 0.0.1 → 0.1.0

package/package.json

@@ -1,19 +1,40 @@
 {
   "name": "@pixelvibing/cli",
-  "version": "0.0.1",
-  "description": "PixelVibing: pixel art game assets from the command line. In development.",
+  "version": "0.1.0",
+  "description": "PixelVibing: pixel art game assets from the command line, and the Skills that teach coding assistants to make them.",
   "license": "MIT",
   "homepage": "https://pixelvibing.com",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/protonspy/pixelvibing.git",
+    "url": "git+https://github.com/Pixel-Vibing/pixel-vibing.git",
     "directory": "cli"
   },
+  "type": "module",
+  "bin": {
+    "pixel-vibing-cli": "dist/pixel-vibing-cli.js"
+  },
   "files": [
+    "dist/",
+    "skills/",
     "README.md",
     "LICENSE"
   ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "npm run build --workspace=@pixelvibing/toolkit && node scripts/build.mjs",
+    "check": "node ../node_modules/typescript/bin/tsc -p tsconfig.json --noEmit",
+    "check:package": "node ../editor/src/main/package-guard.ts dist && node ../editor/src/main/package-guard.ts skills",
+    "test": "node --import ../editor/scripts/test-register.mjs --test \"src/**/*.test.ts\""
+  },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@napi-rs/keyring": "2.1.0"
+  },
+  "devDependencies": {
+    "@pixelvibing/toolkit": "0.1.0"
   }
 }

package/skills/pixelvibing/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: pixelvibing
+description: Make pixel art for this game with pixel-vibing-cli — objects, creatures, level designs and interface art (a HUD, skill and item icons) generated on the PixelVibing platform, listed and pulled into pixelvibing/out/, and sealed into the game's container. Use when the game needs a sprite, a prop, a creature, a level's art, its HUD or its icons, or art already made for it.
+---
+
+# PixelVibing art for this game
+
+This repository is a PixelVibing local project. `pixelvibing.json` at its root names it
+and the platform project it generates for; `pixelvibing/` holds its art. The platform
+keeps every asset, and `pixelvibing/` holds only what was pulled from it. Nothing written
+there is ever sent back: art enters the project only by being generated.
+
+Every command below takes `--json`, which prints its answer as JSON on standard output.
+Progress and errors go to standard error, and a failure exits 1.
+
+## Before anything
+
+1. `pixel-vibing-cli whoami --json` says who is signed in and which platform project
+   this folder generates for.
+   - Not signed in: ask the person to run `pixel-vibing-cli login`.
+   - Never ask for a token, and never write one into a file or a command you show.
+   - No platform project: `pixel-vibing-cli link <project>`, or `link --idea "<what the
+     game is>"` to make one.
+2. Read `pixelvibing/style-guide.md`, or run `pixel-vibing-cli guide show`, before deciding
+   what to ask for. It says what the game is and how its art looks, and every generation is
+   held to it. Write instructions in its terms. The `pixelvibing-style-guide` Skill says
+   when the guide itself should change.
+
+## Generating
+
+```bash
+pixel-vibing-cli generate object --instruction "<what>" --size <cols>x<rows> --yes --json
+pixel-vibing-cli generate creature --instruction "<what>" [--reference <png>]... --yes --json
+pixel-vibing-cli generate level-design --instruction "<what>" --tiles <cols>x<rows> --yes --json
+pixel-vibing-cli generate hud [--pieces <list>] [--instruction "<theme>"] --yes --json
+pixel-vibing-cli generate icons --names "<name>,<name>,..." --purpose <skill|item> [--size <16|32|64>] --yes --json
+pixel-vibing-cli generate hud-mockup --instruction "<the HUD>" --yes --json
+```
+
+Each generation spends the account's credits.
+- **The cost.** The command prints the cost and the balance before it starts. Without
+  `--yes` it asks, and with nobody at the terminal it starts nothing. Tell the person what
+  a batch will cost before you start one.
+- **The instruction.** Describe the thing as a person would: its look, its material, what
+  it is for in the game. Describe the thing itself, not a prompt for a model.
+- **The options.**
+  - `--size` is an object's footprint in whole tiles, `1x1` unless given.
+  - `--tiles` is how many tiles a level design is across, `6x4` unless given.
+  - `--quality` is `low`, `medium` (the default), `high`, `xhigh` or `max`; the higher,
+    the dearer.
+  - `--reference` is a PNG to draw from, repeated for several: at most 8 for an object,
+    3 for a creature, a level design or a HUD mockup, none for a HUD set or icons.
+- **Interface art.** When the game shows the player something over the world, make it here
+  rather than drawing it in code:
+  - `hud` makes a matching set in one generation: `health-bar`, `mana-bar`, `button`,
+    `inventory-slot`, `panel-frame` and `minimap-frame`, all unless `--pieces` names some.
+    Frames, buttons, slots and the minimap frame come with nine-slice insets, so stretch
+    them with the engine's nine-slice sprite rather than scaling them.
+  - `icons` makes up to 16 icons that match, from `--names`: `--purpose skill` for a
+    hotbar or a skill tree (each on a square badge), `--purpose item` for an inventory,
+    potions or loot (each alone). `--size` is 16, 32 (the default) or 64 px.
+  - `hud-mockup` draws one screen with its whole HUD, to agree on the look first; take
+    its pieces out in the desktop editor.
+  - The art never carries text or numbers: draw labels, counts and values in the game.
+- **Success.** The asset is pulled at once. The answer's `files` are where its pictures
+  are, relative to `pixelvibing/`.
+- **Failure.** Too few credits starts nothing and names the page where the person buys
+  more: tell them, and do not retry. A failed job prints its reason.
+
+## Listing and pulling
+
+```bash
+pixel-vibing-cli list [<kind>] --json
+pixel-vibing-cli pull <id|name> [--as <name>] --json
+```
+
+- **Listing.** `list` answers the newest 50 assets. When there are more, it gives a
+  `next` id for `--before`. A kind is the generation that made the asset: `object`,
+  `creature`, `level-design`, `rotate`, `animate`…
+- **Pulling.** `pull` writes an asset of one picture as `pixelvibing/out/<name>.png`, and
+  one of several as `pixelvibing/out/<name>/<n>.png`; a HUD set's pieces as
+  `pixelvibing/out/ui/hud/<piece>.png` and an icon set's as `pixelvibing/out/ui/icon/<name>.png`.
+  It downloads again only when the platform's copy changed.
+- **Collisions.** `pull` never writes over a picture it did not pull. When it refuses,
+  give the asset another name with `--as`.
+- **Using the art.** Use the pictures where they are, or copy them into the game's own
+  asset folders. A copy is not tracked.
+
+## Taking the art into the game
+
+```bash
+pixel-vibing-cli export <default|pixi|phaser|godot> [--out <dir>] --json
+```
+
+- **What it makes.** Every picture under `pixelvibing/out/`, packed into sprite sheets,
+  with the animations, and the map as placed sprites. It goes into
+  `pixelvibing/export/<engine>/`, or `--out`.
+- **The formats.**
+  - `pixi`: a TexturePacker JSON Hash spritesheet per sheet, for `Assets.load`.
+  - `phaser`: a multi-atlas for `load.multiatlas`, and `animations.json` for
+    `anims.fromJSON`.
+  - `godot`: `AtlasTexture` and `SpriteFrames` resources, and `map.tscn`, under the
+    `res://` folder `--godot-root` names.
+  - `default`: plain JSON, for any other engine.
+- **The map.** `map.json` lists each placed sprite, with its frame, its box in world
+  pixels, its level and its layer (`ground`, `object` or `foreground`), in draw order.
+  Place them in that order.
+- **Interface art that stretches.** A HUD frame's nine-slice insets travel with it:
+  `nineGrid` on its frame in `sheets.json`, `borders` on its PixiJS frame (a
+  `NineSliceSprite` reads them), Phaser's `nine-slices.json` (the widths `nineslice()`
+  takes), and a `NinePatchRect` scene under Godot's `nine-patch/`.
+- **Safety.** An export replaces only an earlier export or an empty directory, never a
+  folder of the game's own.
+
+## Sealing
+
+`pixel-vibing-cli seal` builds `pixelvibing/build/assets.eac` from every picture under
+`pixelvibing/out/`, as the editor does, for a game that reads the container.
+
+## By hand
+
+`pixel-vibing-cli editor` opens the PixelVibing desktop app on this project, where a person
+finishes art by hand. Suggest it when a result needs a person's eye rather than another
+generation.

package/skills/pixelvibing-style-guide/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: pixelvibing-style-guide
+description: Keep this game's PixelVibing style guide true as the game grows — read it before generating, and change it when the game gains a place, a palette, a camera or a rule its art must follow. Use when the game's look or scope changes, or when generated art keeps missing the game in the same way.
+---
+
+# The style guide
+
+`pixelvibing/style-guide.md` mirrors the platform project's style guide. The guide is the
+game's source of truth: what the game is, its world, its camera, its palette, its outline
+and shading, its scale in pixels, and what never belongs in it. Every generation the
+platform makes for this project is held to it, so a guide that no longer describes the
+game makes art that no longer fits it.
+
+## When to change it
+
+- The game gains a place, a biome, a faction, an era, or a kind of thing it did not have.
+- The camera, the perspective, the tile size, the palette, the outline or the shading
+  changes.
+- Generated art keeps coming back wrong in the same way.
+- The game gets a rule its art must keep, such as a light that always comes from one side.
+
+Do not change it for one asset: say that in the asset's instruction instead.
+
+## How
+
+1. `pixel-vibing-cli guide pull` writes the current version to `pixelvibing/style-guide.md`.
+   It refuses to write over changes that were never pushed.
+2. Then change it, one of two ways:
+   - **Edit the file.** Keep it prose a person reads. Keep its first fenced block marked
+     `prompt`: that block is the guide's own sentence for an image model. When the rest
+     changes, bring it up to date too. The whole guide is at most 8000 characters.
+   - **Ask the platform.** `pixel-vibing-cli guide revise "<what changed in the game>"
+     --yes` revises the guide by that instruction, keeping what it does not change, and
+     pulls the result. It costs a credit.
+3. `pixel-vibing-cli guide push` keeps the file as the guide's next version.
+   - If the platform's guide moved on since your pull, nothing is kept.
+   - Save your changes aside, run `pixel-vibing-cli guide pull --force`, make them again on
+     top, and push.
+4. `pixel-vibing-cli guide versions` lists every version, with how and when each was made.
+
+Tell the person what you changed and why, since the guide shapes every later generation.
+Art made before the change was made under the old guide, and nothing remakes it by itself.