Make Your Army

VibeCraft ships with ready-made factions, but you can also bring an army of your own. You describe your people in code, usually by talking to a coding AI. The engine works out what their bodies can do.

How it stays fair: you never set HP, damage, speed or cost. You shape bodies: how heavy a unit is, how much of it is muscle, frame (bone, shell, plate) or reserve, and what crystal weapon it carries. The physics prices the rest. A giant hits hard, but it's also slow, hungry and expensive, so nobody can vibecode an army that's simply better.

1. Get the game running

You need Node.js and git. Then:

git clone https://github.com/mcscope/Vibecraft.git
cd Vibecraft
npm install
npm run dev

Open the address it prints (usually http://localhost:5173). That's your own copy of the game, and every change you save shows up when you reload.

2. Dream up your people

Before any code, decide who they are. Where do they live, what do they eat, how do they fight, and what's strange about them? Frog-folk of the fens, clockwork monks, a hive that grows its buildings... One clear idea makes every later choice easier.

3. Ask your AI to build it

Open the project in a coding assistant (for example Claude Code) and describe your faction. For example:

Make me a new VibeCraft faction: the Ashwalkers, salamander-folk from a volcanic badland.
Copy src/factions/fenfolk as a starting point. I want small fast skirmishers who throw
hot stones, heavy basalt-shelled guards with short spears, and a lumbering lava-tortoise
siege beast. Give them a homeworld of black rock and ember trees, and some wildlife.
Register it in PLAYABLE and the Codex, and follow the rules in CLAUDE.md.

The project's CLAUDE.md and README.md tell the AI how factions work, so it can follow the rules without you explaining them.

4. What a faction is made of

Units: a mass, a physique (muscle, frame, reserve) and an attack: strike or throw, how much crystal, and optionally a spear shaft, a sling or a sidearm. Long bodies have a length and wheel round.
Buildings train units, research techs and store resources. Techs and buildings raise refinement, which makes units cheaper, never stronger.
Art: every unit and building has a small 3D model made from boxes, spheres and limbs. The game bakes it into lit sprites.
Land: your homeworld's ground, trees and deposits, plus the animals that roam it.
New abilities (flying, burrowing, healing...) are added to the engine as generic, data-driven abilities that any faction can switch on. The design space lists ones nobody uses yet.

5. Test it

Codex and Unit Lab show what physics made of each body.
Arena fights any two units on an equal budget and scores every matchup, which is where you find out what your army beats.
Proving Grounds lets you command your army against dummies, and Skirmish puts it against the AI.
npm test checks your faction against the same rules an opponent's game will.

6. Bring it online

Choose Online game, pick a relay and a room code, and share the code with a friend. When the match starts, your faction travels to them as data, and their game re-derives every stat with its own physics. You never need each other's code, and nobody can sneak in cheaper units.

The full details are in the README on GitHub.