Build Locally With an LLM

VibeLands Creator projects are ordinary local source directories. The LLM edits those files, Creator performs deterministic checks, and the hosted Sandbox is the visual multiplayer runtime.

idea → local source → check/test → hosted preview → improve and repeat

The browser is not the authoring source of truth. Keep the project in Git and let the open game tab hot-swap successful local revisions.

1. Bootstrap the project

Run account login yourself. The browser confirmation keeps credentials out of the LLM prompt and transcript:

npm install --global @vibelands/creator
vibelands login
vibelands doctor --json

Check that the short code in the browser matches the terminal before confirming. Do not ask the LLM to inspect Creator's config file or complete the account confirmation for you.

Create a decorative Tier A feature unless the design needs one shared multiplayer truth:

vibelands create neon-garden --json
cd neon-garden
npm install

Use Tier B for shared objectives, collected objects, scores, rewards, persistence, validated interactions, or timers:

vibelands create beacon-quest --tier B --json
cd beacon-quest
npm install
npm test

2. Give the LLM the local contract

Every scaffold contains AGENTS.md. Tell the LLM to read it and the manifest before changing code:

Work in this VibeLands plugin project. Read AGENTS.md and vibelands-plugin.json first. Use only public @vibelands/plugin-sdk/* imports. Keep Tier A deterministic or Tier B server-authoritative as specified. Implement the feature, run the required local checks and report any hosted visual validation that still needs a human.

Creator can provide the exact installed contract without requiring the LLM to guess versions, permissions, limits, entries, scripts, SDK exports, or architecture recipes:

vibelands context . --json
vibelands context . --format agent-md
vibelands context . --write

--write generates .vibelands/CONTEXT.md from the installed SDK declarations and local manifest. The project files and that generated contract are authoritative. Do not ask an LLM to infer host internals from old examples.

3. Use the shortest safe feedback loop

For every source change:

npm run check
npm test          # Tier B

check dry-builds entries without writing dist, rejects host-internal imports, detects bundled React/Three singletons and enforces bundle and asset budgets. Tier B tests run against the deterministic SDK harness without a game server.

When local gates pass:

npm run dev

Open the printed hosted game URL once. Creator keeps the clone and game session stable while successful revisions are applied.

An agent runner that needs structured watch output can use:

vibelands dev . --world-id <world-id> --jsonl

Each stdout line is one event with type, status, build identity, duration and hosted URLs or a failing stage plus message. Other terminating commands use regular JSON:

vibelands check . --json
vibelands serve . --world-id <world-id> --json
vibelands status <build-id> --logs --json
vibelands publish . --metadata review-metadata.json --world-id <world-id> --json

Failed checks return stable diagnostic codes, file/line locations, remediation text and a canonical docs link. Agents should fix the reported location and rerun the same command instead of guessing from a broad build failure.

Optional: start from working source

Open-source Marketplace plugins can be remixed into a fresh local identity:

vibelands remix community-board my-town-board --id my-town-board --json
cd my-town-board
npm install
npm run check

Creator resets the plugin id, version, author and review metadata, records the source identity in forkedFrom, and normalizes package dependencies. The Marketplace source endpoint returns text source; re-add any binary assets the original listing documents separately.

Creator also ships small version-matched capability templates:

vibelands templates --json
vibelands create my-props --template props-pack --json
vibelands create my-quest --template persistent-collectible --json
vibelands create my-crafting --template inventory-crafting --json
vibelands create my-physics-toy --template physics-entity --json

Choose the closest architecture and modify it. This avoids deriving authority, persistence, physics or preview behavior from an empty entry point.

For an older local project, inspect the upgrade before editing:

vibelands migrate . --dry-run --json

Creator only applies migration paths it knows how to validate. Manual source changes are returned as stable file/line diagnostics.

5. Definition of done

• The manifest declares only required permissions.
• Tier A placement uses deterministic SDK helpers.
• Tier B clients send intent; the server validates outcomes and has rejected input plus restart/persistence tests.
• npm run check and required tests pass.
• The hosted clone shows the expected feature with no plugin health errors.
• review-metadata.json explains permissions, privacy, testing and changelog before npm run publish.

The in-game editor remains useful after the feature loads: it places and configures contributed editorItems. It does not replace the local source project.

After a hosted build is available, use the read-only readiness handoff:

vibelands inspect <build-id> --json

It checks build publication, live runtime state, exact revision application, sandbox errors and the build log tail. It returns the game URL and explicit browser assertions. inspect deliberately reports visual verification as a separate step: compilation and runtime readiness do not prove aesthetic success.