Skip to content
Weld Weld Docs

Your first project

This guide starts a new game from Weld’s Unreal template and takes one feature from idea to main. If your team already has a game on the hub, skip to step 5 after weld clone.

You need: a machine that has joined your hub (Mac or Windows) with Unreal Engine 5.8, and a project on the hub that you own.

  1. Create the game.

    Terminal window
    weld game new SkyForge --engine ue5.8 --style stylized
    cd SkyForge

    The name becomes the project and C++ module name (letters and digits, up to 20). Styles are stylized, realistic and lowpoly; they set the art style guide, default triangle budgets and the starter critic rubric. You get a C++ project already wired up:

    • Epic’s Unreal MCP configured for Claude Code (.mcp.json), and the git source-control settings;
    • automation test scaffolding (Source/SkyForgeTests) and a game debug and automation API so agents can verify their own changes;
    • .weld/project.toml, .weld/scopes.toml, docs/gdd.md, docs/decisions.md and docs/style-guide.md;
    • starter packs in .claude/skills/, including rubric-stylized for the critic loop;
    • a CLAUDE.md for agents, .gitattributes for Git LFS, and an initial commit.

  2. Put it on the hub.

    Link the repo to your project and push it as the hub’s main:

    Terminal window
    weld node link --project "SkyForge"
    weld git setup --push

    weld git setup configures the credential helper, the hub remote and Git LFS, commits the settings it writes and, with --push, pushes your branch as main. Only this first push goes straight to main; after it, changes land through the merge queue. (You can also do all of this in one go with weld game new SkyForge --project <prj_id> --push.)

    No project yet? weld project create "SkyForge" creates one you own and links the repo.

  3. Invite your teammate.

    Terminal window
    weld invite sam@example.com

    It shows what it will do and asks first. The hub creates an invite bound to Sam’s address (single use, 7 days) and emails Sam a welcome with the install steps and the weld node command. Use --role owner for a co-owner. weld invite list shows pending invites and weld invite revoke sam@example.com cancels one.

  4. Map your scopes.

    Open .weld/scopes.toml. The template already maps each feature folder of the game module to a system (Source/SkyForge/Inventory/** → system:inventory), config to system:config, the GDD to doc:gdd and pipeline assets to asset: scopes. Agree on one rule with your teammate: one folder per feature in Source/SkyForge/. That’s what makes overlap warnings precise. See Scopes.

  5. Write the GDD together.

    docs/gdd.md has sections for the pitch, core loop, controls, one subsection per system, levels, art direction, audio and UI. Keep the headings stable: Work items link to them. Record why you decided things in docs/decisions.md.

  6. Turn on the gates.

    Terminal window
    weld node link --t1-command "weld game smoke"     # T1 tests on every merge (each teammate, once)
    weld agents targets code=7 --require-critic false # optional critic targets; keep them modest at first

    See Merge queue and Critic loop.

  7. Start your first Work item.

    Start Claude Code in the repo and describe a feature:

    Terminal window
    claude

    Add a pickup system: coins spawn in the level, the player collects them on overlap and the HUD shows the count. See GDD 5.1.

    Before its first edit, Claude declares a Work item (title, summary, why, approach, scopes) and it appears on the dashboard. The same from a terminal:

    Terminal window
    weld work declare "Coin pickups" --summary "Collectible coins with a HUD counter" \
      --path Source/SkyForge/Pickups/ --gdd docs/gdd.md#5-systems

  8. Let it build and verify.

    Claude implements the feature, builds with weld game build and checks its own work with weld game smoke. Your node pushes a WIP snapshot to the hub about once a minute, so your teammate can see the progress and any predicted conflicts.

  9. Merge it.

    When you’re happy, tell Claude to merge, or:

    Terminal window
    weld merge --commit -m "Coin pickups with HUD counter"

    The merge queue runs T1 (and the critic gate if you set targets), merges into main and marks the Work merged. The result arrives in weld status, your inbox and the dashboard’s activity feed. Your first merged Work item is done.

Next

Section titled “Next”