Godot, One Mechanic at a Time (reference folder, grey box, tested mechanics)
/godot-one-mechanic
A GameSkill original for building a Godot 4 game with an agent in an order that holds up: a reference folder with a style-prompt JSON, a grey box, then one mechanic per prompt in its own script with its own headless playtest, re-running every earlier playtest before the next. Ships templates, checkers for the reference folder and project layout, and a tested 2D example (run and jump, then glide across a gap) whose playtests catch a broken mechanic.
- License
- MIT
- By
- By GameSkill
Tested by GameSkill
35/35 checks passed on Godot 4.7.2 (2D physics, headless playtests) + Python 3 standard library (2026-11-03): trigger, a runnable example, a screenshot and self-check, one job per skill, and English + Chinese docs. Trigger checks match prompts against skill descriptions; they are not a live agent run.
Test reportGameSkill's tested copy
Written and tested by GameSkill for gameskill.dev. The ZIP holds the whole skill: SKILL.md and its Chinese version, scripts, a runnable example, tests, the self-check list and our test report.
A GameSkill original, released under MIT. The ZIP keeps LICENSE and CREDITS.md, which lists the workflow inspiration, the CC0 test assets and the third-party libraries with their licenses.
Self-check
- 先写 refs/style.json，每张图写取什么、不取什么 / Write refs/style.json first; every image says what to take and ignore
- 先灰盒，尺寸写成常量 / Grey box first, sizes as constants
- 一个提示只加一个机制，一个机制一个脚本 / One mechanic per prompt, one script per mechanic
- 每个机制的测试同时说明它做什么、为什么需要它 / Each playtest shows what the mechanic does and why it is needed
- 打开新机制后重跑之前所有测试组 / Re-run every earlier playtest group with the new mechanic on
- 机制稳定之前不上美术 / No art until the mechanics hold
Install
Tell your AI
Install the skill from https://gameskill.dev/skills/godot-one-mechanic/install.md
GameSkill's tested copy
mkdir -p .claude/skills
curl -fsSL https://gameskill.dev/dl/skills/godot-one-mechanic.zip -o /tmp/gameskill-godot-one-mechanic.zip
unzip -oq /tmp/gameskill-godot-one-mechanic.zip -d .claude/skills
rm /tmp/gameskill-godot-one-mechanic.zipWhat you get
- The loop: reference folder, grey box, one mechanic per prompt, its playtest, re-run everything
- templates/: style.json (style-prompt JSON), MECHANICS.md (one row per mechanic), mechanic.gd
- tools/check_refs.py: every reference image says what to take and ignore; no 'in the style of'
- tools/check_project.py: one script per mechanic, no rules in the player, a playtest group each, re-runs present
- Cliff Glider grey box: run and jump, then glide across a 300 px gap, 14 headless playtests
Good fit
- Starting a Godot game with an agent so each step is proven before the next
- Adding a mechanic without silently breaking an earlier one
- Turning a folder of reference images into a style the agent can follow
Not for
- A specific mechanic's design: see the mechanic skills
- Unity or Unreal projects: the scripts and playtests are Godot's
Try this prompt
Start my Godot platformer the one-mechanic way: write refs/style.json from my reference images, make a grey box, then add mechanic 1 (run and jump) with its playtests.About this skill
Godot, One Mechanic at a Time is a GameSkill original about the order of work when an agent builds a Godot game. A whole game from one prompt tends to be a game where nothing quite works and nobody can say why. This skill has the agent start from a reference folder and a style-prompt JSON, build a grey box, then add exactly one mechanic per prompt, in its own script, with a headless playtest that proves both what it does and why the game needs it, and re-run every earlier playtest before moving on. Art comes after the mechanics hold.
The example, Cliff Glider, is our own grey box: run and jump, then a glide that is the only way across a 300 px gap. Its tests also break the glide on purpose: a glide that slows the rise passes the old jump tests on their own and is only caught when they run again with the glide switched on. The ideas of building a world from a folder of references and prompting one mechanic at a time come from posts by @sorenxet (link only; no code or text was used). The templates, tools and example are ours.
Related
- glb-godot-acceptance to accept 3D art into the Godot project.
- style-cards to turn the reference folder into checkable limits.
Requirements
- Godot 4.2+ (tested on 4.7.2); playtests run headless
- Python 3 standard library for check_refs.py and check_project.py
Topics
FAQ
Based on Reference folder to world, and one mechanic per prompt (posts, ideas only) by @sorenxet (no licence, idea only, no code or text used). Ideas only: GameSkill wrote the code and text; CREDITS.md in the ZIP lists every source.
Works well with
Skills the author points to as related or as the better fit for neighbouring tasks.
GLB to Godot Acceptance (is this model really done?)
A GameSkill original that decides whether a 3D model is ready for a game: Godot 4 imports the GLB like any file in the project, then checks import errors, triangle budget, size in metres with Y up, origin at the base, materials, colliders, the clips the code plays, a drop test on a floor and runtime errors, with a fix for every failure. Works on any GLB from Blender or an image-to-3D model.
Game Feel & Juice
Add juice to actions: screen shake, hit-stop, eased motion, squash and stretch, knockback and layered audio-visual feedback.
Style Cards (one art style as hard limits, switch looks by switching cards)
A GameSkill original that writes a game's art style down as a card of measurable limits (canvas, colours and palette, alpha, triangles, shading, materials, textures, voxel grid), pastes it into every asset request and checks every asset against it. Ships 12 cards from pixel and one-bit to low-poly, voxel and toon, a no-dependency PNG checker, a Blender GLB checker and a palette locker; switch the whole look by switching the card.
Similar skills
Claude Code Game Studios
Turns Claude Code into a full game studio: 49 agents and 72 workflow skills arranged like a real studio hierarchy.
Awesome Gamedev Agent Skills
77 portable SKILL.md skills across 12 engines (Godot, Unity, Unreal, Phaser, PixiJS, three.js, Bevy, pygame, LÖVE, Roblox, Defold, Ebitengine), with a router.
ForgeSkills
28 gated game-development agent skills (concept, orchestration, verification, Blender headless, reference reconstruction, textures, animation, VFX, lighting, foliage, Godot pipeline) plus Python tools that measure the result. GameSkill hosts the 27 we ran, with the tools. Apache-2.0.
open-game-skills
An MIT pack of about 190 SKILL.md agent skills for game design: combat feel, camera, traversal, world, validation, 2D/Spine and art pipeline, with a dispatcher and adapters for Three.js, PixiJS, Phaser, Cocos, Godot, Unity and Unreal.